Configuração assistida

Um agente ou o seu terminal propõe a configuração da conta; uma pessoa a revisa e a aprova.

O Cord lê o site de uma empresa, uma descrição com as palavras dela e a sua tabela de preços, e monta uma proposta de configuração: dados do perfil, marca, impostos, catálogo de produtos, modelos de mensagem e preferências de orçamento. É o mesmo assistente do onboarding e das Configurações, exposto por três portas para desenvolvedores:

Porta	Como
API REST	`POST /api/v1/setup/plans` e `GET /api/v1/setup/plans/{id}`
CLI	`cord setup` (veja CLI)
Servidor MCP	As ferramentas `proponer_configuracion` e `estado_configuracion` (veja Servidor MCP)

A IA nunca aplica nada

Nenhuma das três portas altera a conta. Todas devolvem um review_url: uma página do app em que uma pessoa com sessão iniciada e permissão de Configurações revisa a proposta, pode editá-la e a aplica ou a descarta. A proposta sempre configura a conta real à qual a chave pertence, mesmo que a chave seja de teste.

Propor uma configuração

Envie pelo menos um dos três campos:

Campo	Tipo	Detalhe
`sitio`	string	Site da empresa, por exemplo `materialesdelvalle.mx`. O Cord lê o texto, as cores, o logo, os e-mails e os telefones. Até 300 caracteres.
`descripcion`	string	O que a empresa faz, como recebe e quais impostos cobra ou retém, com as palavras dela. Até 4.000 caracteres; o restante é cortado.
`archivo`	objeto	A tabela de preços: `{ "nombre": "prices-2026.csv", "base64": "..." }`. Excel (`.xlsx`), CSV, PDF ou foto (PNG ou JPG), até 3 MB antes da codificação.

curl https://cordhq.app/api/v1/setup/plans \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "sitio": "materialesdelvalle.mx",
    "descripcion": "We sell building materials on 30-day credit and withhold 4% VAT on freight."
  }'

Para incluir a tabela de preços a partir do terminal:

curl https://cordhq.app/api/v1/setup/plans \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d "{\"sitio\":\"materialesdelvalle.mx\",\"archivo\":{\"nombre\":\"prices.csv\",\"base64\":\"$(base64 < prices.csv | tr -d '\n')\"}}"

A resposta é 201 Created:

{
  "data": {
    "object": "setup_plan",
    "id": "c7a2e9d1-4b6f-4f0a-8e3c-2d9b1a5f7e64",
    "estado": "propuesto",
    "review_url": "https://cordhq.app/app/setup/c7a2e9d1-4b6f-4f0a-8e3c-2d9b1a5f7e64",
    "resumen": "Building materials distributor with 30-day credit and VAT withholding on freight.",
    "conteos": { "perfil": 3, "marca": 2, "cotizaciones": 1, "impuestos": 1, "productos": 42, "plantillas": 2 },
    "avisos": [],
    "descartado": [
      { "campo": "perfil.telefono", "motivo": "No es un teléfono válido." }
    ]
  }
}

Campo	O que é
`review_url`	A página em que uma pessoa revisa e aplica a proposta. Compartilhe-a com quem administra a conta.
`resumen`	Uma linha com o que o Cord entendeu da empresa. Vem escrita no idioma da conta.
`conteos`	Quantas alterações cada seção traz.
`avisos`	O que não foi possível ler, por exemplo um site que não respondeu ou uma tabela com colunas que não foram reconhecidas. A proposta sai mesmo assim com o restante.
`descartado`	Dados que a IA propôs e que não passaram na validação do Cord (formato fiscal, alíquotas, preços). Nunca chegam à proposta.

O Cord propõe apenas o que a fonte sustenta: uma identificação fiscal só se aparecer literalmente, um produto só se tiver preço e um imposto só se ainda não estiver no seu catálogo. Cada dado passa pelas mesmas regras do país que as Configurações.

Consultar o status

