Eventos

Cada alteração relevante no Cord produz um evento: um registro com tipo, objeto, dados e quem o originou. Os mesmos eventos são entregues aos seus webhooks, disparam o Cord Workflows e ficam em um histórico que você consulta com GET /api/v1/events, haja ou não endpoints inscritos.

Catálogo de eventos

Há 41 tipos. A coluna Objeto é o valor de object no histórico e define o formato de data (veja a próxima seção).

ping não é um evento do catálogo: é a entrega de teste do botão Testar do Workbench e nunca aparece no histórico.

Formato de data por objeto

Todo valor viaja com a sua moeda em moneda. Os nomes dos campos são os do servidor, em espanhol.

Campos extras por evento:

Em uma fatura, estado é o ciclo de vida dela (draft, open, paid, void ou uncollectible) e estado_fiscal é o registro dela perante o provedor fiscal (pending, issued, cancelled ou error). Em um orçamento, status é draft, sent, viewed, approved, rejected, expired, invoiced ou paid.

O data que o histórico guarda é o mesmo do webhook sem link_publico: o link é uma credencial do cliente e não é armazenado.

Quem originou o evento: actor

Trate actor como texto com um prefixo: decida pelo que vem antes dos dois-pontos e não presuma que a lista não vai crescer.

Histórico: GET /api/v1/events

Devolve os eventos da sua organização, do mais recente ao mais antigo. Se o seu servidor ficou fora do ar por mais tempo do que as novas tentativas cobrem, é aqui que você recupera o que perdeu.

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 }
}

• O id do histórico é um UUID próprio do registro. Ele não é o evt_… da entrega do webhook: para fazer a deduplicação entre os dois, use object_id mais type mais created_at.
• object_id chega como null nos eventos sem um objeto com UUID, como account.updated.
• A paginação é por cursor e estável: um evento novo não desloca a página que você está lendo. Veja Paginação.
• Um object_id que não é UUID ou um cursor inválido respondem 400 com code: "invalid_request".

Retenção

O histórico é somente de anexação: um evento não é editado depois de escrito. Ele é mantido por 90 dias e depois um processo diário o exclui; o evento que iniciou uma execução de um workflow é mantido enquanto essa execução existir, e uma execução é excluída um ano depois de terminar. O log de entregas de webhooks tem seu próprio prazo (30 dias; 90 para as que falharam). Tudo é excluído junto com a organização.

Verificar uma chave: GET /api/v1/me

É a chamada mais simples da API: confirma que a chave é válida e diz a qual organização ela pertence, a sua permissão e o seu modo. Responde a qualquer chave secreta, chave restrita ou conexão OAuth, independentemente das permissões por recurso.

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"
  }
}

Use-a para testar uma credencial antes de guardá-la na sua integração.