Quickstart

Create a test key. In the app, turn on Developer mode in Your account › Preferences and open the Developers pill in the bottom-right corner. In the API keys tab, create a read and write Secret Key in test mode (if the app is already in test mode, the key is created as a test key). It starts with sk_test_ and is shown only once: copy it.

Store it in a terminal variable. The Cord CLI reads it from there too:

export CORD_API_KEY="sk_test_..."

Check the key. GET /api/v1/me returns the key’s organization, permission and mode:

curl https://cordhq.app/api/v1/me \
  -H "Authorization: Bearer $CORD_API_KEY"

{
  "data": {
    "org": { "id": "5b1f7d9e-3c2a-4e8b-9f61-0a7c4d2e8b13", "nombre": "Aceros del Norte", "plan": "pro" },
    "scope": "write",
    "mode": "test"
  }
}

If you see "mode": "test", everything that follows happens in your test environment. A 401 with code: "invalid_key" means the key was copied wrong or was revoked.

Listen for webhooks on your machine. Cord can’t call your localhost, so the CLI opens a listening session and forwards each event to you with the real signature headers. First, the server that receives them. Install the SDK in an empty folder:

npm init -y && npm install @flouviahq/node

Save this as server.mjs:

import { createServer } from 'node:http';
import { constructEvent, CordWebhookSignatureError } from '@flouviahq/node';

createServer(async (req, res) => {
  if (req.method !== 'POST' || req.url !== '/webhooks/cord') {
    res.writeHead(404).end();
    return;
  }
  // The signature is computed over the RAW body: don't parse it before verifying.
  const chunks = [];
  for await (const chunk of req) chunks.push(chunk);
  try {
    const event = await constructEvent(Buffer.concat(chunks), req.headers, process.env.CORD_WEBHOOK_SECRET);
    console.log(event.event, event.id, event.data.id);
    res.writeHead(200).end('ok');
  } catch (err) {
    if (err instanceof CordWebhookSignatureError) {
      console.error('Signature rejected:', err.code);
      res.writeHead(400).end(err.code);
      return;
    }
    throw err;
  }
}).listen(3000, () => console.log('Listening on http://localhost:3000/webhooks/cord'));

In a second terminal (with the same CORD_API_KEY), open the listening session:

npx @flouviahq/cli listen --forward-to http://localhost:3000/webhooks/cord

The CLI prints the session secret (whsec_…). Start your server with it in the first terminal:

CORD_WEBHOOK_SECRET="whsec_..." node server.mjs

Leave both running. The session expires in 24 hours and Ctrl+C closes it.

Create a client. With an email address of yours:

curl https://cordhq.app/api/v1/clientes \
  -H "Authorization: Bearer $CORD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "empresa": "Ferretería La Prueba", "contacto": "Ana Torres", "email": "your-email@example.com" }'

{ "data": { "id": "0e6f2b8a-91c4-4d7e-b3a5-6c2d8f1e4a90" } }

Your server prints the first event:

client.created evt_4c1e9a7b2d5f8e0a3b6c9d2e5f8a1b4c 0e6f2b8a-91c4-4d7e-b3a5-6c2d8f1e4a90

Create the quote. Use the client’s id. Without tax_rate, each line takes the default rate from your account’s tax catalog; without base_currency, the quote uses your account’s currency.

curl https://cordhq.app/api/v1/cotizaciones \
  -H "Authorization: Bearer $CORD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6a1d3f5e-8b2c-4e7a-9d0f-1c3e5a7b9d2f" \
  -d '{
    "cliente_id": "0e6f2b8a-91c4-4d7e-b3a5-6c2d8f1e4a90",
    "items": [
      { "descripcion": "Window frame installation", "cantidad": 1, "precio_unitario": 12000 }
    ],
    "vigencia_dias": 15
  }'

{
  "data": {
    "id": "8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10",
    "token": "3f9a1c2e7b4d6f8a0b1c2d3e4f5a6b7c",
    "folio": "COT-0001",
    "link_publico": "https://cordhq.app/q/3f9a1c2e7b4d6f8a0b1c2d3e4f5a6b7c",
    "needs_approval": false,
    "motivo": null
  }
}

The quote starts as a draft and your server receives quote.created. The Idempotency-Key header makes retrying safe: with the same key and the same body, Cord returns this same response instead of creating a second quote. Generate a new key (for example with uuidgen) for each different quote.

Send it. Sending generates the link and emails the client:

curl https://cordhq.app/api/v1/cotizaciones/8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10 \
  -H "Authorization: Bearer $CORD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "send" }'

{ "data": { "ok": true, "status": "sent", "email": { "sent": true } } }

If the client had no email, email would come back as { "sent": false, "skipped": "el cliente no tiene correo" } and the quote would still be sent. Your server receives:

quote.sent evt_9d2a6c4e1f8b3a5d7c0e2f4a6b8d1c3e 8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10

Simulate the client. Open the link from the email or trigger the view with a simulator. In another terminal:

npx @flouviahq/cli simulate quote 8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10 vista

quote.viewed arrives. To close the loop, approve it through the API ({ "action": "approve" }) and quote.approved arrives.