Ereignisse

Jede relevante Änderung in Cord erzeugt ein Ereignis: einen Datensatz mit Typ, Objekt, Daten und dem Auslöser. Dieselben Ereignisse werden an Ihre Webhooks zugestellt, lösen Cord Workflows aus und bleiben in einem Verlauf erhalten, den Sie mit GET /api/v1/events abfragen – unabhängig davon, ob Endpoints abonniert sind.

Ereigniskatalog

Es gibt 41 Typen. Die Spalte Objekt ist der Wert von object im Verlauf und bestimmt die Form von data (siehe nächster Abschnitt).

ping ist kein Ereignis des Katalogs: Es ist die Testzustellung der Schaltfläche Testen in der Workbench und erscheint nie im Verlauf.

Form von data pro Objekt

Jeder Betrag wird mit seiner Währung in moneda übertragen. Die Feldnamen sind die des Servers, auf Spanisch.

Zusätzliche Felder pro Ereignis:

Bei einer Rechnung ist estado ihr Lebenszyklus (draft, open, paid, void oder uncollectible) und estado_fiscal ihre Registrierung beim Steueranbieter (pending, issued, cancelled oder error). Bei einem Angebot ist status einer der Werte draft, sent, viewed, approved, rejected, expired, invoiced oder paid.

Das im Verlauf gespeicherte data entspricht dem des Webhooks, jedoch ohne link_publico: Der Link ist eine Zugangsberechtigung des Kunden und wird nicht gespeichert.

Wer das Ereignis ausgelöst hat: actor

Behandeln Sie actor als Text mit Präfix: Entscheiden Sie anhand dessen, was vor dem Doppelpunkt steht, und gehen Sie nicht davon aus, dass die Liste nicht wächst.

Verlauf: GET /api/v1/events

Gibt die Ereignisse Ihrer Organisation zurück, das neueste zuerst. War Ihr Server länger ausgefallen, als die Wiederholungsversuche abdecken, holen Sie hier nach, was Sie verpasst haben.

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

• Die id des Verlaufs ist eine eigene UUID des Datensatzes. Sie ist nicht die evt_… der Webhook-Zustellung: Um zwischen beiden zu deduplizieren, verwenden Sie object_id plus type plus created_at.
• object_id kommt bei Ereignissen ohne Objekt mit UUID als null, etwa bei account.updated.
• Die Paginierung erfolgt per Cursor und ist stabil: Ein neues Ereignis verschiebt die Seite, die Sie gerade lesen, nicht. Siehe Paginierung.
• Eine object_id, die keine UUID ist, oder ein ungültiger cursor antworten mit 400 und code: "invalid_request".

Aufbewahrung

Der Verlauf ist nur erweiterbar: Ein Ereignis wird nach dem Schreiben nicht bearbeitet. Es wird 90 Tage aufbewahrt und danach von einem täglichen Prozess gelöscht; ein Ereignis, das eine Workflow-Ausführung gestartet hat, bleibt so lange erhalten wie diese Ausführung, und eine Ausführung wird ein Jahr nach ihrem Ende gelöscht. Das Zustellprotokoll der Webhooks hat eine eigene Frist (30 Tage; 90 für fehlgeschlagene). Alles wird zusammen mit der Organisation gelöscht.

Einen Schlüssel prüfen: GET /api/v1/me

Das ist der einfachste Aufruf der API: Er bestätigt, dass der Schlüssel gültig ist, und gibt an, zu welcher Organisation er gehört, welche Berechtigung und welchen Modus er hat. Er antwortet auf jeden geheimen Schlüssel, eingeschränkten Schlüssel oder jede OAuth-Verbindung, unabhängig von den Berechtigungen pro 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"
  }
}

Verwenden Sie den Aufruf, um Zugangsdaten zu prüfen, bevor Sie sie in Ihrer Integration speichern.