Aller au contenu
FREN

Cord Workbench

Créez, testez et déboguez votre intégration sans quitter Cord : chaque requête, chaque erreur, chaque événement et chaque envoi dans un seul panneau.

Qu’est-ce que c’est ?

Le Workbench est la console développeurs de Cord. Il se trouve en bas de l’application sous la forme d’une pastille Développeurs et, lorsque vous l’ouvrez, il déploie un panneau à huit onglets : Vue d’ensemble, Journaux, Erreurs, Événements, Webhooks, Shell, Clés API et Santé. La barre supérieure du panneau contient l’Inspecteur, qui retrouve n’importe quel ID.

Les clés API, les webhooks, les journaux et les événements se trouvent ici. MCP, Intelligence artificielle et Générateur de devis intégrable restent dans les Paramètres, dans la section Développeurs de l’index, car il s’agit d’une configuration ponctuelle.

Prérequis

  • Le droit Paramètres dans votre rôle. Sans lui, le Workbench n’apparaît pas.
  • Le Mode développeur activé. C’est une préférence de votre compte, pas de l’organisation.
  • Il est disponible dans toutes les offres. L’historique des envois de webhooks, Réessayer et Renvoyer nécessitent l’offre Professionnel ou une offre supérieure.

L’activer

  1. Allez dans Paramètres et faites défiler jusqu’en bas de l’index des catégories.
  2. Activez l’interrupteur Mode développeur.
  3. La pastille Développeurs apparaît dans le coin inférieur droit, dans toute l’application. Cliquez dessus, faites-la glisser vers le haut ou appuyez sur W.

Le Mode développeur vous suit sur n’importe quel ordinateur où vous vous connectez avec votre compte. Vous pouvez aussi le modifier dans Vos préférences. Un lien contenant ?wb= ou ?wbi= (voir Liens directs) l’active également.

Le panneau

Le Workbench ouvert à mi-hauteur sur Devis, sur l’onglet Vue d’ensemble des 7 derniers jours en production : 2 523 requêtes API avec 1,9 % d’erreurs, une latence p95 de 412 ms et 99,5 % des envois de webhook réussis ; les principales erreurs par code, la provenance des requêtes, l’activité récente, l’intégration sans alerte et 3 412 requêtes utilisées sur 5 000 ce mois-ci.
  • Taille. Faites glisser la poignée supérieure pour agrandir ou réduire le panneau ; relâchez-la près du bas pour le fermer.
  • Plein écran. Le bouton situé à côté de Fermer étend le panneau à toute la fenêtre. Vous en sortez avec le même bouton, avec ⇧W ou avec Esc.
  • Options (⋯). Afficher les heures en UTC change instantanément toutes les dates du panneau sans toucher au fuseau horaire de votre compte. Le menu liste aussi les raccourcis clavier et renvoie vers ce guide et vers la spécification OpenAPI.
  • Environnement. Le Workbench affiche l’environnement dans lequel se trouve l’application. Dans l’environnement de test, vous voyez ce qu’ont fait vos clés sk_test_ et le Shell en Test ; en production, ce qu’ont fait vos clés live. La Vue d’ensemble l’indique par une étiquette Test ou Production.
  • Le panneau mémorise dans ce navigateur s’il était ouvert, l’onglet, la hauteur, le plein écran et l’option UTC.

Raccourcis clavier

Touche Effet
W Ouvre ou ferme le Workbench.
⇧W Plein écran.
/ Place le curseur dans l’Inspecteur.
1 à 8 Va à l’onglet portant ce numéro, dans l’ordre de la barre.
J / K Ligne suivante ou précédente dans Journaux et Événements.
⌘↵ (Ctrl+↵ sous Windows) Envoie la requête du Shell.
Esc Ferme ce qui est ouvert : menu, boîte de dialogue, Inspecteur, plein écran et, en dernier, le panneau.

