Usar a API do Cord a partir do Node.js

O SDK oficial para o seu backend é o @flouviahq/node. É um pacote separado do Cord Elements (que vive no navegador), sem dependências, e roda em Node 20+, Bun, Deno, Cloudflare Workers e Vercel. Se você usava @flouviahq/elements/server com CordAPI, ele continua funcionando, mas não recebe mais mudanças.

Instalação

npm install @flouviahq/node

Criar e listar

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

O SDK repete automaticamente só os erros de rede, 429 e 5xx, e cada operação leva uma Idempotency-Key que se repete nas novas tentativas: ele nunca cria a mesma coisa duas vezes.

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

Passe para ele o corpo bruto da requisição. Um aviso com a assinatura alterada ou com mais de 5 minutos é rejeitado. Para testá-los na sua máquina, use cord listen da CLI.

Sem o SDK

A API do Cord é REST padrão, então você também pode chamá-la com 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})`);

Lembre-se:

• Os valores vão na unidade da moeda do documento (1500 em MXN é MXN 1.500,00), não em centavos, e sempre com a moeda.
• Criar orçamentos, clientes ou produtos requer uma chave com permissão de escrita. Uma chave restrita (rk_) só acessa os recursos que você liberou para ela.
• Se você repetir uma criação por conta própria, envie o mesmo header Idempotency-Key em cada tentativa.