Designs

Os designs do Cord Studio como código: guarde-os no seu repositório, verifique-os antes de enviá-los e escolha com qual sai cada orçamento.

Visão geral

Um design do Cord Studio decide como o seu cliente vê o link do orçamento: a ordem dos blocos, o conteúdo, o estilo e o que ele muda do tema da sua empresa. Pela API, é o mesmo documento JSON que a aba Código do editor visual mostra, e o Cord o valida com as mesmas regras: os blocos de que o seu cliente precisa antes de aprovar, o contraste de 4,5 para 1 e as mídias da biblioteca da sua empresa.

Com a API, você pode guardar os seus designs no seu repositório, verificá-los na sua CI e enviá-los para a sua conta. As operações completas, com cada campo, estão na Referência da API.

Campo	O que é
`object`	Sempre `"diseno"`.
`id`	UUID do design.
`nombre`	De 1 a 80 caracteres.
`descripcion`	Descrição interna, até 280 caracteres; `null` sem descrição. O seu cliente não a vê.
`predeterminado`	`true` se é o design com que saem os orçamentos que não escolhem outro. Só um é o padrão de cada vez.
`actualizado`	Última edição, ISO 8601.
`diseno`	O documento: `esquema` (hoje `1`), `temaOverrides` (o que o design muda do tema da sua empresa) e `paginas`, cada uma com os seus `bloques` (`id`, `tipo`, `props` e `estilo`). Só vem no detalhe e nas respostas de criar e editar.

Listar e consultar

GET /api/v1/disenos devolve os seus designs não arquivados, sem o documento: primeiro o padrão e depois do editado mais recentemente ao mais antigo. Não é paginado, porque uma conta tem até 100.

curl "https://cordhq.app/api/v1/disenos" \
     -H "Authorization: Bearer sk_live_tU..."

{
  "data": [
    { "object": "diseno", "id": "5b2e8c41-7d3a-4f19-9e6b-0c4a2d8f1b73", "nombre": "Proposta de obra", "descripcion": "Com capa, cronograma e garantia", "predeterminado": true, "actualizado": "2026-11-10T16:42:08.000Z" },
    { "object": "diseno", "id": "c8d1f6a2-3e4b-4a7c-8f05-6b9e2d1c7a40", "nombre": "Manutenção mensal", "descripcion": null, "predeterminado": false, "actualizado": "2026-11-08T19:05:31.000Z" }
  ]
}

GET /api/v1/disenos/{id} devolve um design com o documento em diseno. O id de um design que não existe ou que está arquivado responde 404 not_found.

Criar um design

POST /api/v1/disenos aceita nombre, descripcion e uma destas duas fontes, nunca as duas juntas:

diseno: um documento completo, por exemplo um que você baixou com GET /api/v1/disenos/{id} ou copiou da aba Código.
plantilla: um dos dezoito modelos da galeria: agencia, arquitectura, eventos, consultoria, software, fotografia, industrial, salud, educacion, inmobiliaria, minimal, editorial, noche, brutalista, tropical, gala, pop ou escenario. Os textos saem no idioma da sua conta e com os usos do país da sua empresa, e sem nombre o design recebe o nome do modelo. gala, pop e escenario personalizam os blocos do Cord: sem o plano Profissional respondem 402 subscription_required.

Sem nenhuma das duas, o design nasce como o Cartão do Cord, o design de sempre, e se chama "Diseño nuevo". Um design novo não é o padrão: para usá-lo, marque-o como explica a seção seguinte.

curl -X POST "https://cordhq.app/api/v1/disenos" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: design-obra-2027" \
     -d '{ "plantilla": "arquitectura", "nombre": "Proposta de obra 2027" }'

Responde com o design criado, com o documento. Com um diseno que não passa na validação, responde 400 invalid_request com issues (veja Validar sem salvar), e se a sua conta já tiver 100 designs não arquivados, 409 disenos_tope.

Editar e definir o padrão