Les raccourcis d’une lettre ou d’un chiffre ne se déclenchent pas pendant que vous saisissez du texte dans un champ. Sur les écrans de moins de 880 px, il n’y a pas de raccourcis à une touche et le panneau s’ouvre comme une feuille bord à bord ; sur les plus étroits, l’Inspecteur est une icône de la barre supérieure qui se déploie lorsque vous la touchez.

Les onglets

Vue d’ensemble

La vue d’accueil, sur une période de 24 heures, 7 jours ou 30 jours :

  • Indicateurs : requêtes API, taux d’erreur, latence p95 (avec la p50 en dessous) et part des envois de webhooks réussis.
  • Requêtes dans le temps : barres des requêtes réussies et en erreur.
  • Principales erreurs : les cinq codes les plus fréquents. Un clic ouvre Journaux filtré sur ce code.
  • Provenance : les requêtes par source. Un clic ouvre Journaux filtré sur cette source.
  • Activité récente : les six dernières requêtes.
  • À droite : la carte de santé (elle vous mène à Santé), l’utilisation de l’API ce mois-ci par rapport à ce qu’inclut votre offre, les premiers pas tant qu’il n’y a aucune requête sur la période, et les ressources pour les développeurs.

Seuls les appels effectués avec des clés live comptent dans l’utilisation du mois : ceux en test et ceux du Workbench ne consomment pas votre quota.

La source de chaque requête dépend du client qui l’a effectuée :

Source Quand
SDK Node, SDK Python, SDK PHP, CLI Le SDK ou la CLI de Cord s’est identifié dans la requête.
cURL La requête provient de curl.
MCP Un appel au serveur MCP.
Cord Elements Une clé publiable (pk_), comme celle qu’utilise Cord Elements.
App connectée Une application autorisée via OAuth, comme Zapier ou Make.
Workbench Le Shell.
HTTP Tout autre client.

Journaux

Chaque requête parvenue à /api/v1 et au serveur MCP, dans une liste avec son détail à droite. Les appels MCP affichent l’outil, par exemple /mcp/tools/call:listar_productos.

Le Workbench dans l’environnement de test, sur l’onglet Journaux : les requêtes du démarrage rapide faites avec cURL et la clé de test, l’une avec l’erreur invalid_request et une autre depuis le Shell du Workbench, et le détail de POST /v1/cotizaciones (201, 184 ms) avec son request id, la version 2026-10-01, le mode Test et les boutons Copier en cURL et Ouvrir dans le Shell.
  • Recherchez par route, par request id (req_…), par code d’erreur ou par une Idempotency-Key exacte. Un request id est recherché dans tout l’historique, quelle que soit la période.
  • Filtrez par méthode (GET, POST, PATCH, DELETE), par classe de statut (2xx, 4xx, 5xx), par clé (ou uniquement celles du Workbench), par source et par période (1 heure, 24 heures, 7 jours ou 30 jours).
  • En direct ajoute les nouvelles requêtes en haut toutes les quelques secondes tant que l’onglet est visible. Charger plus affiche les 50 suivantes.

Le détail d’une requête affiche le statut, le code d’erreur avec son message et un lien Comment résoudre vers Erreurs, le request id, la date, la latence, la clé, la source, la version de l’API, le mode, l’IP et l’Idempotency-Key. Si Cord a renvoyé la réponse enregistrée d’une requête répétée, il l’indique par Réponse rejouée, et liste en dessous les autres requêtes portant la même Idempotency-Key.

  • Copier en cURL copie la requête prête à coller dans votre terminal : l’en-tête Authorization lit votre clé dans la variable d’environnement $CORD_SECRET_KEY. Le corps n’est pas inclus, car il n’est pas conservé.
  • Ouvrir dans le Shell la charge dans le Shell avec ses paramètres. En production, cette option n’apparaît que pour les requêtes GET.
  • Inspecter la ressource ouvre dans l’Inspecteur l’ID contenu dans la route.

