Die Cord-API aus Node.js verwenden

Das offizielle SDK für Ihr Backend ist @flouviahq/node. Es ist ein eigenes Paket, getrennt von Cord Elements (das im Browser läuft), ohne Abhängigkeiten, und läuft auf Node 20+, Bun, Deno, Cloudflare Workers und Vercel. Wenn Sie @flouviahq/elements/server mit CordAPI verwendet haben, funktioniert es weiterhin, erhält aber keine Änderungen mehr.

Installation

npm install @flouviahq/node

Erstellen und auflisten

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

const cord = new Cord(process.env.CORD_SECRET_KEY!); // sk_live_..., sk_test_... oder rk_...

try {
  const quote = await cord.quotes.create({
    cliente: { empresa: 'Acme', email: 'purchasing@acme.com' },
    items: [{ descripcion: 'Installation', cantidad: 1, precio_unitario: 12500, tax_rate: 0.16 }],
    base_currency: 'MXN',
  });
  console.log(quote.folio, quote.link_publico);
} catch (err) {
  if (err instanceof CordError) console.error(err.code, err.requestId);
}

for await (const invoice of cord.invoices.listAll({ estado: 'open' })) {
  console.log(invoice.numero, invoice.saldo);
}

Das SDK wiederholt nur Netzwerkfehler, 429 und 5xx, und jeder Vorgang trägt einen Idempotency-Key, der bei seinen Wiederholungen gleich bleibt: Es legt nie zweimal dasselbe an.

Webhooks verifizieren

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

export async function POST(req: Request) {
  const event = await constructEvent(await req.text(), req.headers, process.env.CORD_WEBHOOK_SECRET!);
  // event.event: 'quote.approved', 'invoice.paid', ...
  return new Response('ok');
}

Übergeben Sie den unveränderten Rohinhalt der Anfrage. Ein Ereignis mit veränderter Signatur oder einem Alter von mehr als 5 Minuten wird abgelehnt. Um sie auf Ihrem Rechner zu testen, verwenden Sie cord listen aus der CLI.

Ohne SDK

Die Cord-API ist Standard-REST, Sie können sie also auch mit fetch aufrufen:

const res = await fetch('https://cordhq.app/api/v1/cotizaciones', {
  headers: { Authorization: `Bearer ${process.env.CORD_SECRET_KEY}` },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.error} (${body.request_id})`);

Denken Sie daran:

• Beträge werden in der Einheit der Dokumentwährung angegeben (1500 in MXN sind 1.500,00 MXN), nicht in Cent, und immer mit ihrer Währung.
• Zum Erstellen von Angeboten, Kunden oder Produkten ist ein Schlüssel mit Schreibberechtigung erforderlich. Ein eingeschränkter Schlüssel (rk_) kann nur die Ressourcen bearbeiten, die Sie ihm freigegeben haben.
• Wenn Sie eine Erstellung selbst wiederholen, senden Sie bei jedem Versuch denselben Header Idempotency-Key.