PATCH /api/v1/disenos/{id} muda o que você envia e mantém o resto:

Campo	Efeito
`nombre`, `descripcion`	Substituem os salvos; `descripcion: null` a remove.
`diseno`	Substitui o documento inteiro. O Cord o valida como na criação.
`predeterminado`	`true` o usa nos orçamentos enviados a partir de agora, e o anterior deixa de ser o padrão. `false` no padrão deixa de usá-lo: os seus orçamentos voltam a sair com o Cartão do Cord.

curl -X PATCH "https://cordhq.app/api/v1/disenos/5b2e8c41-7d3a-4f19-9e6b-0c4a2d8f1b73" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: padrao-obra-2027" \
     -d '{ "predeterminado": true }'

Responde com o design atualizado. Editar um design ou mudar o padrão não mexe no que os seus clientes já receberam: cada orçamento congela o seu design ao ser enviado.

Validar sem salvar

POST /api/v1/disenos/validar recebe { "diseno": { … } } e o verifica como o editor, sem salvar nada. Use-o na sua CI antes de enviar um design; basta uma chave com leitura sobre disenos.

curl -X POST "https://cordhq.app/api/v1/disenos/validar" \
     -H "Authorization: Bearer sk_test_tU..." \
     -H "Content-Type: application/json" \
     -d @disenos/proposta-de-obra.json

Se o design pode ser salvo, responde 200 com object: "diseno_validacion", valido: true, avisos (o que não impede salvar, mas vale revisar, como uma variável que não existe ou um texto difícil de ler), diseno (o documento como o Cord o salvaria, com os valores padrão que ele completa) e personaliza_bloques_cord, que diz se salvá-lo assim precisa do plano Profissional.

Se não, responde 400 invalid_request. issues traz cada problema com o caminho em path (separado por pontos), o que está errado em message e um código estável em codigo, como esquema, falta_bloque, orden_aprobacion, contraste, superficie_no_solida ou medio_desconocido. field é o caminho do primeiro:

{
  "error": "diseno.paginas: Falta un bloque que el cliente necesita ver antes de aprobar.",
  "code": "invalid_request",
  "field": "diseno.paginas",
  "issues": [
    { "path": "diseno.paginas", "message": "Falta un bloque que el cliente necesita ver antes de aprobar.", "codigo": "falta_bloque" },
    { "path": "diseno.paginas.0.bloques.4.props.medio", "message": "Este medio no está en la biblioteca del negocio.", "codigo": "medio_desconocido" }
  ]
}

As mensagens de message chegam em espanhol. Um design aceita até 60 blocos e 64 KB, e só usa imagens e vídeos da biblioteca de mídia da sua empresa, que você envia na aba Mídia do editor; no ambiente de teste, também os da sua conta real. Criar e editar devolvem a mesma resposta 400 quando o design não passa.

Arquivar

DELETE /api/v1/disenos/{id} arquiva o design e responde { "data": { "id": "…", "archivado": true } }. Ele deixa de aparecer na lista e de contar no limite de 100. Os orçamentos que já foram enviados com ele não mudam, e um rascunho que o tinha escolhido sai com o padrão.

curl -X DELETE "https://cordhq.app/api/v1/disenos/c8d1f6a2-3e4b-4a7c-8f05-6b9e2d1c7a40" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Idempotency-Key: arquivar-manutencao"

O padrão não é arquivado: responde 409 no_archivable. Marque outro design como padrão, ou tire a marca com predeterminado: false, e tente de novo.

Escolher o design de um orçamento

POST /api/v1/cotizaciones e PATCH /api/v1/cotizaciones/{id} aceitam diseno_id: o id de um dos seus designs, ou null para o orçamento sair com o padrão. Só muda um rascunho: um orçamento enviado mantém o design com que saiu. Com uma chave publicável, o Cord ignora diseno_id.