Cord ne conserve pas le corps des requêtes ni des réponses de l’API, uniquement leurs métadonnées. Les conserver reviendrait à garder les données de vos clients (identifiants fiscaux, adresses e-mail, montants) à chaque appel. Pour voir une réponse complète, répétez l’opération dans le Shell ou consultez le journal de votre propre serveur.

Chaque requête est conservée 30 jours. Un traitement quotidien supprime ce qui est plus ancien : la période la plus longue de Journaux, Erreurs et Vue d’ensemble est donc de 30 jours. La suppression passe par une fonction de la base de données qui n’efface que les enregistrements de plus de 30 jours ; même Cord ne peut pas l’utiliser pour supprimer quelque chose de plus récent.

Erreurs

Les requêtes en échec regroupées par code, méthode et route, les ID de la route étant remplacés par {id}, pour que vous voyiez la cause et non chaque ligne. Période de 1 heure, 24 heures, 7 jours ou 30 jours. Une requête sans code propre apparaît sous la forme http_ suivi de son statut.

Chaque groupe indique combien de fois l’erreur s’est produite et quand pour la dernière fois. En l’ouvrant, vous voyez le dernier message d’erreur, la route, la première et la dernière occurrence, le nombre de clés qui l’ont provoquée et trois actions : Voir les requêtes (Journaux filtré sur ce code), Voir un exemple (la requête la plus récente dans l’Inspecteur) et Comment résoudre.

Événements

L’historique des événements de votre entreprise : le même que renvoie GET /api/v1/events, même si vous n’avez aucun webhook.

  • Filtrez par type d’événement, par statut d’envoi (Échoués, En attente, Envoyés) et par ID de l’objet. En direct et Charger plus fonctionnent comme dans Journaux.
  • Chaque ligne affiche le statut de ses envois, le type, l’objet, ce qui l’a déclenché (API, MCP, Tableau de bord, Workflow, Workbench, Intégration ou Système) et la date.
  • Le détail affiche l’ID de l’événement, la date, l’objet (un clic l’ouvre dans l’Inspecteur), ce qui l’a déclenché avec le nom de la clé ou de la personne, les données de l’événement et un envoi par endpoint abonné : URL, statut, tentatives, prochaine tentative, l’evt_… reçu par cet endpoint et la dernière erreur.
  • Renvoyer renvoie un envoi avec le même payload et le même evt_…, pour que votre serveur puisse le dédupliquer. Lorsqu’il y a plus d’un envoi en échec, Renvoyer les envois échoués apparaît. Ces deux actions nécessitent l’offre Professionnel ou une offre supérieure.
  • Le statut de l’événement dépend du dernier envoi vers chaque endpoint : un renvoi réussi remplace l’échec. Un envoi que Cord a annulé parce qu’il a désactivé l’endpoint apparaît comme Annulé, et non comme envoyé.

Les événements internes, comme quote.expiring ou invoice.due_soon, portent l’étiquette Interne : les workflows les utilisent et ils ne sont pas envoyés par webhook. Les envois de test (le bouton Tester d’un endpoint ou le simulateur sans objeto_id) ne sont pas des événements de votre entreprise : ils n’apparaissent pas ici, uniquement dans les envois de l’endpoint.

Webhooks

Vos endpoints, avec le quota de votre offre. Ajouter un endpoint ouvre un assistant en plein écran :

  1. Choisissez les événements. Les 41 événements du catalogue, regroupés par famille, avec une recherche et une case pour sélectionner toute une famille. Tous les événements inclut aussi ceux que Cord ajoutera plus tard ; si vous n’en cochez aucun, vous les recevez tous.
  2. Configurez la destination. Une URL publique en https://.
  3. Enregistrez le secret. Le secret de signature (whsec_…) ne s’affiche qu’une seule fois. Depuis ce même écran, vous pouvez Envoyer un événement de test.
L’onglet Webhooks du Workbench en plein écran : l’endpoint de l’ERP avec 93,1 % d’envois réussis sur 7 jours, déplié sur ses envois ; la plus récente, quote.approved à sa deuxième tentative, a échoué avec une erreur 500 et affiche le payload exact envoyé par Cord, la réponse du serveur et les boutons Réessayer et Voir l’événement.

