chineur

Chiffrage d'un projet entier au meilleur prix livraison comprise, neuf et occasion séparés, avec un plan de commande groupé qui minimise le total réellement payé.

Le moins cher article par article n'est pas la bonne réponse : 10 articles chez 10 marchands, c'est 10 frais de port. Le moteur de panier groupe les achats chez 2 ou 3 marchands, seuils de franco compris, et affiche l'écart avec ce total naïf.

Installation

python -m venv .venv && ./.venv/bin/pip install -e .
./.venv/bin/pytest          # 74 tests hors ligne, aucun réseau

Python 3.11 ou plus. Le projet tourne sans aucune clé : LeDénicheur, AliExpress et Leboncoin ne demandent rien. Les sources à clé (eBay, Mouser) restent simplement éteintes, et list_sources() le dit.

Clés

Aucun secret n'est lu dans un fichier versionné. bin/chineur-mcp.sh charge un .env local s'il existe (ignoré par git), sinon il prend l'environnement tel quel, ce qui permet de les injecter depuis un gestionnaire de secrets par simple substitution, la valeur ne transitant alors que par l'environnement du processus :

export EBAY_CERT_ID=$(votre-cli-de-coffre get password 'eBay - API Browse')

Variable	Rôle	Sans elle
EBAY_APP_ID / EBAY_CERT_ID	keyset eBay Browse	source eBay éteinte
MOUSER_API_KEY	clé Mouser Search API	source Mouser éteinte
FLARESOLVERR_URL	recours navigateur sur mur anti-bot	recours éteint, le reste fonctionne
CHINEUR_VAR	répertoire d'état (cache, quotas, cookies, journal)	<dépôt>/var

Utilisation

Exposé en MCP stdio (bin/chineur-mcp.sh), trois outils :

Outil	Rôle
price_project(articles, zipcode?, used_threshold?, detail?)	chiffre une liste complète en un seul appel
best_price(article, …)	le cas à un seul article, en detail="full"
list_sources()	état, quota horaire restant et coupure en cours de chaque source

Chaque article accepte une quantité ou un plafond : "LD2410C x3", "ESP32-S3 <=12€".

En ligne de commande :

python -c "
import asyncio; from chineur.models import Project
from chineur.search import Orchestrator; from chineur.report import render
async def m():
    o = Orchestrator(); print(render(await o.run(Project.build(['LD2410C x2','BME280'])), failures=o.failures))
asyncio.run(m())"

Sources et ce qu'elles valent

Source	Volet	Port	Remarque
LeDénicheur	neuf + occasion	exact	agrégateur : apporte Amazon, Cdiscount, Fnac, Rue du Commerce, Back Market, Rakuten en une requête
AliExpress	neuf	estimé	seule source réaliste pour les modules chinois de niche
Leboncoin	occasion	estimé	10 recherches/heure maximum, non négociable
eBay	neuf + occasion	exact	API Browse officielle, active depuis le 2026-08-06
Mouser	neuf	estimé	distributeur pro, API officielle. Couvre ce qu'AliExpress rate (étain, tresse, résistances, transistors, connectique). Inutile sur les modules chinois : absent, ou 3 à 5x le prix

Limites connues, mesurées le 2026-08-05 et non contournables sans Playwright (V2) :

• AliExpress ne donne ni le vendeur ni le port sur la page de recherche, et la fiche produit en HTTP simple est vide. Le groupage se fait donc au niveau de la plateforme, avec son seuil de franco. Après plusieurs requêtes rapprochées, AliExpress répond 200 avec une page de 2 Ko : c'est détecté et traité comme un blocage, pas comme une absence d'offre.
• Le budget AliExpress est d'environ 6 requêtes par IP fraîche, mesuré le 2026-08-10 après 46 h sans aucune sollicitation : 6 articles servis (133 offres), blocage au 7e, FlareSolverr mis au mur lui aussi. Une liste de 17 articles ne peut donc pas être chiffrée en une fois par scraping, quelle que soit l'attente respectée. C'est la limite structurelle qui justifie l'API affiliée officielle (portals.aliexpress.com), et non un réglage de patience à trouver.
• En occasion, le prix est indicatif. Les annonces Leboncoin sont du texte libre : un résultat peut être un lot, une pièce cassée ou un accessoire. Neuf et occasion ne sont jamais fusionnés en un prix unique.
• Le port est marqué ~ quand il est estimé (table shipping.py) et ? quand il est inconnu. Un total contenant une estimation est signalé comme tel.

