Événements

Chaque changement important dans Cord produit un événement : un enregistrement avec un type, un objet, des données et son auteur. Ces mêmes événements sont envoyés à vos webhooks, déclenchent Cord Workflows et restent dans un historique que vous consultez avec GET /api/v1/events, qu’un endpoint y soit abonné ou non.

Catalogue des événements

Il existe 41 types. La colonne Objet correspond à la valeur de object dans l’historique et détermine la forme de data (voir la section suivante).

ping n’est pas un événement du catalogue : c’est l’envoi de test du bouton Tester du Workbench et il n’apparaît jamais dans l’historique.

Forme de data par objet

Tout montant voyage avec sa devise dans moneda. Les noms des champs sont ceux du serveur, en espagnol.

Champs supplémentaires par événement :

Sur une facture, estado correspond à son cycle de vie (draft, open, paid, void ou uncollectible) et estado_fiscal à son enregistrement auprès du fournisseur fiscal (pending, issued, cancelled ou error). Sur un devis, status vaut draft, sent, viewed, approved, rejected, expired, invoiced ou paid.

Le data conservé dans l’historique est celui du webhook sans link_publico : le lien est un identifiant du client et n’est pas conservé.

Qui a provoqué l’événement : actor

Traitez actor comme un texte avec un préfixe : décidez en fonction de ce qui précède les deux-points et ne supposez pas que la liste n’évoluera pas.

Historique : GET /api/v1/events

Renvoie les événements de votre organisation, du plus récent au plus ancien. Si votre serveur est resté indisponible plus longtemps que ce que couvrent les nouvelles tentatives, c’est ici que vous récupérez ce que vous avez manqué.

curl "https://cordhq.app/api/v1/events?object_id=8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10&limit=10" \
  -H "Authorization: Bearer sk_test_..."

import { Cord } from '@flouviahq/node';

const cord = new Cord(process.env.CORD_API_KEY);
const page = await cord.events.list({ object_id: '8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10', limit: 10 });
for (const event of page.data) console.log(event.created_at, event.type, event.actor);

{
  "data": [
    {
      "id": "e81c5a3f-7d2b-4e9a-b6c1-0f4d8a2e5c71",
      "type": "quote.approved",
      "object": "quote",
      "object_id": "8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10",
      "data": {
        "id": "8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10",
        "folio": "COT-0001",
        "status": "approved",
        "moneda": "MXN",
        "total": 13920,
        "cliente": "Ferretería La Prueba",
        "cliente_id": "0e6f2b8a-91c4-4d7e-b3a5-6c2d8f1e4a90"
      },
      "actor": "client",
      "created_at": "2026-10-07T17:31:44.208Z"
    },
    {
      "id": "3a7f1c9e-2b4d-4a6e-8c0f-5d9b3e7a1c24",
      "type": "quote.sent",
      "object": "quote",
      "object_id": "8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10",
      "data": {
        "id": "8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10",
        "folio": "COT-0001",
        "status": "sent",
        "moneda": "MXN",
        "total": 13920,
        "cliente": "Ferretería La Prueba",
        "cliente_id": "0e6f2b8a-91c4-4d7e-b3a5-6c2d8f1e4a90"
      },
      "actor": "api:2c6e0a9d-4f1b-4c3e-8a7d-9b5f1e3c7a20",
      "created_at": "2026-10-07T17:04:12.318Z"
    }
  ],
  "meta": { "next_cursor": null }
}

• L’id de l’historique est un UUID propre à l’enregistrement. Ce n’est pas l’evt_… de l’envoi du webhook : pour dédupliquer entre les deux, utilisez object_id, type et created_at.
• object_id vaut null pour les événements sans objet doté d’un UUID, comme account.updated.
• La pagination se fait par curseur et elle est stable : un nouvel événement ne décale pas la page que vous lisez. Voir Pagination.
• Un object_id qui n’est pas un UUID ou un cursor non valide répondent 400 avec code: "invalid_request".

Conservation

L’historique fonctionne en ajout seul : un événement n’est pas modifié après son écriture. Il est conservé 90 jours, puis un traitement quotidien le supprime ; celui qui a lancé une exécution d’un workflow est conservé tant que cette exécution existe, et une exécution est supprimée un an après sa fin. Le journal des envois de webhooks a sa propre durée (30 jours ; 90 pour les envois échoués). Tout est supprimé avec l’organisation.

Vérifier une clé : GET /api/v1/me

C’est l’appel le plus simple de l’API : il confirme que la clé est valide et indique à quelle organisation elle appartient, son droit et son mode. Il répond à toute clé secrète, clé restreinte ou connexion OAuth, quels que soient ses droits par ressource.

curl https://cordhq.app/api/v1/me \
  -H "Authorization: Bearer sk_test_..."

import { Cord } from '@flouviahq/node';

const cord = new Cord(process.env.CORD_API_KEY);
const me = await cord.me();
console.log(me.org.nombre, me.scope, me.mode);

{
  "data": {
    "org": { "id": "5b1f7d9e-3c2a-4e8b-9f61-0a7c4d2e8b13", "nombre": "Aceros del Norte", "plan": "pro" },
    "scope": "write",
    "mode": "test"
  }
}

Utilisez-le pour tester un identifiant avant de l’enregistrer dans votre intégration.