API & webhooks : brancher cocoPIM à vos outils

L’API en deux mots (vraiment)

Une API, c’est un guichet automatique pour logiciels : au lieu qu’un humain clique dans l’interface, un programme vient demander « donne-moi la fiche du produit TSH-001 » et reçoit la réponse instantanément, dans un format qu’il comprend. C’est ce qui permet, par exemple, à votre site web maison d’afficher toujours les fiches à jour, sans recopie.

L’API publique de cocoPIM permet de lire votre catalogue (produits, variantes, catégories, attributs, familles, listes d’options) et de l’écrire : créer et modifier des produits, structurer une famille (lui associer des attributs, avec leurs libellés personnalisés), remplir une liste d’options valeur par valeur, le tout depuis vos outils externes, un ERP ou un script d’intégration. L’écriture est protégée par des clés à portée dédiée (voir ci-dessous) et chaque création exige une clé d’idempotence : si votre programme renvoie deux fois la même requête, le produit n’est créé qu’une fois.

Le contrat complet : la spécification OpenAPI

Toute l’API est décrite dans une spécification OpenAPI (le format standard que les développeurs attendent), disponible à l’adresse /v1/openapi.json de l’API. Elle couvre chaque opération avec ses paramètres, la forme exacte des réponses (schémas), la pagination et les erreurs possibles. Et comme elle est générée directement depuis le code de cocoPIM, elle est toujours à jour : une évolution de l’API apparaît dans la spécification le jour même.

• Explorer sans coder : importez le fichier dans Postman, Insomnia ou Bruno, avec toutes les requêtes prêtes à tester ;
• Générer un client : les outils standard (openapi-generator, orval…) produisent le code d’appel dans votre langage à partir de la spécification ;
• Donner le contrat à un prestataire : la spécification suffit à chiffrer et développer une intégration, sans accès à votre compte.

Une API stable : ce qui marche aujourd’hui marchera demain

La version v1 n’évolue que de façon compatible : de nouveaux champs ou de nouvelles opérations peuvent apparaître, jamais disparaître ni changer de sens. Votre programme doit donc simplement ignorer un champ qu’il ne connaît pas. Un changement incompatible passerait par une nouvelle version (v2), servie à côté de la v1, et le retrait d’une version est annoncé au moins 12 mois à l’avance, dans l’application et sur cette page.

Essayer l’API en trois minutes : la collection Postman

Pour éviter à votre développeur, ou à vous-même, de partir d’une page blanche, nous publions une collection Postman prête à l’emploi : 62 requêtes, les 32 routes REST et les 30 opérations GraphQL, rangées par ressource. Chacune arrive avec un exemple de corps valide, ses paramètres commentés et un test qui vérifie la réponse. La partie REST est générée depuis la spécification OpenAPI, donc depuis le code : elle ne décrit jamais une API imaginaire.

• Collection PostmanJSONLes 62 requêtes REST et GraphQL, organisées par ressource. Dans Postman : Import, puis déposez le fichier.
• Environnement (modèle)JSONLes variables à renseigner : l’adresse de l’API et votre clé. Importez-le aussi, puis sélectionnez-le en haut à droite.

Une fois les deux fichiers importés, collez votre clé API dans la variable apiKey et lancez « Vérifier ma clé API », dans le dossier Commencer ici : en cas de refus, elle vous dit précisément pourquoi au lieu de vous laisser avec une erreur muette. Ensuite, les créations rangent automatiquement l’identifiant obtenu dans une variable, si bien que vous pouvez enchaîner créer, lire, modifier et supprimer sans recopier un seul identifiant à la main.

REST ou GraphQL ? Les deux guichets, même catalogue

L’API REST fonctionne comme une série de guichets spécialisés : un pour les produits, un pour les familles, un pour les catégories… Simple, universel : c’est le bon choix par défaut. À partir de l’offre Croissance, cocoPIM ouvre un second style de guichet : l’API GraphQL (/v1/graphql). La différence ? Votre outil décrit précisément ce qu’il veut (« la fiche NAP-GAR, avec ses variantes et le nom de sa famille ») et reçoit exactement cela, en une seule demande, au lieu d’enchaîner trois ou quatre appels et de trier les réponses.

• Même badge, même budget : la clé API est la même que pour le REST, avec les mêmes portées ; une requête GraphQL compte pour une unité du même quota mensuel. Rien de nouveau à administrer.
• Lecture ET écriture : tout ce que fait l’API REST, soit lire le catalogue (produits, variantes, familles, attributs, catégories, listes d’options) et le modifier, avec les mêmes garde-fous (clé d’idempotence sur les créations, mêmes règles de validation).
• Un contrat auto-décrit : l’équivalent GraphQL de la spécification OpenAPI. Le schéma est publié (/v1/graphql/sdl) et les outils standard le découvrent tout seuls : votre développeur génère son client typé en une commande.
• Des limites saines : profondeur et complexité des requêtes plafonnées, rythme d’appels par clé. Un script mal écrit est refusé poliment, il ne ralentit pas votre catalogue.

Les clés API : donner l’accès sans donner son compte

Un programme ne se connecte pas avec votre email et votre mot de passe : il utilise une clé API, un badge d’accès dédié, créé dans Développeurs → Clés API, avec une portée limitée (lecture seule, écriture, suppression). Donnez à chaque programme le minimum dont il a besoin. Bonnes pratiques :

• une clé par usage (une pour le site, une pour le prestataire) : on sait qui fait quoi, et on peut couper l’un sans casser l’autre ;
• révoquer sans pitié : un prestataire s’en va ? Sa clé se révoque en un clic, l’accès s’arrête immédiatement ;
• la clé ne s’affiche qu’une fois, à la création. Rangez-la dans votre gestionnaire de mots de passe ;
• faire tourner les clés : la rotation remplace une clé par une nouvelle sans coupure de service. Une bonne hygiène annuelle, et le réflexe immédiat si une clé a pu fuiter ;
• un budget par clé : chaque clé peut porter un quota mensuel d’appels ; à 80 % de consommation, cocoPIM vous alerte par email. Un script qui s’emballe chez un prestataire ne surprendra personne.

Les webhooks : être prévenu au lieu de vérifier

Le webhook, c’est l’inverse de l’API : au lieu que votre outil vienne demander « du nouveau ? » toutes les cinq minutes, c’est cocoPIM qui le prévient dès qu’un événement se produit (un produit créé ou modifié, mais aussi un changement de structure : attribut, famille, catégorie, liste d’options). Et ce quelle que soit l’origine du changement : une modification faite à la main dans cocoPIM déclenche les mêmes notifications qu’une écriture par l’API, y compris un import de fichier ou une modification en masse : chaque produit créé ou modifié déclenche sa propre notification, sans plafond. Votre ERP, votre outil de pilotage ou votre site peuvent réagir en temps réel.

1. 1

   Créez la souscription

   Dans Développeurs → Webhooks : l’adresse de votre outil (fournie par votre développeur) + les types d’événements à écouter.

2. 2

   cocoPIM notifie

   À chaque événement, cocoPIM envoie le message à l’adresse indiquée. Les envois sont signés (votre outil peut vérifier que c’est bien cocoPIM) et, en cas d’échec, réessayés jusqu’à cinq fois sur une quinzaine d’heures. Une coupure de quelques heures de votre outil ne fait donc rien perdre.

3. 3

   Suivez les livraisons

   L’écran des webhooks montre l’historique des envois, réussis ou non, précieux pour diagnostiquer avec votre prestataire.