Pertinence : le vrai facteur limitant

Mesuré le 2026-08-08 sur la liste type réelle (17 articles, composants) : les « introuvables » ne venaient pas d'un manque de sources mais du libellé. Deux causes distinctes, séparées en comptant les titres bruts rendus par eBay avant filtrage.

La requête est trop longue. « etain soudure 60/40 flux 0.8mm » fait renvoyer 0 résultat par eBay ; « etain soudure » en renvoie 11. Chaque mot descriptif ajouté rétrécit le résultat jusqu'au vide. D'où reduced_query et la seconde chance de guarded_search : quand une source ne rend rien, on retente une fois sur un libellé réduit aux références et aux deux premiers mots porteurs, les qualifiants jetés. Une requête de plus uniquement en cas d'échec, et jamais sur le dernier crédit du quota.

Le filtre jetait du bon. « cables dupont assortiment » contre « Câble Dupont … Assortiment 5 à 100pcs » tombait à 0.67 pour un seuil de 0.70 : le score ne comparait que par inclusion de chaîne, donc le pluriel cassait tout. _apparie rapproche désormais sur le préfixe commun (60 % du mot), réservé aux mots d'au moins 4 lettres — jamais aux nombres ni aux références courtes, pour que « 2410 » et « 2420 » restent deux capteurs différents.

Résultat sur la même liste : eBay passe de 10 à 14 articles couverts sur 17, articles sans aucune offre de 5 à 3. Restent trois vrais introuvables, à toutes les sources : la plaque pastillée, le Diese 2201M et la Sugon 8620DX.

Le prix à payer, et il est réel. Une recherche élargie répond à une question plus large que celle posée : « ESP32-WROOM-32 DevKit 38 broches » élargi en « esp32 wroom 32 » remonte un modèle 30 broches. Toute offre issue d'un élargissement porte donc la réserve « recherche élargie à « … » », qui doit rester visible jusqu'à l'affichage.

Recours navigateur (FlareSolverr)

Le point faible du projet : AliExpress est la seule source des modules chinois, et elle se fait bloquer au bout de 5 à 9 recherches. Le README annonçait ce trou comme « non contournable sans Playwright (V2) ». Il l'est, sans dépendance supplémentaire côté projet : une instance FlareSolverr pilote un vrai Chrome, exécute le JavaScript et porte une empreinte de navigateur complète. Elle se déclare par FLARESOLVERR_URL ; non renseignée, le recours est simplement éteint.

Mesuré le 2026-08-08, alors que le connecteur direct était bloqué et son disjoncteur ouvert : fr.aliexpress.com/w/wholesale-LD2410C.html rend HTTP 200, 832 Ko, aucun marqueur anti-bot, et le parseur HTML existant y décode 60 articles avec prix en EUR. Aucune modification du parsing n'a été nécessaire.

Branchement dans AliExpress._items : sur mur anti-bot ou page tronquée, on tente le recours avant de lever Blocked. Points de conception :

• Recours, pas régime. Chaque appel démarre un Chrome : c'est lent et lourd. On n'y passe que sur un blocage avéré.
• None et pas [] quand le recours ne donne rien. Une liste vide passerait pour « aucun résultat », le disjoncteur ne s'ouvrirait pas, et le connecteur retaperait la source bloquée à l'article suivant en aggravant le bridage.
• Jamais bloquant. flaresolverr.fetch ne lève pas : une panne du solveur masquerait la vraie cause derrière un incident d'infrastructure. FLARESOLVERR_URL= l'éteint.
• Abandon après 2 échecs consécutifs. Voir la limite ci-dessous : sans ça, chaque article suivant paierait encore des dizaines de secondes d'attente pour rien.

