Plateforme HstockPlus : comment les commandes, l'exécution et l'API s'articulent réellement
Aperçu technique de la marketplace : les rôles, le parcours d'une commande, ce que l'API expose, et la distinction d'un endpoint qui décide si deux de vos collaborateurs livrent la même commande deux fois.
Sarah JohnsonCette page décrit le fonctionnement de la marketplace en tant que système : les rôles qu'elle comporte, le parcours d'une commande et ce que l'API expose. Aucune vente n'est réalisée depuis cette page.
Deux catalogues, pas un seul
La plateforme propose deux types de stock, dont les comportements diffèrent suffisamment pour que les traiter comme une seule entité pose problème.
Les annonces de produits sont des biens numériques vendus à l'unité depuis l'inventaire d'un vendeur : comptes, boîtes mail, proxys, clés. Environ dix-sept mille sont visibles par les acheteurs à tout moment, issues d'un catalogue plus large comprenant les brouillons, les annonces en attente d'approbation et celles désactivées par le vendeur. Elles sont regroupées en catégories et sous-catégories, balisées pour le filtrage, et tarifées par variante plutôt que par annonce — une seule annonce peut donc proposer plusieurs options d'achat à des prix différents.
Les services de croissance sont basés sur la quantité : vous commandez un nombre d'abonnés, de vues ou de commentaires pour un lien. Environ trente mille sont actifs. Ils utilisent leur propre catégorisation et leur propre vocabulaire de balises, et ne sont pas comptabilisés dans la limite d'annonces de produits d'un vendeur.
Les vendeurs se comptent en quelques centaines par catalogue actif, contre environ mille cinq cents comptes disposant du rôle vendeur, répartis sur près de cinq cent soixante boutiques.
Rôles et accès de chacun
Trois rôles existent et ils sont cumulatifs plutôt qu'exclusifs : un même compte peut être à la fois acheteur et vendeur.
- Les acheteurs consultent, commandent, disposent d'un solde sur le site, suivent leurs commandes et ouvrent des tickets d'assistance.
- Les vendeurs gèrent leurs annonces et leur inventaire, traitent les commandes, configurent des codes promo et demandent des paiements. Un profil vendeur peut être rendu public afin que les acheteurs puissent parcourir tout ce que ce vendeur propose au même endroit.
- Les administrateurs approuvent les vendeurs et les annonces, résolvent les litiges et détiennent les paramètres dont la plupart des comportements de la plateforme dépendent.
L'approbation des vendeurs est actuellement obligatoire et conditionne aussi bien l'API que l'interface : un vendeur dont le compte n'a pas été approuvé reçoit une réponse explicite d'approbation en attente plutôt qu'un catalogue vide, ce qui est utile à distinguer lorsqu'une intégration ne renvoie rien.
Les vendeurs sont répartis sur cinq paliers déterminés par les ventes attribuées sur douze mois glissants. Le palier n'est pas décoratif. Il définit le délai avant le déblocage automatique des fonds et alimente le calcul de la limite d'annonces.
Le parcours d'une commande
L'état de la commande et l'état du paiement sont suivis séparément, et les deux comptent lorsque vous lisez l'API.
L'état propre de la commande passe par en attente, en traitement, terminée, puis éventuellement remboursée, avec annulée et erreur comme issues terminales. L'état du paiement est un champ distinct avec ses propres valeurs : terminé, partiel, remboursé, échoué, en attente et en traitement. À noter si vous écrivez un filtre : il n'existe pas d'état de paiement « payé ». Une requête pour cet état ne renvoie rien, ce qui ressemble à un résultat vide plutôt qu'à une erreur de requête.
L'exécution diffère selon le type d'annonce. Les annonces automatiques et adossées à l'inventaire remettent un stock déjà détenu par la plateforme. Les annonces manuelles sont celles qui nécessitent l'intervention d'un vendeur ou de son logiciel, et c'est à cela que sert l'API d'exécution.
Une fois l'acheteur en possession de sa commande, une fenêtre de garantie s'ouvre. Elle se mesure en heures et court à partir de la livraison, et non du paiement, avec un minimum global de quelques heures et des réglages par vendeur au-dessus. Dans cette fenêtre, l'acheteur peut ouvrir un ticket ou un litige ; au-delà, la voie du litige est refusée. Les fonds sont débloqués au vendeur soit lorsque l'acheteur confirme, soit à l'expiration du délai de confirmation automatique propre au palier du vendeur, selon la première échéance, et un litige en cours bloque le déblocage.
L'API et la distinction la plus importante
Il existe deux surfaces d'API, toutes deux authentifiées par clé.
La surface côté acheteur suit la convention de panneau largement répandue : un point d'entrée unique prenant un paramètre action. Les actions standard sont toutes implémentées, de sorte que les outils de panneau existants fonctionnent avec : services pour lister ce qui est disponible, add pour passer une commande, status pour en vérifier une, balance, refill et cancel. Par-dessus, elle ajoute des actions que la convention ne définit pas : categories et subcategory_info pour naviguer dans la taxonomie, products et shops, allowcancel, inventory pour les vérifications de stock, et un ensemble complet d'actions de vérification SMS couvrant les projets, les pays, la commande d'un numéro et l'interrogation du code. Considérez-la comme la convention standard enrichie d'extensions, plutôt que comme un clone direct ; les appels standard fonctionneront sans modification, et les extensions sont là où réside la capacité propre à la plateforme.
La surface côté vendeur est une API REST classique couvrant les produits, les commandes, les tickets et les paiements. Au sein de celle-ci, une distinction décide de la justesse de votre intégration, et il est facile de se tromper car les deux points d'entrée renvoient des commandes.
- Lister les commandes est une lecture. Elle ne réserve rien. Deux workers qui interrogent reçoivent tous deux la même commande, et tous deux tenteront de la livrer.
- Récupérer les commandes est une réservation. Elle fait passer chaque commande de en attente à en traitement via une écriture conditionnelle, et ne renvoie que les commandes dont l'écriture a réellement gagné. Si deux workers récupèrent simultanément, chacun reçoit un ensemble disjoint.
Tout ce qui exécute automatiquement doit récupérer, et non lister. Utilisez la lecture pour les tableaux de bord et la réconciliation, où voir deux fois la même commande est sans conséquence.
Trois détails supplémentaires vous épargnent un après-midi. La récupération ne renvoie que les lignes à exécution manuelle, donc le stock automatique et adossé à l'inventaire n'y apparaîtra jamais. Le lot par défaut est de cent commandes et le plafond est de cinq cents. Et une commande récupérée n'est pas reproposée avant environ une demi-heure, ce qui constitue une marge de sécurité délibérée : si votre worker plante après la récupération, la commande revient d'elle-même, mais pas instantanément.
La référence complète des deux surfaces se trouve dans la documentation de l'API acheteur et la documentation de l'API vendeur.
Paiements et soldes
La plateforme gère un solde interne par lequel transite la plupart des activités. Les acheteurs le rechargent et dépensent depuis celui-ci, les remboursements y sont crédités, et c'est de là que la majorité des commandes sont réellement payées. Les canaux de paiement en cryptomonnaie et conventionnels sont tous deux pris en charge pour le rechargement, certains réglant directement et d'autres via un processeur de paiement.
Les vendeurs demandent des paiements sur la valeur de commandes réglée et débloquée. Un minimum s'applique, défini à l'échelle de la plateforme avec des minimums supplémentaires par méthode, et les paiements comportent des frais en pourcentage. Aucune commission par commande n'est prélevée sur les vendeurs, c'est donc dans les frais de paiement que se situe la part de la plateforme, plutôt que dans la vente elle-même.
Assistance et litiges
L'assistance passe par un système de tickets partagé par les trois rôles : un acheteur, un vendeur et le support peuvent ainsi se trouver dans un même fil plutôt que dans trois conversations qui ne se croisent jamais. Les tickets portent une classification du problème, et un vendeur peut en résoudre un en remplaçant l'article livré, en le remboursant ou en rejetant la réclamation.
Les litiges sont la voie plus lourde et sont délibérément plus restreints : ils exigent que la commande soit terminée et dans sa fenêtre de garantie, au moins une capture d'écran, et une sélection dans une liste de problèmes à deux niveaux. Ils se concluent par le versement des fonds au vendeur ou leur retour à l'acheteur. Un remplacement n'est pas une issue de litige, ce qui explique pourquoi la voie du ticket résout la grande majorité des problèmes réels et pourquoi ouvrir d'abord un ticket est généralement le chemin le plus rapide.
Ce qui s'exécute selon un calendrier
Plusieurs choses se produisent sans déclenchement manuel, et une intégration est plus facile à raisonner si l'on sait qu'elles existent : les fonds se confirment et se débloquent automatiquement après le délai du palier du vendeur ; un litige laissé sans action après la fermeture de tous ses tickets se résout en faveur du vendeur après un nombre fixe de jours ; les mises en avant expirent via une tâche quotidienne ; les partages promotionnels approuvés sont revérifiés chaque semaine ; et le texte des annonces est scanné par lots contre les règles de contact hors plateforme.
Aucune de ces opérations ne s'annonce à l'API. Si votre réconciliation voit une commande changer d'état sans appel de votre part, l'une d'elles en est généralement la cause.
Pour commencer
- Inscrivez-vous, puis demandez l'approbation vendeur si vous comptez vendre. L'approbation conditionne l'API comme l'interface.
- Créez des annonces, ou importez des services de croissance depuis un fournisseur amont configuré, en masse plutôt qu'un par un.
- Générez une clé API et confirmez votre rôle en appelant le point d'entrée de profil avant toute autre chose.
- Si vous exécutez manuellement, construisez dès le départ autour du point d'entrée de récupération. Passer de la liste à la récupération après avoir expédié des livraisons en double est une journée bien pire que la lecture de ce paragraphe.
- Définissez délibérément les heures de garantie par annonce. C'est l'horloge sur laquelle repose toute la protection acheteur de la plateforme, et elle démarre à la livraison.
