Proxy de servidor
O navegador fala com o seu backend e o seu backend fala com o Cord: nenhuma chave chega à página.
O Cord Elements funciona de duas maneiras: com uma chave publicável (pk_) direto para o Cord, ou com proxyUrl, em que o seu próprio backend atende as requisições e chama o Cord com uma chave de servidor. Use o proxy quando quiser que o Builder leia o seu cadastro de clientes, envie o orçamento por e-mail ou fixe preços negociados: coisas que uma chave pk_ nunca pode fazer.
O proxy vive no @flouviahq/node, o SDK de servidor. Esse pacote substitui o antigo @flouviahq/elements/server, que continua funcionando, mas não recebe mais alterações.
Montar o proxy
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 é a sua própria função de sessão. createElementsProxy devolve um handler (Request) => Promise<Response>, então funciona da mesma forma em Next.js, Astro, Remix, Hono, Bun ou Cloudflare Workers. O cord init o cria para você em um projeto Next.js.
O que ele atende
| Requisição do navegador | Chama o Cord | Condição |
|---|---|---|
GET {proxyUrl}/elements/config |
GET /api/v1/elements/config |
Sempre. |
GET {proxyUrl}/productos |
GET /api/v1/productos |
Sempre. |
POST {proxyUrl}/cotizaciones |
POST /api/v1/cotizaciones |
Sempre, com o corpo sanitizado. |
POST {proxyUrl}/elements/ai-draft |
POST /api/v1/elements/ai-draft |
Sempre. O stream da IA é reencaminhado como está; arquivo de até 4 MB. |
GET {proxyUrl}/clientes |
GET /api/v1/clientes?limit=200 |
Só se authorizeClients devolver true. Caso contrário, 403 com code: "clients_require_proxy". |
Qualquer outra rota ou método responde 404. O proxy não faz novas tentativas: o navegador já as faz por conta própria.
Opções
| Opção | Detalhe |
|---|---|
secretKey |
Obrigatória. Uma chave sk_ ou rk_. |
allowedOrigins |
Origens que podem usar o proxy. Por padrão, apenas a origem da própria requisição: um proxy aberto a qualquer site equivale a publicar a sua chave. |
authorizeClients(request) |
Autoriza a leitura do cadastro de clientes. Sem ela, ele nunca é lido. |
authorizeSellerFields(request) |
Autoriza os campos de vendedor na criação: cliente_id, send (enviar por e-mail), fiscal_currency e, em cada linha, precio_negociado e costo_unitario. Sem ela, esses campos são descartados e o orçamento nasce como rascunho, como com uma chave pk_. |
baseUrl |
Origem do Cord. Padrão https://cordhq.app. |
fetch |
Para testes. |
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',
});O proxy reencaminha a Idempotency-Key do navegador (o Builder envia uma por tentativa de envio) e devolve os erros do Cord com o seu code, request_id e doc_url.
Dê ao proxy uma chave restrita
O proxy não precisa de uma Secret Key com todas as permissões. Crie uma chave restrita (rk_) em Desenvolvedores › Chaves com apenas isto:
| Recurso | Nível | Para quê |
|---|---|---|
elements |
escrita | Configuração e preenchimento de itens com IA |
productos |
leitura | O catálogo do Builder |
cotizaciones |
escrita | Criar o orçamento |
clientes |
leitura | Só se você usar authorizeClients |
Se o seu servidor for comprometido, essa chave não pode ler faturas, cobrança nem webhooks. Você também pode fixar os IPs do seu servidor e definir um vencimento. Veja Autenticação.
Depurar
Cada chamada do proxy ao Cord fica em Desenvolvedores › Logs do Workbench, com o seu request_id, método, rota, status, duração e IP. O mesmo request_id chega ao navegador no header Cord-Request-Id e no corpo de um erro.