Sa limite, mesurée le 2026-08-08. Le recours n'est pas un contournement, c'est un second budget. Sur huit recherches AliExpress enchaînées : six servies à 60 articles chacune en 4 à 6 s, la septième en erreur 500 après 101 s d'attente, la huitième renvoyant le mur anti-bot (208 Ko, marqueur RGV587). L'IP de sortie ne change pas, donc le même mur finit par tomber. Deux conséquences dans le code : maxTimeout ramené de 90 à 45 s, et un mur rendu en HTTP 200 compte comme un échec, sinon le compteur d'abandon ne se déclencherait jamais.

En pratique le budget AliExpress passe donc d'environ 9 recherches à environ 15, avec 60 articles par page au lieu de 20. C'est un gain net, ce n'est pas l'illimité.

Garde-fous anti-ban

L'IP de sortie est unique et résidentielle : un ban la coupe entièrement. Tout le module est écrit pour ne jamais en arriver là.

• Quotas horaires persistés en SQLite (var/chineur.db) : Leboncoin 10/h, LeDénicheur 30/h, AliExpress 20/h, eBay 200/h, Mouser 60/h (quotas API, aucun risque IP).

• Espacement sérialisé par source, pas un simple sleep : l'orchestrateur lançant tous les articles en parallèle, des délais concurrents s'écouleraient en même temps et les requêtes partiraient quand même en rafale. Chaque départ attend le précédent.

• Disjoncteur sur 403 / captcha / page tronquée : 1 h, 2 h pour AliExpress, dont la pénalité persiste au-delà de la rafale qui l'a déclenchée.

• Le blocage AliExpress n'est ni un quota ni une question de cadence. Trois recettes du 2026-08-06, libellés jamais mis en cache :

  espacement	transport	servies avant blocage
  6-12 s	requêtes nues	5 (blocage à 46 s)
  6-12 s	session à cookies	6 (blocage à 56 s)
  45-60 s	session à cookies	2 (blocage à 108 s)
  2,5 s	session à cookies, endpoint JSON	9 (blocage à 30 s)

  Ralentir dégrade le rendement, donc la cadence n'est pas le levier : le meilleur rendement s'obtient en allant vite. Le blocage dure ~40 min, mesuré deux fois, et se signale par FAIL_SYS_USER_VALIDATE / RGV587_ERROR::SM, l'anti-bot d'Alibaba qui exige une validation.

• Les articles sont lus sur l'endpoint interne POST www.aliexpress.com/fn/search-pc/index (celui que la page de recherche appelle elle-même), charge utile de forme mods, depuis une session déjà ouverte sur l'accueil. Il rend exactement les mêmes objets article que la page HTML, en .data.result.mods.itemList.content, pour 390 Ko au lieu de 600. Piège : plusieurs blocs de la réponse portent une clé content, celui des filtres de recherche arrive avant itemList. La page HTML reste en repli automatique, mais uniquement si la réponse n'a plus la forme attendue : sur un mur anti-bot, retenter en HTML depuis la même IP ne ferait que gaspiller une requête.

• Session persistante (transport.Session) conservée pour AliExpress : page d'accueil visitée une fois, cookies rejoués ensuite, pot dans var/cookies/ pour survivre à un redémarrage, jeté dès qu'une page revient tronquée. Aucun gain mesuré sur le blocage, gardée parce qu'elle rapproche le trafic de celui d'un navigateur.

• Piste non tranchée : si l'endpoint interne se referme un jour, sous-traiter la source à un service hébergé (omkar.cloud, 5 000 requêtes/mois gratuites), au prix d'un tiers qui voit nos recherches.

• Cache consulté avant le rate limiter : rechiffrer un projet ne retape rien. TTL 1 h par défaut, mais jamais plus court que la coupure du disjoncteur (Connector.effective_ttl, 6 h pour AliExpress). Sans ce plancher, un projet plus large que le budget d'une source ne peut pas se terminer : la relance d'après-coupure retrouve un cache vide, refait les mêmes premières recherches, rebrûle le budget et se fait rebloquer, indéfiniment. Sauf eBay, exclu du cache pour rester conforme à l'exemption (voir plus bas).

• Un projet dépassant le quota Leboncoin est traité par ordre d'enjeu décroissant, et les articles non traités sont nommés dans la restitution.

Économie de tokens

Le calcul reste en Python, seul le verdict remonte : sortie en texte tabulaire dense, une meilleure offre neuve et une occasion par article, titres tronqués, URL nettoyées, notes regroupées, diagnostics dans var/chineur.log. Mesuré : 10 articles ≈ 650 tokens.