Chaque endpoint affiche son secret masqué, le nombre d’événements qu’il reçoit, son dernier envoi et les 7 derniers jours : envois par jour, taux de réussite et latence p95. Ses actions :

  • Tester envoie ping ou l’un de ses événements abonnés avec des données d’exemple, dans la version de l’API à laquelle l’endpoint est fixé. Le payload porte "test": true au premier niveau pour que votre serveur distingue un test d’un événement réel.
  • Modifier, Renouveler le secret (avec une période de 1, 24 ou 72 heures pendant laquelle les deux secrets restent valables), activer ou mettre en pause, et Supprimer.
  • Réactiver ou Réactiver et réessayer lorsque Cord a désactivé l’endpoint après une série d’échecs. La seconde option remet en file d’attente ce qui a échoué au cours des dernières 24 heures.
  • En dépliant la ligne, vous voyez ses 50 derniers envois. Chacun affiche ce que Cord a envoyé (le payload exact) et ce que votre serveur a répondu (jusqu’à 2 000 caractères), avec Réessayer et, s’il provient d’un événement, Voir l’événement.

Le guide complet (payload, signatures, catalogue et nouvelles tentatives) se trouve dans Webhooks.

Shell

Exécute n’importe quelle opération de l’API publique avec votre session, sans créer de clé.

  • Test s’exécute dans votre environnement de test : vous pouvez créer et modifier sans toucher aux données réelles, et utiliser les simulateurs de test.
  • Production · lecture seule lit vos données réelles : seules les opérations GET peuvent être envoyées.
  • Les opérations liées à une clé (les endpoints de webhook via l’API et les sessions cord listen) ainsi que celles qui répondent en streaming ou envoient des fichiers ne s’exécutent pas dans le Shell.

Choisissez une opération dans la liste (avec recherche), renseignez ses paramètres et son corps JSON, fourni avec un exemple, puis envoyez-la avec Envoyer ou ⌘↵. Dans En-têtes facultatifs, vous choisissez la version de l’API (Cord-Version). La réponse affiche le statut, la latence et le request id, et propose trois vues : Réponse (jusqu’à 200 Ko), En-têtes et Code, avec la même requête en cURL, SDK Node, JavaScript (fetch) et Python, en utilisant votre clé sous la forme $CORD_SECRET_KEY. Récentes conserve vos 15 derniers appels pour cette organisation dans ce navigateur.

Chaque appel du Shell apparaît dans Journaux avec la source Workbench et ne consomme pas le quota d’API de votre offre. Un clic sur le request id l’ouvre dans l’Inspecteur. Si vous l’avez exécuté dans un autre environnement que celui de l’application (par exemple, en Test alors que l’application est en production), le request id est seulement copié : changez le mode test de l’application pour le voir dans Journaux.

Clés API

L’onglet Clés API du Workbench en plein écran : en haut, 3 412 requêtes API utilisées sur 5 000 ce mois-ci et la version 2026-10-01 ; en dessous, des clés secrètes, restreinte et publiable en production et en test, chacune avec son jeton masqué et ses 4 derniers caractères, ses droits, sa dernière utilisation, sa création et son expiration, plus une connexion OAuth et une clé révoquée.
  • L’utilisation de l’API ce mois-ci par rapport à ce qu’inclut votre offre, et la version de l’API en vigueur. Chaque clé et chaque webhook restent liés à la version du jour de leur création ; l’en-tête Cord-Version la modifie par requête. Voir Versions.
  • Clés API : générez, modifiez, renouvelez et révoquez des clés secrètes (sk_), restreintes (rk_) et publiables (pk_), en test ou en production. Chaque clé dispose d’un bouton Journaux qui ouvre ses requêtes des 7 derniers jours. Les applications autorisées via OAuth apparaissent comme Connexion autorisée. Voir Clés API.
  • Référence de l’API : toutes les opérations, regroupées, avec un exemple curl, un bouton Essayer sur celles qui peuvent s’exécuter dans le Shell, et le bouton qui génère un prompt d’intégration pour ChatGPT ou Cursor.

