API REST Cashod : envoyer des commandes COD depuis n’importe quelle boutique, CRM ou agent IA

Si vos commandes arrivent d’un outil que Cashod ne connecte pas nativement (boutique sur mesure, CRM, constructeur de landing pages ou agent IA), l’API REST publique de Cashod permet à cet outil de créer des commandes COD, de lire leur statut de livraison et leur numéro de suivi, et de synchroniser produits et stock. Vous créez une clé par boutique dans Paramètres → Développeurs, vous envoyez POST /v1/orders avec votre propre external_id pour que les nouvelles tentatives ne créent jamais de doublon, puis vous interrogez la commande pour suivre sa livraison. Guides complets et référence interactive sur le portail développeurs.

API, intégration native, webhook ou Google Sheets : laquelle choisir ?

Cashod reçoit les commandes de quatre façons. Choisissez la plus légère qui convient :

• Intégrations natives : Shopify, YouCan, WooCommerce, LightFunnels, Storeep et xPage. Si votre boutique tourne sur l’une d’elles, connectez-la depuis Intégrations, sans une ligne de code. Exemple : l’intégration Shopify.
• Webhook entrant : votre formulaire ou votre outil envoie chaque nouvelle commande à une URL de webhook Cashod. Idéal quand vous n’attendez rien en retour. Détails sur la page webhook.
• Import Google Sheets : pour les équipes qui collectent encore leurs commandes dans un tableur.
• API REST publique : quand il faut un échange dans les deux sens : créer des commandes, lire statut et suivi, créer ou mettre à jour des produits par SKU, mettre à jour le stock. L’option des développeurs, des agences et des agents IA.

Comment fonctionnent les clés API et les scopes ?

Chaque requête porte l’en-tête Authorization: Bearer csk_live_…. Les clés se créent par boutique dans Paramètres → Développeurs. Une clé n’est affichée qu’une fois, à sa création, et Cashod n’en conserve qu’une empreinte (hash) : copiez-la directement dans votre gestionnaire de secrets.

Chaque clé reçoit uniquement les scopes nécessaires :

• orders:read et orders:write : lister, lire et créer des commandes.
• products:read et products:write : lister, lire et créer ou mettre à jour des produits.
• stock:write : mettre à jour le stock d’une variante.

Un scope d’écriture inclut la lecture correspondante. Une landing page qui ne fait que créer des commandes n’a besoin que de orders:write ; un script d’entrepôt qui ne pousse que le stock n’a besoin que de stock:write. Agences : une clé par boutique cliente, pour révoquer un client sans toucher aux autres.

Comment créer une commande COD sans doublon ?

Envoyez POST /v1/orders avec un corps JSON. Les champs principaux :

• external_id : votre propre identifiant de commande (fortement recommandé, voir plus bas).
• customer : nom et téléphone. Le téléphone peut être dans n’importe quel format ; Cashod le normalise.
• shipping : adresse, ville et un téléphone de livraison optionnel.
• items : chacun avec une quantité et soit un sku, soit un product_id, soit un name libre (avec prix unitaire) pour un article hors catalogue.
• Optionnels : total ou discount, notes pour l’agent de confirmation, source_name pour vos propres rapports, scheduled_for pour une date d’échéance, et confirmed.

Par défaut, la commande arrive dans la file de confirmation comme les autres : votre centre d’appels ou votre agent IA la confirme. Ne passez confirmed à true que si vous avez déjà confirmé la commande avec le client vous-même.

Des nouvelles tentatives sans risque grâce à external_id

Sans idempotence, une requête renvoyée peut devenir une seconde vraie commande, confiée à un vrai livreur. Avec external_id, le premier appel renvoie 201 (créée) et toute nouvelle tentative avec le même identifiant renvoie 200 avec la commande déjà existante. Votre code peut donc réessayer sans risque.

Comment récupérer le statut de livraison et le suivi ?

GET /v1/orders/:id renvoie la commande avec son statut d’expédition, son statut de confirmation, la société de livraison, le tracking_number, les montants (dont l’avance et le montant COD à encaisser) et des horodatages comme l’expédition et la livraison. GET /v1/orders liste les commandes avec des filtres par statut d’expédition, statut de confirmation et date de création , pour remonter les statuts dans un CRM.