Tests

pytest              # 74 tests hors ligne, aucun réseau
pytest -m network   # 5 tests d'intégration réels (consomment du quota)

Le moteur de panier est entièrement testable hors ligne, y compris ses cas piégeux (seuil de franco déclenché par le groupage, marchand unique, article sans offre, égalités). La propriété « total optimisé ≤ total naïf » est vérifiée sur 50 jeux d'offres aléatoires.

Mouser

Une seule variable : MOUSER_API_KEY. Clé gratuite en self-service sur mouser.com/api-hub (onglet Search API).

La clé doit être créée depuis mouser.fr. La recherche par mot-clé n'accepte aucun paramètre de devise (vérifié dans le swagger api.mouser.com/api/docs/V1) : la devise est celle du site d'inscription. Une clé créée sur mouser.com renvoie des dollars, que le connecteur écarte plutôt que de les convertir à un taux inventé — la source paraîtrait simplement vide.

Quotas annoncés par Mouser : 50 pièces par appel, 30 appels/minute, 1 000 appels/jour. D'où limit_per_hour = 60 et 2 s d'espacement : ce n'est pas de l'anti-ban, c'est le respect du quota.

Trois choix de fond :

• mouserPaysCustomsAndDuties: true — Mouser expédie du Texas. Sans ce drapeau, les droits de douane arrivent après coup et un prix « moins cher » sur le papier devient plus cher à la livraison.
• searchOptions: InStock — une référence à 12 semaines de délai n'a rien à faire dans une comparaison de prix pour un projet en cours.
• Paliers de prix suivis à la quantité demandée. Retenir le palier 1 surestime tout achat groupé de composants passifs.

Les deux pièges qui fausseraient une comparaison, tous deux signalés en réserve sur l'offre : le minimum de commande (0,10 € l'unité par sachet de 100, soit 10 € réels à la caisse) et le format de prix (« 0,096 € » est un prix à trois décimales, « $1,250 » vaut mille deux cent cinquante — un parseur naïf se trompe d'un facteur mille dans les deux sens).

Port : non vérifié. Le franco de 50 € HT et les ~20 € en dessous sont recoupés sur le web (2026-08-07), pas sur une facture. Ils vivent donc dans shipping.py et ressortent en ESTIMATED, jamais en fait établi. À corriger dès la première commande réelle : sous le franco, le port écrase le gain, et c'est ce seuil qui décide si la source sert à quelque chose.

eBay

EBAY_APP_ID (App ID) et EBAY_CERT_ID (Cert ID), pour un keyset Production — le seul exploitable. Un keyset Sandbox se branche avec EBAY_ENV=sandbox, qui bascule sur api.sandbox.ebay.com. En sandbox le connecteur reste éteint : l'inventaire est factice, les prix entreraient dans le panier sans que rien ne le signale. EBAY_SANDBOX_OK=1 le rallume pour tester la plomberie uniquement.

Vérifié le 2026-08-06 sur un keyset Production : jeton client_credentials obtenu, recherches réelles (29 offres sur « cable hdmi 2.1 2m », port exact lu dans shippingOptions).

L'état de l'article se lit sur conditionId, jamais sur condition : ce dernier est traduit par eBay (« Neuf », « Occasion », « Ouvert (jamais utilisé) » sur EBAY_FR), et la table à clés anglaises d'origine ne matchait rien, donc tout ressortait en occasion. Les articles 7000 (« pour pièces ») sont écartés : à 3 €, un article cassé gagnerait la comparaison sans que rien ne le signale.

Conformité (« Your Keyset is currently disabled »). eBay n'active un keyset Production qu'après abonnement aux notifications de suppression de compte, ou exemption. Le projet prend l'exemption « je ne conserve pas de données eBay », et le code la rend littéralement vraie : EBay.cacheable = False, donc aucune réponse eBay n'est écrite dans var/chineur.db (elles contiennent des pseudos vendeurs). Un test le verrouille. Si un jour on remet eBay en cache, l'exemption devient fausse : il faudra héberger l'endpoint de notification à la place.

Licence

MIT, voir LICENSE.