Eventos

Cada cambio relevante en Cord produce un evento: un registro con tipo, objeto, datos y quién lo originó. Los mismos eventos se entregan a tus webhooks, disparan Cord Workflows y quedan en un historial que consultas con GET /api/v1/events, haya o no endpoints suscritos.

Catálogo de eventos

Hay 41 tipos. La columna Objeto es el valor de object en el historial y decide la forma de data (ver la sección siguiente).

ping no es un evento del catálogo: es la entrega de prueba del botón Probar del Workbench y nunca aparece en el historial.

Forma de data por objeto

Todo importe viaja con su divisa en moneda. Los nombres de campo son los del servidor, en español.

Campos extra por evento:

En una factura, estado es su ciclo de vida (draft, open, paid, void o uncollectible) y estado_fiscal su registro ante el proveedor fiscal (pending, issued, cancelled o error). En una cotización, status es draft, sent, viewed, approved, rejected, expired, invoiced o paid.

El data que guarda el historial es el mismo del webhook sin link_publico: el link es una credencial del cliente y no se guarda.

Quién originó el evento: actor

Trata actor como texto con un prefijo: decide por lo que va antes de los dos puntos y no asumas que la lista no crecerá.

Historial: GET /api/v1/events

Devuelve los eventos de tu organización, del más nuevo al más viejo. Si tu servidor estuvo caído más tiempo del que cubren los reintentos, aquí recuperas lo que te perdiste.

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

• El id del historial es un UUID propio del registro. No es el evt_… de la entrega del webhook: para deduplicar entre los dos, usa object_id más type más created_at.
• object_id llega null en los eventos sin un objeto con UUID, como account.updated.
• La paginación es por cursor y estable: un evento nuevo no desplaza la página que estás leyendo. Ver Paginación.
• Un object_id que no es UUID o un cursor inválido responden 400 con code: "invalid_request".

Retención

El historial es de solo anexar: un evento no se edita después de escribirse. Se conserva 90 días y luego un proceso diario lo borra; el que inició una ejecución de un workflow se conserva mientras exista esa ejecución, que se borra un año después de terminar. El log de entregas de webhooks tiene su propio plazo (30 días; 90 los fallidos). Todo se elimina con la organización.

Verificar una llave: GET /api/v1/me

Es la llamada más simple de la API: confirma que la llave es válida y dice a qué organización pertenece, su permiso y su modo. Responde con cualquier llave secreta, restringida o conexión OAuth, sin importar sus permisos 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"
  }
}

Úsala para probar una credencial antes de guardarla en tu integración.