Que fait d1-cli — Tiendas D1 depuis la ligne de commande ?
D1 est la plus grande chaîne de hard-discount colombienne. Sa vitrine fonctionne sur
VTEX IO (compte d1tiendas), ce qui signifie que l'API publique du site est la surface
d'intégration — ni scraping, ni identifiants admin.
Invocation
cd skills/commerce/d1-cli
# 1. Définissez d'abord votre point de livraison — tout le reste en dépend
bun run src/cli.ts region --lat 4.6486 --lng=-74.0628
# 2. Ensuite, recherchez : les prix et le stock sont ceux de votre magasin, pas du pays
bun run src/cli.ts search leche entera --count 5
bun run src/cli.ts search --facets category-1/lacteos-y-huevos --sort price:asc
# 3. Devis d'un panier sans toucher à votre chariot
bun run src/cli.ts quote 262:2 892:1
# 3b. Ou laissez un budget décider — termes, pas SKU
bun run src/cli.ts basket --budget 30000 arroz leche aceite huevos
# 4. Ou construisez un vrai panier, puis confiez le paiement à un humain
bun run src/cli.ts cart add 262 --qty 2
bun run src/cli.ts cart deliver-to
bun run src/cli.ts cart checkout # affiche une URL ; ne paie pas
Ajoutez --json à n'importe quelle commande pour une sortie lisible par agent. Les codes de sortie sont un contrat, et cette liste est la seule copie :
| code | signification | réessayer ? |
|---|---|---|
0 | ça a fonctionné | — |
1 | D1 a refusé ou était injoignable — point non livrable, SKU indisponible ou inconnu, panne | oui, peut aider |
2 | la commande a été mal invoquée | ne sert jamais à rien |
3 | ça a fonctionné et la réponse est « vide » (substitute, basket) | ne sert jamais à rien |
Un agent qui ne peut pas faire la différence entre ces codes réessaiera une faute de frappe pour toujours ou abandonnera sur une panne temporaire. 3 existe car une catégorie vide n'est ni l'un ni l'autre.
Notez que cart add fixe la ligne à --qty ; il n'ajoute pas. C'est la sémantique de D1, vérifiée en direct.
Les deux choses qui rendent naïve l'automatisation de D1 erronée
La disponibilité est régionalisée. Interrogez le catalogue sans région et D1 répond depuis le catalogue national, signalant un confortable 10 000 unités pour le vendeur fictif 1. Passez le même SKU dans une simulation de commande pour une adresse réelle et il revient withoutStock, car le magasin physique qui le livrerait ne l'a pas en stock. Toujours d1 region d'abord ; la CLI prévient en texte clair chaque fois qu'elle affiche les prix nationaux.
Définir une région est aussi la partie la moins intuitive de l'API : les coordonnées s'envoient en geoCoordinates={lon};{lat} — séparé par un point-virgule, longitude en premier. Une virgule, ce que les propres corps JSON de VTEX utilisent pour la même paire, est rejetée par CHK0119 (« les adresses doivent avoir un code postal ou des géocoordonnées ») — un message qui donne l'impression que le paramètre manque plutôt qu'il n'est mal formé. test/region.test.ts verrouille ce comportement pour qu'un nettoyage ne puisse pas le défaire.
Les prix arrivent dans deux unités. Pour SKU 262 (Leche Entera Latti 900 ml, COP 3 500 en rayon) :
| API | Champ | Valeur | Unité |
|---|---|---|---|
| intelligent-search | Price | 3500 | pesos entiers |
| catalog_system | Price | 3500.0 | pesos entiers |
| checkout orderForm | sellingPrice | 350000 | centièmes |
Aucun ne libelle son unité. catalog.ts normalise tout en centièmes à la frontière pour que le reste du code ait exactement une unité, et un test vérifie qu'un prix issu de la recherche s'affiche identique à un prix issu du checkout.
Ce qu'il ne fera pas
d1 construit et tarife des paniers. Il ne paie pas. d1 cart checkout affiche l'URL où un humain examine le total et finalise le paiement.
Cette limite est vérifiée à deux endroits à partir d'une seule liste (src/endpoints.ts) :
à l'exécution, D1Client.request refuse toute requête dont l'URL résolue n'est pas l'origine de D1
plus un des 18 chemins approuvés avant que la requête ne quitte le processus ; statiquement,
test/safety.test.ts échoue si un littéral /api/ sous src/ n'est pas approuvé. Ajouter un endpoint — paiement ou autre — échoue tant qu'il n'est pas listé, donc la décision est prise plutôt que prise par défaut.
La partie à l'exécution est critique et a été ajoutée après qu'une revue a montré qu'une analyse statique seule ne suffit pas : --facets '../../../..' résolvait hors de l'endpoint de recherche vers le règlement des commandes alors que tous les littéraux source restaient approuvés.
Dit précisément, car les versions précédentes de ce fichier exagéraient : rien ici n'empêche un contributeur ayant un accès en écriture de modifier la liste blanche. Aucun test dans le dépôt ne le peut.
Le seul identifiant qu'il stocke est un token de session de la boutique — la même chose qu'un navigateur connecté possède, limité aux propres commandes et panier de son propriétaire — écrit dans ~/.config/d1-cli/session.json avec le mode 0600. Aucune appKey/appToken admin VTEX n'est lue nulle part. La connexion se fait par code unique envoyé par email ; l'authentification par mot de passe n'est intentionnellement pas implémentée.
La porte de sortie du checkout — terminez toujours ici
Terminez chaque panier par d1 cart checkout et agissez sur son code de sortie. Pas comme une formalité : c'est la seule commande qui revérifie tout le panier auprès de D1 tel qu'il est maintenant, et les paniers deviennent obsolètes d'une manière qu'aucune autre commande ne révèle.
0 chaque ligne est livrable — l'URL peut être remise en toute sécurité
1 au moins une ligne NE PEUT PAS être livrée ; l'URL est imprimée mais le panier est cassé
2 la commande a été mal invoquée
Ceci existe parce que chacun de ces cas est arrivé sur un vrai panier :
- Une ligne s'est vendue pendant la nuit.
PAN ARTESANAL INTEGRALest devenuno tiene inventariodes heures après avoir été ajouté. Le panier s'affichait toujours, avait toujours un total — un total qui était silencieusement inférieur de 6.490 COP, car la ligne morte avait disparu. - Un changement d'adresse a bloqué chaque ligne. Neuf articles sont revenus
cannotBeDeliveredalors que chacun portait encore un SLA valide et que le panier affichait toujours un total payable. - La livraison a été sous-estimée de 12 fois par une allocation par ligne qui ressemblait à un total.
Dans les trois cas, le panier semblait correct. Un devis pris plus tôt dans une session n'est pas une preuve sur le panier actuel, donc ne remettez jamais une URL de checkout que vous avez obtenue avant la dernière mutation — relancez la porte.
Quand elle retourne 1, --json donne undeliverable[] nommant les lignes, et readyToCheckout: false. Supprimez ou remplacez ces lignes et relancez.
Remplacer une ligne que D1 ne peut pas fournir
d1 substitute 192 --limit 5 # classe les produits en stock de la même catégorie
Le code 0 signifie qu'il y a quelque chose à proposer ; 3 signifie qu'il n'y a rien — une des deux commandes qui utilisent 3, aux côtés de d1 basket.
Trois, pas un, et la distinction est le point : 1 signifie « D1 a refusé, ou n'a pas pu être joint » partout ailleurs dans cette CLI, et invite à réessayer. Une catégorie vide ne devient jamais non vide en réessayant, donc un agent avec une politique de réessai sur 1 bouclerait indéfiniment. Le code 0 avec une liste vide est l'autre mauvaise réponse — il se lit comme un succès et déclenche une action.
Chaque candidat nomme ce qui change : marque, taille d'emballage, $/kg ou $/L, prix de l'emballage, et tout avertissement Ley 2120 gagné ou perdu. C'est la sortie, pas le score. Un -12% par litre pour les mêmes 900 ml et la même étiquette est une proposition différente de celle qui arrive avec Exceso en Azúcares attaché, et seuls les écarts les distinguent.
Proposez-le ; ne l'acceptez pas. substitute n'écrit jamais — il imprime la commande d1 cart add pour approbation humaine. Ce n'est pas de la prudence gratuite : le client a préféré à deux fois supprimer une ligne plutôt qu'un mauvais substitut, l'a dit explicitement, et avait raison les deux fois. Présentez les candidats et les compromis ; laissez la personne décider, et soyez prêt à supprimer la ligne.
Trois choses qu'il vous dira qui valent la peine d'être lues :
- « Ce produit est encore en stock dans votre magasin. » La disponibilité est par magasin, donc une ligne qui a échoué ailleurs peut être acceptable ici. Vérifiez avant de remplacer quoi que ce soit. Sans
--lat/--lng, il le dit plutôt que de deviner — il n'y a pas de magasin pour lequel faire une déclaration par magasin. - « élargi au niveau 2 sur 3 » — la catégorie feuille n'avait rien en stock, donc les suggestions viennent d'un rayon plus large et sont donc moins pertinentes.
- « seuls N ont été comparés » — la catégorie est plus grande qu'une page. Augmentez
--count. Ceci s'affiche aussi sur le résultat vide, car « rien ici n'est en stock » affirmé sur un balayage partiel a encore plus besoin de cette nuance.
Trouver des trucs quand la demande est vague
Pour « il nous faut du riz » plutôt que « acheter SKU 1092 », deux axes comptent et aucun n'est le défaut :
Classez par prix unitaire, pas par prix d'emballage. --sort per-unit utilise les données PUM que la loi colombienne oblige D1 à publier. Les deux classements divergent véritablement : ARROZ ESTÁNDAR 500 GRS est l'emballage le moins cher à 1 550 $ et coûte 3 100 $/kg, tandis que la meilleure valeur dans les mêmes résultats est à 2 775 $/kg — dans un sac de 5 550 $ qui n'apparaît nulle part dans le top cinq des prix d'emballage. Classer par prix d'emballage donne une mauvaise réponse tout en ayant l'air correct.
Comme la recherche de D1 ne peut pas trier sur ce critère, --sort per-unit ordonne la page que vous avez récupérée, pas l'ensemble des résultats. Augmentez --count (max 50) pour l'élargir. La sortie le dit plutôt que d'impliquer un superlatif qu'elle ne peut pas soutenir, et nomme combien de résultats ne publient pas de taille et ne peuvent donc pas être comparés du tout.
La taille déclarée d'un multipack est celle de l'emballage, pas d'un article — ne la « corrigez » pas. Un recensement de tous les 1 600 produits a trouvé que parmi les multipacks identifiables par nom, 44 des 46 où D1 en dit assez pour décider déclarent le total de l'emballage. Analyser N UN dans un nom de produit et multiplier corromprait ces 44 pour en corriger 2. Le nombre dans un nom n'est pas une preuve de ce que signifie le PUM.
resolvePackSize lit donc les descriptions plutôt que les noms. Sur les 1 548 produits portant un PUM, il agit sur les 10 dont la description indique à la fois une taille par article et un nombre : trois sont corrigés (SKU 718, 510, 1008), sept sont confirmés comme indiquant déjà l'emballage, et tout le reste reste tel que déclaré.
Lisez les étiquettes d'avertissement. Les produits portent les avertissements colombiens sur le devant de l'emballage (Exceso en Azúcares, Exceso en sodio, Exceso en grasas saturadas, Exceso en grasas trans, Contiene Edulcorantes) dans warnings[] avec --json. La couverture est partielle — environ 70–90 % par catégorie — donc l'absence signifie « non déclaré », jamais « sûr ».
Ensuite, affinez avec d1 facets <query> (catégorie, marque, sous-catégorie avec décomptes) avant de paginer : la recherche est limitée à 50 pages, donc une requête large est mieux réduite par facette que parcourue.
Commandes
| Commande | Ce qu'elle fait |
|---|---|
region --lat --lng | résoudre et mémoriser le point de livraison |
search <query> | trouver des produits (--facets --sort --count --page --available) |
suggest <partial> · trending | autocomplétion · ce que la Colombie recherche |
categories · facets [query] | arbre des rayons · filtres pour une requête |
substitute <sku> | quoi acheter à la place, et ce qui change (--limit --count) |
quote <sku>[:qty]... | tarifer un panier, sans modifier le chariot |
| `cart [show | add |
login --email / --from-cookie · whoami · logout | compte |
orders · order <id> | historique des commandes (les détails sont réduits à une liste blanche ; --raw opte pour le brut) |
stores near | magasins D1 près d'un point — emplacements seulement, D1 ne propose pas de retrait |
Tests
bun test # unités monétaires, le piège du point-virgule, la quantité dans le devis,
# vacuité SKU inconnu, normalisation du panier, rédaction des commandes, et
# la liste blanche des endpoints qui limite la surface de paiement
bun run lint && bun run typecheck
Les codes de sortie sont un contrat, pas une décoration — le tableau sous Invocation ci-dessus est la seule copie.
Voir README.md pour la carte complète des endpoints, le comportement des niveaux de livraison, et ce que l'API publique ne vous donnera pas.