L’API n’envoie pas de webhooks sortants : la synchronisation des statuts est donc un job de polling, par exemple lister les commandes de votre période toutes les quelques minutes et écrire les changements dans votre système.

Comment synchroniser produits et stock ?

• POST /v1/products fait un upsert par SKU : le même appel crée le produit la première fois puis le met à jour. Les variantes sont aussi rapprochées par SKU ; une variante absente de l’appel reste intacte, elle n’est pas supprimée.
• GET /v1/products et GET /v1/products/:id lisent le catalogue, avec des filtres par SKU, nom et statut actif.
• PATCH /v1/products/:id/variants/:variantId/stock fixe le niveau de stock. C’est une valeur absolue, pas un delta : un appel répété ne peut pas compter deux fois.

Pagination, limites de débit et erreurs

• Pagination : les listes utilisent des curseurs. Chaque page renvoie data, has_more et next_cursor ; renvoyez le curseur pour obtenir la page suivante (jusqu’à 100 éléments par page).
• Limite de débit : 120 requêtes par minute par clé. Au-delà, vous recevez un HTTP 429 : patientez puis réessayez.
• Erreurs : toujours la même forme, un objet error avec un type (par exemple invalid_request, authentication_error, permission_error, not_found, rate_limit_exceeded ou server_error) et un message lisible.

Un agent IA doit-il utiliser l’API ou le serveur MCP ?

Tout dépend de pour qui travaille l’agent :

• Votre propre agent ou automatisation (un bot de vente sur votre landing page, un agent de prise de commande dans votre CRM) utilise l’API REST avec une clé limitée en scopes. Il agit pour une seule boutique, avec exactement les droits donnés à cette clé. La spécification OpenAPI (https://api.cashod.ma/api/v1/openapi.json) se convertit facilement en outils pour l’agent.
• Un assistant IA utilisé par une personne passe par le serveur MCP de Cashod, https://mcp.cashod.ma/mcp. Il fonctionne avec les assistants IA qui prennent en charge les connecteurs MCP, comme Claude et ChatGPT. La connexion se fait en OAuth : l’utilisateur se connecte avec son compte Cashod et approuve l’accès, puis l’assistant agit avec les droits habituels de cet utilisateur sur ses boutiques. Les étapes sont dans Paramètres → Chat IA. En savoir plus sur l’IA dans Cashod.

Cashod peut-il pousser des événements vers votre système ?

Pas via l’API. Pour pousser des événements, utilisez les Workflows : un workflow peut appeler n’importe quelle URL avec son action webhook, et aussi publier sur Slack ou Discord, envoyer un e-mail, un SMS ou un message WhatsApp.

Check-list avant la mise en production

1. Créez une clé par boutique avec le minimum de scopes, et gardez-la uniquement côté serveur.
2. Envoyez un external_id sur chaque commande et traitez 201 comme 200 comme un succès.
3. Utilisez des SKU identiques à votre catalogue Cashod, ou faites d’abord l’upsert des produits.
4. Laissez confirmed désactivé sauf si vous avez réellement confirmé avec le client.
5. Gérez le 429 avec un délai progressif et lisez le champ error.type.
6. Suivez next_cursor jusqu’à ce que has_more soit false.
7. Planifiez un job de polling pour statuts et suivi, ou un webhook de workflow pour les événements.
8. Testez le parcours complet avec une vraie commande : création, confirmation, expédition, lecture du numéro de suivi.

FAQ

L’API Cashod envoie-t-elle des webhooks ?

Non. Lisez les statuts avec des requêtes GET, ou utilisez l’action webhook d’un Workflow pour appeler votre URL.

Je gère plusieurs boutiques. Me faut-il plusieurs clés ?

Oui. Les clés sont par boutique, ce qui sépare les données et les accès de chaque boutique.

Où trouver la référence complète ?

Sur le portail développeurs, avec les guides, une référence interactive et la spécification OpenAPI.

Commencer

Ouvrez la documentation développeurs, créez votre première clé dans Paramètres → Développeurs et envoyez une commande de test. Pour choisir un plan selon le nombre de boutiques et de commandes mensuelles, consultez les tarifs.