Proxy serveur

Le navigateur parle à votre backend et votre backend parle à Cord : aucune clé n’arrive jamais sur la page.

Cord Elements fonctionne de deux façons : avec une clé publiable (pk_) directement vers Cord, ou avec proxyUrl, où votre propre backend traite les requêtes et appelle Cord avec une clé serveur. Utilisez le proxy lorsque vous voulez que le Builder lise votre annuaire de clients, envoie le devis par e-mail ou fixe des prix négociés : des choses qu’une clé pk_ ne peut jamais faire.

Le proxy se trouve dans @flouviahq/node, le SDK serveur. Ce paquet remplace l’ancien @flouviahq/elements/server, qui fonctionne toujours mais ne reçoit plus de modifications.

Le mettre en place

npm install @flouviahq/node

// app/api/cord/[...path]/route.ts (Next.js App Router)
import { createElementsProxy } from '@flouviahq/node';

const proxy = createElementsProxy({
  secretKey: process.env.CORD_SECRET_KEY!,
  authorizeClients: async (req) => Boolean(await getSession(req)),
});

export const GET = proxy;
export const POST = proxy;

<CordProvider proxyUrl="/api/cord">
  <CordBuilder />
</CordProvider>

getSession est votre propre fonction de session. createElementsProxy renvoie un handler (Request) => Promise<Response> : il fonctionne donc de la même façon avec Next.js, Astro, Remix, Hono, Bun ou Cloudflare Workers. cord init le crée pour vous dans un projet Next.js.

Ce qu’il traite

Requête du navigateur	Appel à Cord	Condition
`GET {proxyUrl}/elements/config`	`GET /api/v1/elements/config`	Toujours.
`GET {proxyUrl}/productos`	`GET /api/v1/productos`	Toujours.
`POST {proxyUrl}/cotizaciones`	`POST /api/v1/cotizaciones`	Toujours, avec le corps assaini.
`POST {proxyUrl}/elements/ai-draft`	`POST /api/v1/elements/ai-draft`	Toujours. Le flux de l’IA est retransmis tel quel ; fichier jusqu’à 4 Mo.
`GET {proxyUrl}/clientes`	`GET /api/v1/clientes?limit=200`	Uniquement si `authorizeClients` renvoie `true`. Sinon, `403` avec `code: "clients_require_proxy"`.

Toute autre route ou méthode renvoie 404. Le proxy ne fait pas de nouvelles tentatives : le navigateur en fait déjà de lui-même.

Options

Option	Détail
`secretKey`	Obligatoire. Une clé `sk_` ou `rk_`.
`allowedOrigins`	Les origines autorisées à utiliser le proxy. Par défaut, uniquement l’origine de la requête elle-même : un proxy ouvert à n’importe quel site revient à publier votre clé.
`authorizeClients(request)`	Autorise la lecture de l’annuaire de clients. Sans cette option, il n’est jamais lu.
`authorizeSellerFields(request)`	Autorise les champs réservés au commercial lors de la création : `cliente_id`, `send` (envoyer par e-mail), `fiscal_currency` et, sur chaque ligne, `precio_negociado` et `costo_unitario`. Sans cette option, ils sont écartés et le devis est créé en brouillon, comme avec une clé `pk_`.
`baseUrl`	L’origine de Cord. Par défaut, `https://cordhq.app`.
`fetch`	Pour les tests.

const proxy = createElementsProxy({
  secretKey: process.env.CORD_PROXY_KEY!,
  allowedOrigins: ['https://portal.yourcompany.com'],
  authorizeClients: async (req) => (await getSession(req))?.role === 'seller',
  authorizeSellerFields: async (req) => (await getSession(req))?.role === 'seller',
});

Le proxy retransmet l’Idempotency-Key du navigateur (le Builder en envoie une par tentative d’envoi) et renvoie les erreurs de Cord avec leur code, leur request_id et leur doc_url.

Donnez au proxy une clé restreinte

Le proxy n’a pas besoin d’une clé secrète dotée de tous les droits. Créez une clé restreinte (rk_) dans Développeurs › Clés API avec uniquement ceci :

Ressource	Niveau	Usage
`elements`	écriture	Configuration et remplissage des lignes par IA
`productos`	lecture	Le catalogue du Builder
`cotizaciones`	écriture	Créer le devis
`clientes`	lecture	Uniquement si vous utilisez `authorizeClients`

Boîte de dialogue « Nouvelle clé API LIVE » avec le type Restreinte (backend) sélectionné et les droits par ressource du proxy Elements : Devis et Elements en écriture, Produits et Clients en lecture, le reste sans accès ; les outils MCP de lecture et d’écriture de brouillons, sans les actions à effet externe ; avec une IP autorisée et une expiration à 90 jours.

Si votre serveur est compromis, cette clé ne peut lire ni les factures, ni le recouvrement, ni les webhooks. Vous pouvez en outre restreindre la clé aux IP de votre serveur et lui fixer une date d’expiration. Voir Authentification.

Déboguer

Chaque appel du proxy à Cord apparaît dans Développeurs › Journaux du Workbench avec son request_id, sa méthode, sa route, son statut, sa durée et son IP. Le même request_id parvient au navigateur dans l’en-tête Cord-Request-Id et dans le corps d’une erreur.