curl -X PATCH "https://cordhq.app/api/v1/cotizaciones/2a9d8e4f-6b1c-4d7a-9e3f-5c8b1a2d4e6f" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: design-orcamento-2a9d8e4f" \
     -d '{ "diseno_id": "c8d1f6a2-3e4b-4a7c-8f05-6b9e2d1c7a40" }'

O detalhe do orçamento traz diseno_id, o design escolhido (null se ele sai com o padrão), e diseno_propio, true se alguém criou um design só para ele no editor; esse design prevalece sobre diseno_id. Ao enviá-lo, o Cord usa o design próprio, o escolhido, o padrão ou o Cartão do Cord, nessa ordem, e o congela. Mais em API de Orçamentos e em Crie o design de um único orçamento.

Na sua página, o <CordBuilder disenoId> do Cord Elements cria o orçamento com um design: uma chave publicável ou o proxy do Elements também o aceitam, com a mesma regra do plano. O orçamento incorporado mostra o tema com que o orçamento saiu e só os seus blocos do Cord (Aparência).

Planos

As rotas desta página funcionam em todos os planos, exceto duas coisas que fazem parte do plano Profissional (e também do Scale e do Developer):

Personalizar os blocos do Cord: os textos, a aparência e a superfície deles, em props e estilo.superficie de um bloco do Cord. Criar ou editar um design que acrescenta uma personalização responde 402 subscription_required; o que já estava salvo é mantido. O personaliza_bloques_cord da validação avisa você antes de enviá-lo.
Escolher o design de um orçamento com diseno_id, que responde 402 subscription_required sem o plano. null é sempre aceito.

A resposta 402 traz plan (o atual) e plan_required. Sem o plano, o que foi salvo é mantido, mas não é aplicado: os seus orçamentos saem com o design padrão e os blocos do Cord aparecem como sempre.

Pela CLI

Desde a versão 2.3.0, a CLI do Cord baixa e envia os seus designs como arquivos JSON. Como a CLI só usa chaves de teste, cord disenos trabalha sobre o seu ambiente de teste, que nasce com uma cópia dos designs não arquivados da sua conta real. Reiniciá-lo os copia de novo com ids novos, então depois de um reinício rode pull outra vez; um ambiente de teste que já existia recebe a cópia na próxima vez que você o reinicia.

cord disenos pull --dir disenos
cord disenos validar disenos
cord disenos push disenos/proposta-de-obra.json

pull grava um arquivo por design em ./disenos, ou na pasta de --dir. Se já houver um arquivo com o mesmo id, ele o reescreve.
validar verifica um arquivo ou todos os .json de uma pasta, como POST /api/v1/disenos/validar, sem salvar nada.
push atualiza os designs cujo arquivo traz id, cria os demais e grava no arquivo o id novo. Envia nombre, descripcion e diseno; não muda qual é o design padrão.
push e validar listam cada problema com o caminho e o código, seguem para o próximo arquivo e terminam com código 1.
Com --json, cada comando imprime {"type":"disenos_pull",…}, {"type":"disenos_push",…} ou {"type":"disenos_validar",…} com o resultado de cada arquivo.

Cada arquivo traz id, nombre, descripcion, predeterminado e diseno. Aqui vai abreviado, porque ao baixá-lo o Cord completa props e estilo de cada bloco com os valores padrão:

{
  "id": "5b2e8c41-7d3a-4f19-9e6b-0c4a2d8f1b73",
  "nombre": "Proposta de obra",
  "descripcion": "Com capa e os blocos do Cord",
  "predeterminado": true,
  "diseno": {
    "esquema": 1,
    "temaOverrides": {},
    "paginas": [
      {
        "id": "principal",
        "bloques": [
          { "id": "portada", "tipo": "portada", "props": { "titulo": "Proposta para {cliente.empresa}" } },
          { "id": "encabezado", "tipo": "encabezado" },
          { "id": "metadatos", "tipo": "meta" },
          { "id": "totalcord", "tipo": "total" },
          { "id": "partidas", "tipo": "partidas" },
          { "id": "planpagos", "tipo": "plan_pagos" },
          { "id": "notascord", "tipo": "notas" },
          { "id": "legalcord", "tipo": "legal" },
          { "id": "aprobacion", "tipo": "aprobacion" },
          { "id": "conversacion", "tipo": "conversacion" },
          { "id": "contacto", "tipo": "contacto" },
          { "id": "piecord", "tipo": "pie" }
        ]
      }
    ]
  }
}

