Utiliser l’API de Cord depuis Node.js

Le SDK officiel pour votre backend est @flouviahq/node. Il s’agit d’un paquet distinct de Cord Elements (qui s’exécute dans le navigateur), sans dépendances, qui fonctionne sur Node 20+, Bun, Deno, Cloudflare Workers et Vercel. Si vous utilisiez @flouviahq/elements/server avec CordAPI, cela fonctionne toujours, mais ne reçoit plus de modifications.

Installation

npm install @flouviahq/node

Créer et lister

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

const cord = new Cord(process.env.CORD_SECRET_KEY!); // sk_live_..., sk_test_... ou 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);
}

Le SDK ne relance que les erreurs réseau, les 429 et les 5xx, et chaque opération porte une Idempotency-Key répétée lors de ses nouvelles tentatives : il ne crée jamais deux fois la même chose.

Vérifier les webhooks

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');
}

Transmettez-lui le corps brut de la requête. Un événement dont la signature a été altérée ou datant de plus de 5 minutes est rejeté. Pour les tester sur votre machine, utilisez cord listen du CLI.

Sans le SDK

L’API de Cord est une API REST standard : vous pouvez donc aussi l’appeler avec fetch :

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})`);

À retenir :

• Les montants sont exprimés dans l’unité de la devise du document (1500 en MXN correspond à 1 500,00 MXN), et non en centimes, et toujours avec leur devise.
• Créer des devis, des clients ou des produits nécessite une clé disposant du droit d’écriture. Une clé restreinte (rk_) ne peut agir que sur les ressources que vous lui avez accordées.
• Si vous relancez vous-même une création, envoyez le même en-tête Idempotency-Key à chaque tentative.