L'API REST : piloter ses commandes COD depuis son code

À quoi sert l'API — et quand elle ne sert à rien

L'API répond à trois situations, et à peu près seulement trois. La première est une boutique développée sur mesure : au moment où le client valide son panier, votre code crée le lead et reçoit immédiatement sa référence, qu'il peut afficher au client. La deuxième est une application mobile, qui n'a pas de page web à faire appeler. La troisième est un outil interne — un tableau de bord, un rapprochement comptable, un script de reporting — qui a besoin de lire l'état des commandes pour le combiner à ses propres données.

En dehors de ces trois cas, elle ne sert pas à grand-chose, et il vaut mieux le dire avant que quelqu'un y passe une semaine. Si vos commandes viennent d'une boutique existante, la connexion de la boutique les fait entrer sans code et avec une relecture de secours que vous n'auriez pas écrite. Si elles viennent d'un formulaire ou d'une page d'atterrissage, la feuille de calcul est plus courte à mettre en place et plus facile à corriger. Si vous voulez simplement être prévenu quand un colis est livré, c'est un webhook sortant qu'il faut, pas une boucle d'appels à l'API.

La règle utile est celle-ci : l'API est justifiée quand c'est un programme que vous contrôlez qui produit la commande. Dans tous les autres cas, une des trois autres voies d'entrée fait le même travail pour moins d'effort et moins de maintenance.

La clé API, et ce qu'elle vaut

L'authentification tient en une ligne : chaque appel porte une clé dans son en-tête d'autorisation. Il n'y a ni identifiant à transmettre, ni paramètre de compte, ni session à maintenir. Le vendeur est déduit de la clé, et c'est une décision de sécurité autant que de simplicité : aucun appel ne peut porter sur les données d'un autre compte, même en modifiant les paramètres.

Une clé se crée depuis l'espace vendeur, avec un nom qui dit à quoi elle sert. Elle n'est affichée qu'une seule fois, à sa création : seule son empreinte est conservée, et personne — pas même le support — ne peut vous la relire. Si elle est perdue, on en crée une autre. Si elle est révoquée, elle ne redevient jamais valide.

• Une clé par intégration — Une clé pour l'application mobile, une autre pour le script de reporting. Révoquer l'une n'arrête pas l'autre, et le journal des appels dit laquelle a fait quoi.
• Une clé peut être rattachée à une boutique — Les leads créés avec cette clé portent alors automatiquement la boutique correspondante, sans que votre code ait à l'indiquer.
• La clé est un secret de serveur — Elle ne doit jamais partir dans une page web, une application mobile distribuée ou un dépôt de code : quiconque la lit peut créer des commandes à votre nom.
• La dernière utilisation est visible — Une clé qui n'a plus servi depuis longtemps est une clé à révoquer.
• Le journal des appels est à vous — Méthode, adresse appelée, code de réponse : c'est ce qui permet de répondre à « pourquoi ça ne marche pas » sans deviner.

Ce qui se lit, ce qui s'écrit, ce qui ne se touche pas

Le périmètre est volontairement étroit : l'API sert à faire entrer des commandes et à savoir où elles en sont. Tout ce qui engage de l'argent ou modifie un parcours reste dans l'interface, parce qu'une erreur de programme y coûterait plus cher qu'un clic humain.

• Deux réponses possibles à la création — Un lead accepté répond « créé ». Un lead douteux — référence inconnue, ville non reconnue, total incohérent, doublon récent — répond « accepté » avec la liste des anomalies : il existe, en lead endommagé, et attend une correction. Il n'est jamais refusé en silence.
• Pagination par curseur — La liste des leads se parcourt en reprenant l'identifiant renvoyé par la page précédente, pas par un numéro de page. Un numéro de page se décalerait à chaque nouveau lead, et l'intégration sauterait des commandes sans le voir.
• Votre propre référence est conservée — Le champ de référence externe est repris tel quel et réaffiché dans l'interface : c'est ce qui permet de rapprocher un lead de la commande d'origine dans votre système.
• Ce que l'API ne fait pas — Elle ne change pas un statut, n'annule pas une commande, ne déclenche pas de retrait et ne lit rien d'un autre vendeur. Ces actions existent dans l'interface, où elles sont tracées.

Limites de débit et codes d'erreur

Une limite de débit s'applique par clé et par minute. Elle existe pour une raison simple : une boucle mal écrite chez un vendeur ne doit pas ralentir la plateforme pour tous les autres. La valeur en vigueur n'est pas une constante à recopier dans votre code — elle est renvoyée par l'appel de vérification de clé, ce qui permet de l'adapter sans attendre une annonce.

Quand la limite est atteinte, la réponse le dit explicitement et indique combien de temps attendre. Un client correctement écrit respecte ce délai plutôt que de réessayer immédiatement ; réessayer tout de suite ne fait que consommer la minute suivante.

Où se trouve la référence complète

Cette page explique à quoi sert l'API et ce qu'elle permet ; elle ne remplace pas la référence. Celle-ci vit dans la documentation développeurs, qui est publique et ne demande aucun compte — le développeur d'un vendeur n'a pas ses identifiants, et exiger une inscription pour lire un contrat d'API ne protégerait rien.

On y trouve le guide de démarrage, la référence des adresses avec tous les champs attendus, la page des webhooks sortants, la liste des erreurs et des limites, et le journal des versions. La description est écrite une seule fois et sert à tout : la page lue par un humain, un fichier OpenAPI que votre outil importe pour engendrer un client, et une collection prête à essayer. C'est ce qui garantit que la page et le fichier ne disent pas deux choses différentes au bout de six mois.

Le numéro de version de l'API est renvoyé dans l'en-tête de chaque réponse, et le journal des versions dit ce qui a changé. Les ajouts de champs sont courants et ne cassent rien : un client bien écrit ignore un champ qu'il ne connaît pas plutôt que d'échouer dessus.