Levar um design para a sua conta real

A CLI não envia nada para a sua conta real. Para isso, mande o mesmo arquivo para POST /api/v1/disenos com uma chave secreta de produção, a partir do seu servidor ou da sua CI. O Cord ignora o id e o predeterminado do arquivo e responde com o design novo e o id dele na sua conta real:

curl -X POST "https://cordhq.app/api/v1/disenos" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: enviar-proposta-de-obra" \
     -d @disenos/proposta-de-obra.json

O seu ambiente de teste usa a biblioteca de mídia da sua conta real, somente leitura: um design que só usa imagens e vídeos da sua conta real é enviado a ela sem mudanças. As que você envia no ambiente de teste são só dele, e um design que as usa responde medio_desconocido na sua conta real: envie-as para a biblioteca da sua conta real e troque os ids, ou remova-as, antes de enviar o design. Para usá-lo nos seus orçamentos, marque-o depois com PATCH e predeterminado: true.

Pelos SDKs

Os SDKs de servidor têm o recurso designs, com os mesmos campos da API:

SDK	Métodos
Node (`@flouviahq/node`, desde a 1.4.0)	`cord.designs.list`, `create`, `retrieve`, `update`, `validate` e `del`
Python (`cord-sdk`, desde a 1.2.0)	`cord.designs.list`, `create`, `retrieve`, `update`, `validate` e `delete`, também no `AsyncCord`
PHP (`flouviahq/cord`, desde a 1.2.0)	`$cord->designs->list`, `create`, `retrieve`, `update`, `validate` e `delete`

validate recebe o documento e responde como POST /api/v1/disenos/validar: um design inválido chega como erro invalid_request com os seus issues. Veja SDK de Node.

Pelo MCP

O servidor MCP do Cord tem duas ferramentas de designs. Elas não criam nem editam designs: isso é feito no editor, na API ou na CLI.

Ferramenta	O que faz	Grupo e recurso
`listar_disenos`	Lista os seus designs em `items` (`id`, `nombre`, `descripcion` e `predeterminado`), e `elegir_por_cotizacion` diz se o seu plano deixa escolher um por orçamento.	Leitura, `disenos`
`aplicar_diseno`	Escolhe com qual design sai um orçamento em rascunho: recebe `cotizacion_id` e `diseno_id` (ou `null` para o padrão). Não envia nada ao cliente.	Escrita de rascunhos, `cotizaciones`

Permissões e erros

Uma chave restrita precisa do recurso disenos: Leitura para listar, consultar e validar, e Escrita para criar, editar e arquivar. Escolher o design de um orçamento pede escrita sobre cotizaciones. A chave do cord login já inclui disenos.

Código	Status	Quando
`insufficient_permissions`	403	A chave restrita não tem permissão sobre `disenos`.
`invalid_request`	400	Um campo não é válido, você enviou `diseno` e `plantilla` juntos ou o design não passa na validação.
`subscription_required`	402	O design personaliza os blocos do Cord, ou `diseno_id` escolhe um design, sem o plano Profissional.
`not_found`	404	O design não existe ou está arquivado, ou `diseno_id` não é um dos seus designs.
`disenos_tope`	409	A sua conta já tem 100 designs não arquivados.
`no_archivable`	409	Você tentou arquivar o design padrão.
`rate_limited`	429	A sua organização já fez 30 mudanças de designs no último minuto (ao criar ou arquivar) ou 120 (ao editar).