Server-Proxy

Der Browser spricht mit Ihrem Backend und Ihr Backend mit Cord: Kein Schlüssel gelangt je auf die Seite.

Cord Elements funktioniert auf zwei Arten: mit einem veröffentlichbaren Schlüssel (pk_) direkt zu Cord oder mit proxyUrl, wobei Ihr eigenes Backend die Anfragen bedient und Cord mit einem Server-Schlüssel aufruft. Verwenden Sie den Proxy, wenn der Builder Ihr Kundenverzeichnis lesen, das Angebot per E-Mail senden oder verhandelte Preise festlegen soll: Dinge, die ein pk_-Schlüssel nie kann.

Der Proxy steckt in @flouviahq/node, dem Server-SDK. Dieses Paket ersetzt das frühere @flouviahq/elements/server, das weiterhin funktioniert, aber keine Änderungen mehr erhält.

Einrichten

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 ist Ihre eigene Sitzungsfunktion. createElementsProxy gibt einen Handler (Request) => Promise<Response> zurück und funktioniert deshalb gleich in Next.js, Astro, Remix, Hono, Bun oder Cloudflare Workers. cord init legt ihn in einem Next.js-Projekt für Sie an.

Was er bedient

Anfrage des Browsers	Ruft Cord auf	Bedingung
`GET {proxyUrl}/elements/config`	`GET /api/v1/elements/config`	Immer.
`GET {proxyUrl}/productos`	`GET /api/v1/productos`	Immer.
`POST {proxyUrl}/cotizaciones`	`POST /api/v1/cotizaciones`	Immer, mit bereinigtem Body.
`POST {proxyUrl}/elements/ai-draft`	`POST /api/v1/elements/ai-draft`	Immer. Der KI-Stream wird unverändert weitergeleitet; Dateien bis 4 MB.
`GET {proxyUrl}/clientes`	`GET /api/v1/clientes?limit=200`	Nur wenn `authorizeClients` `true` zurückgibt. Sonst `403` mit `code: "clients_require_proxy"`.

Jede andere Route oder Methode gibt 404 zurück. Der Proxy wiederholt nichts: Der Browser wiederholt bereits selbst.

Optionen

Option	Detail
`secretKey`	Pflicht. Ein `sk_`- oder `rk_`-Schlüssel.
`allowedOrigins`	Origins, die den Proxy nutzen dürfen. Standardmäßig nur der Origin der Anfrage selbst: Ein Proxy, der für jede Website offen ist, ist gleichbedeutend mit der Veröffentlichung Ihres Schlüssels.
`authorizeClients(request)`	Erlaubt das Lesen des Kundenverzeichnisses. Ohne diese Option wird es nie gelesen.
`authorizeSellerFields(request)`	Erlaubt die Verkäuferfelder beim Erstellen: `cliente_id`, `send` (per E-Mail senden), `fiscal_currency` und in jeder Position `precio_negociado` und `costo_unitario`. Ohne diese Option werden sie verworfen, und das Angebot entsteht als Entwurf, genau wie mit einem `pk_`-Schlüssel.
`baseUrl`	Origin von Cord. Standard: `https://cordhq.app`.
`fetch`	Für 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',
});

Der Proxy leitet den Idempotency-Key des Browsers weiter (der Builder sendet einen pro Sendeversuch) und gibt die Fehler von Cord mit ihrem code, ihrer request_id und ihrer doc_url zurück.

Geben Sie dem Proxy einen eingeschränkten Schlüssel

Der Proxy braucht keinen Secret Key mit allen Berechtigungen. Erstellen Sie unter Entwickler › Schlüssel einen eingeschränkten Schlüssel (rk_) mit nur diesen Rechten:

Ressource	Stufe	Wofür
`elements`	Schreiben	Konfiguration und KI-Befüllung der Positionen
`productos`	Lesen	Der Katalog des Builders
`cotizaciones`	Schreiben	Das Angebot erstellen
`clientes`	Lesen	Nur wenn Sie `authorizeClients` verwenden

Dialog „Neuer API-Schlüssel (LIVE)“ mit dem Typ Eingeschränkt (Backend) und den Berechtigungen pro Ressource für den Elements-Proxy: Angebote und Elements mit Schreibzugriff, Produkte und Kunden mit Lesezugriff, alles andere ohne Zugriff; die MCP-Tools zum Lesen und Entwürfe schreiben, ohne Aktionen mit externer Wirkung; dazu eine zulässige IP und Ablauf nach 90 Tagen.

Wird Ihr Server kompromittiert, kann dieser Schlüssel weder Rechnungen noch Forderungsmanagement noch Webhooks lesen. Sie können außerdem die IP-Adressen Ihres Servers festlegen und ein Ablaufdatum setzen. Siehe Authentifizierung.

Debugging

Jeder Aufruf des Proxys an Cord erscheint in der Workbench unter Entwickler › Protokolle mit seiner request_id, Methode, Route, Status, Dauer und IP-Adresse. Dieselbe request_id erreicht den Browser im Header Cord-Request-Id und im Body eines Fehlers.