curl https://cordhq.app/api/v1/setup/plans/c7a2e9d1-4b6f-4f0a-8e3c-2d9b1a5f7e64 \
  -H "Authorization: Bearer sk_test_..."

{
  "data": {
    "object": "setup_plan",
    "id": "c7a2e9d1-4b6f-4f0a-8e3c-2d9b1a5f7e64",
    "estado": "aplicado",
    "review_url": "https://cordhq.app/app/setup/c7a2e9d1-4b6f-4f0a-8e3c-2d9b1a5f7e64",
    "resultado": [
      { "seccion": "perfil", "ok": true, "detalle": "6 ajustes" },
      { "seccion": "impuestos", "ok": true, "detalle": "1 de 1" },
      { "seccion": "productos", "ok": true, "detalle": "40 nuevos, 2 actualizados" },
      { "seccion": "plantillas", "ok": true, "detalle": "2 de 2" }
    ],
    "created_at": "2026-10-07T16:20:41.512Z",
    "aplicado_at": "2026-10-07T16:24:03.007Z",
    "expira_at": "2026-10-14T16:20:41.512Z"
  }
}

`estado`	Significado
`generando`	O Cord ainda está montando a proposta.
`propuesto`	Pronta e aguardando que uma pessoa a revise em `review_url`.
`aplicado`	Uma pessoa a aplicou. `resultado` traz uma linha por seção com `ok` e `detalle`; se alguma seção falhou, as demais são aplicadas mesmo assim.
`descartado`	Uma pessoa a descartou. Nada foi alterado.
`fallido`	Não foi possível concluir a proposta, ou todas as seções falharam ao aplicá-la.

resultado é null até que a proposta seja aplicada. Para aguardar a decisão, consulte a cada poucos segundos (a CLI consulta a cada 3) e pare ao chegar a aplicado, descartado ou fallido.

Limites

Limite	Valor
Propostas por organização	6 por dia, somando a API, a CLI, o MCP e o app. A sétima responde `429` com `code: "rate_limited"`.
Validade	7 dias (`expira_at`). Uma proposta expirada não pode mais ser aplicada; gere uma nova.
Arquivo	3 MB antes da codificação em base64. Acima disso responde `413`.
Catálogo proposto	Até 500 produtos, 6 impostos e 4 modelos.

Erros

Situação	Resposta
Você não enviou `sitio`, `descripcion` nem `archivo`	`400`, `code: "invalid_request"`
O arquivo não é Excel, CSV, PDF nem foto, ou está vazio	`400`, `code: "invalid_request"`, com o motivo em `error`
O arquivo tem mais de 3 MB	`413`, `code: "invalid_request"`
Já foram geradas 6 propostas hoje	`429`, `code: "rate_limited"`
O Cord não conseguiu concluir a proposta	`502` com a mensagem em `error`; a proposta fica como `fallido`
O `id` não existe na sua conta	`404`, `code: "not_found"`

Chaves e permissões

Propor exige permissão de escrita no recurso setup; consultar, de leitura. Uma chave restrita com apenas setup é suficiente. A chave que o cord login entrega já a inclui.
A página de revisão exige uma sessão com permissão de Configurações nessa conta. Ninguém mais pode aplicar.
A aplicação fica registrada na auditoria da organização, com quem a fez.

Pela CLI

npx @flouviahq/cli setup --sitio materialesdelvalle.mx --archivo prices.xlsx

A CLI envia a proposta, abre o review_url no seu navegador e aguarda a sua decisão. Quando você aprova, ela imprime o resultado por seção. Enter para de aguardar sem cancelar nada: a proposta continua esperando por você no link durante 7 dias.

A partir de um agente (MCP)

proponer_configuracion recebe sitio, descripcion, archivo_base64 e archivo_nombre e devolve o mesmo que a API (id, estado, review_url, resumen, conteos, avisos, descartado). estado_configuracion recebe o id e devolve estado, review_url, resultado, creada, aplicada e vence. O agente deve compartilhar o review_url com a pessoa: ele não tem como aplicar a proposta por conta própria.