Santé

Une liste d’alertes actives, chacune avec un lien vers l’onglet où la résoudre :

  • un endpoint désactivé ou comptant 3 échecs consécutifs ou plus ;
  • des événements dont les tentatives sont épuisées et des tentatives en retard dans la file ;
  • un taux d’erreur de 5 % ou plus avec au moins 20 requêtes en 24 heures ;
  • des erreurs 5xx au cours des dernières 24 heures ;
  • une clé qui expire, ou une clé renouvelée qui cesse de fonctionner, dans les 7 prochains jours.

En dessous, trois cartes : l’état de chaque endpoint (actif avec son taux de réussite et sa p95, en pause, désactivé ou avec des échecs consécutifs), la file d’événements (en attente, tentatives en retard, épuisés et envoi p95) et l’API sur les dernières 24 heures (requêtes, taux d’erreur, 4xx, 5xx et latence p95).

Inspecteur

Collez un ID dans le champ de recherche de la barre supérieure du panneau, ou appuyez sur / :

  • un request id (req_…) ouvre cette requête ;
  • un ID d’événement (evt_…) ouvre l’événement qui en est à l’origine, ou vous indique qu’il s’agissait d’un envoi de test ;
  • l’ID d’un devis, d’une facture, d’un client, d’un produit, d’une clé, d’un endpoint de webhook ou d’un événement.

Pour un objet, vous voyez son type, son nom ou son numéro, les événements qui le mentionnent et les requêtes des 30 derniers jours qui l’ont concerné (ou qu’a effectuées cette clé). Ouvrir dans Cord mène à sa page lorsqu’il en a une et, pour un devis, une facture ou un client, Voir tel que l’API le renvoie l’ouvre dans le Shell. Retour ou Esc ramènent à l’onglet.

Liens directs

  • /app?wb=registros ouvre le Workbench sur cet onglet. Les noms sont resumen (Vue d’ensemble), registros (Journaux), errores (Erreurs), eventos (Événements), webhooks, shell, api (Clés API) et salud (Santé).
  • /app?wbi=<id> ouvre l’Inspecteur avec cet ID.

Ces deux liens activent le Mode développeur s’il était désactivé.

Questions fréquentes

Pourquoi ne vois-je pas une requête effectuée avec une clé de test ? Le Workbench affiche l’environnement dans lequel se trouve l’application. Passez dans l’environnement de test pour voir ce qu’ont fait vos clés sk_test_.

Le Workbench est-il décompté de mon quota d’API ? Non. Naviguer dans le panneau n’appelle pas votre API, et les appels du Shell ne comptent pas non plus. Seules comptent les requêtes effectuées avec des clés live.

Pourquoi Événements affiche-t-il des événements alors que je n’ai pas de webhooks ? Parce qu’il lit l’historique des événements de l’entreprise, et non les envois. Sans endpoints, chaque événement apparaît comme Aucun endpoint.

Pourquoi ne puis-je pas voir les envois d’un endpoint ? L’historique des envois, Réessayer et Renvoyer nécessitent l’offre Professionnel ou une offre supérieure. La création d’endpoints, la réception d’événements, Tester, Renouveler le secret et Réactiver sont disponibles dans toutes les offres.

Combien de temps les journaux sont-ils conservés ? 30 jours à compter de chaque requête. Si vous avez besoin d’un historique plus long, conservez le request id (Cord-Request-Id) et la réponse dans votre propre système.

Mon équipe voit-elle la même chose que moi ? Oui. Tout membre disposant du droit Paramètres voit les données de l’organisation. Sont personnels le Mode développeur, qui suit votre compte, ainsi que, dans chaque navigateur, la taille du panneau et l’option UTC. Les appels récents du Shell sont conservés dans chaque navigateur, par organisation.