Diseños

Los diseños de Cord Studio como código: guárdalos en tu repositorio, revísalos antes de subirlos y elige con cuál sale cada cotización.

Descripción general

Un diseño de Cord Studio decide cómo ve tu cliente el link de la cotización: el orden de los bloques, su contenido, su estilo y lo que cambia del tema de tu negocio. Por la API es el mismo documento JSON que muestra la pestaña Código del editor visual, y Cord lo valida con las mismas reglas: los bloques que tu cliente necesita antes de aprobar, el contraste de 4.5 a 1 y los medios de la biblioteca de tu negocio.

Con la API puedes guardar tus diseños en tu repositorio, revisarlos en tu CI y subirlos a tu cuenta. Las operaciones completas, con cada campo, están en la Referencia de la API.

Campo	Qué es
`object`	Siempre `"diseno"`.
`id`	UUID del diseño.
`nombre`	De 1 a 80 caracteres.
`descripcion`	Descripción interna, hasta 280 caracteres; `null` sin descripción. Tu cliente no la ve.
`predeterminado`	`true` si es el diseño con que salen las cotizaciones que no eligen otro. Solo uno lo es a la vez.
`actualizado`	Última edición, ISO 8601.
`diseno`	El documento: `esquema` (hoy `1`), `temaOverrides` (lo que el diseño cambia del tema de tu negocio) y `paginas`, cada una con sus `bloques` (`id`, `tipo`, `props` y `estilo`). Solo viene en el detalle y en las respuestas de crear y editar.

Listar y leer

GET /api/v1/disenos devuelve tus diseños sin archivar, sin su documento: primero el predeterminado y después del editado más reciente al más antiguo. No se pagina, porque una cuenta tiene hasta 100.

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

{
  "data": [
    { "object": "diseno", "id": "5b2e8c41-7d3a-4f19-9e6b-0c4a2d8f1b73", "nombre": "Propuesta de obra", "descripcion": "Con portada, cronograma y garantía", "predeterminado": true, "actualizado": "2026-11-10T16:42:08.000Z" },
    { "object": "diseno", "id": "c8d1f6a2-3e4b-4a7c-8f05-6b9e2d1c7a40", "nombre": "Mantenimiento mensual", "descripcion": null, "predeterminado": false, "actualizado": "2026-11-08T19:05:31.000Z" }
  ]
}

GET /api/v1/disenos/{id} devuelve un diseño con su documento en diseno. El id de un diseño que no existe o que está archivado responde 404 not_found.

Crear un diseño

POST /api/v1/disenos acepta nombre, descripcion y una de estas dos fuentes, nunca las dos juntas:

diseno: un documento completo, por ejemplo uno que bajaste con GET /api/v1/disenos/{id} o que copiaste de la pestaña Código.
plantilla: una de las dieciocho plantillas de la galería: agencia, arquitectura, eventos, consultoria, software, fotografia, industrial, salud, educacion, inmobiliaria, minimal, editorial, noche, brutalista, tropical, gala, pop o escenario. Sus textos salen en el idioma de tu cuenta y con los usos del país de tu negocio, y sin nombre el diseño toma el de la plantilla. gala, pop y escenario personalizan los bloques de Cord: sin el plan Profesional responden 402 subscription_required.

Sin ninguna de las dos, el diseño nace como la Tarjeta de Cord, el diseño de siempre, y se llama "Diseño nuevo". Un diseño nuevo no es el predeterminado: para usarlo, márcalo como se explica en la sección siguiente.

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

Responde el diseño creado, con su documento. Con un diseno que no pasa la validación responde 400 invalid_request con issues (ver Validar sin guardar), y si tu cuenta ya tiene 100 diseños sin archivar, 409 disenos_tope.

Editar y marcar el predeterminado

PATCH /api/v1/disenos/{id} cambia lo que mandas y conserva lo demás:

Campo	Efecto
`nombre`, `descripcion`	Reemplazan a los guardados; `descripcion: null` la quita.
`diseno`	Reemplaza el documento completo. Cord lo valida igual que al crearlo.
`predeterminado`	`true` lo usa en las cotizaciones que se envíen desde ahora, y el anterior deja de serlo. `false` en el predeterminado lo deja de usar: tus cotizaciones vuelven a salir con la Tarjeta de 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: predeterminado-obra-2027" \
     -d '{ "predeterminado": true }'

Responde el diseño actualizado. Editar un diseño o cambiar el predeterminado no toca lo que tus clientes ya recibieron: cada cotización congela su diseño al enviarse.

Validar sin guardar

POST /api/v1/disenos/validar recibe { "diseno": { … } } y lo revisa como el editor, sin guardar nada. Úsalo en tu CI antes de subir un diseño; basta una llave con lectura 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/propuesta-de-obra.json

Si el diseño se puede guardar, responde 200 con object: "diseno_validacion", valido: true, avisos (lo que no impide guardarlo pero conviene revisar, como una variable que no existe o un texto que se lee con dificultad), diseno (el documento como lo guardaría Cord, con los valores por defecto que completa) y personaliza_bloques_cord, que dice si guardarlo así necesita el plan Profesional.

Si no, responde 400 invalid_request. issues trae cada problema con su ruta en path (separada por puntos), qué está mal en message y un código estable en codigo, como esquema, falta_bloque, orden_aprobacion, contraste, superficie_no_solida o medio_desconocido. field es la ruta del primero:

{
  "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" }
  ]
}

Los mensajes de message llegan en español. Un diseño admite hasta 60 bloques y 64 KB, y solo usa imágenes y videos de la biblioteca de tu negocio, que se suben en la pestaña Medios del editor; en el entorno de prueba, también los de tu cuenta real. Crear y editar devuelven la misma respuesta 400 cuando el diseño no pasa.

Archivar

DELETE /api/v1/disenos/{id} archiva el diseño y responde { "data": { "id": "…", "archivado": true } }. Deja de aparecer en la lista y de contar en el tope de 100. Las cotizaciones que ya se enviaron con él no cambian, y un borrador que lo tenía elegido sale con el predeterminado.

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

El predeterminado no se archiva: responde 409 no_archivable. Marca otro como predeterminado, o quítale la marca con predeterminado: false, y vuelve a intentarlo.

Elegir el diseño de una cotización

POST /api/v1/cotizaciones y PATCH /api/v1/cotizaciones/{id} aceptan diseno_id: el id de uno de tus diseños, o null para que la cotización salga con el predeterminado. Solo cambia un borrador: una cotización enviada conserva el diseño con que salió. Con una llave publicable, 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: diseno-cotizacion-2a9d8e4f" \
     -d '{ "diseno_id": "c8d1f6a2-3e4b-4a7c-8f05-6b9e2d1c7a40" }'

El detalle de la cotización trae diseno_id, el diseño elegido (null si sale con el predeterminado), y diseno_propio, true si alguien la diseñó sola en el editor; ese diseño manda sobre diseno_id. Al enviarla, Cord toma su diseño propio, el elegido, el predeterminado o la Tarjeta de Cord, en ese orden, y lo congela. Más en API de Cotizaciones y en Diseña una sola cotización.

Desde tu página, <CordBuilder disenoId> de Cord Elements crea la cotización con un diseño: lo acepta también una llave publicable o el proxy de Elements, con la misma regla del plan. El cotizador embebido pinta el tema con que salió la cotización y solo sus bloques de Cord (Apariencia).

Planes

Las rutas de esta página funcionan en todos los planes, salvo dos cosas que son del plan Profesional (también de Scale y Developer):

Personalizar los bloques de Cord: sus textos, cómo se ven y su superficie, en props y estilo.superficie de un bloque de Cord. Crear o editar un diseño que agrega una personalización responde 402 subscription_required; lo que ya estaba guardado se conserva. personaliza_bloques_cord de la validación te lo dice antes de subirlo.
Elegir el diseño de una cotización con diseno_id, que responde 402 subscription_required sin el plan. null siempre se acepta.

La respuesta 402 trae plan (el actual) y plan_required. Sin el plan, lo guardado se conserva pero no se aplica: tus cotizaciones salen con el diseño predeterminado y los bloques de Cord se ven como siempre.

Desde el CLI

Desde la versión 2.3.0, el CLI de Cord baja y sube tus diseños como archivos JSON. Como el CLI solo usa llaves de prueba, cord disenos trabaja sobre tu entorno de prueba, que nace con una copia de los diseños sin archivar de tu cuenta real. Reiniciarlo los vuelve a copiar con ids nuevos, así que después de un reinicio corre pull otra vez; un entorno de prueba que ya existía recibe la copia la próxima vez que lo reinicias.

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

pull deja un archivo por diseño en ./disenos, o en la carpeta de --dir. Si ya hay un archivo con el mismo id, lo reescribe.
validar revisa un archivo o todos los .json de una carpeta, como POST /api/v1/disenos/validar, sin guardar nada.
push actualiza los diseños cuyo archivo trae id y crea los demás, y escribe en el archivo el id nuevo. Manda nombre, descripcion y diseno; no cambia cuál es el predeterminado.
push y validar listan cada problema con su ruta y su código, siguen con el archivo siguiente y terminan con código 1.
Con --json, cada comando imprime {"type":"disenos_pull",…}, {"type":"disenos_push",…} o {"type":"disenos_validar",…} con el resultado de cada archivo.

Cada archivo lleva id, nombre, descripcion, predeterminado y diseno. Abreviado, porque al bajarlo Cord completa props y estilo de cada bloque con sus valores por defecto:

{
  "id": "5b2e8c41-7d3a-4f19-9e6b-0c4a2d8f1b73",
  "nombre": "Propuesta de obra",
  "descripcion": "Con portada y los bloques de Cord",
  "predeterminado": true,
  "diseno": {
    "esquema": 1,
    "temaOverrides": {},
    "paginas": [
      {
        "id": "principal",
        "bloques": [
          { "id": "portada", "tipo": "portada", "props": { "titulo": "Propuesta 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" }
        ]
      }
    ]
  }
}

Llevar un diseño a tu cuenta real

El CLI no sube nada a tu cuenta real. Para eso, manda el mismo archivo a POST /api/v1/disenos con una llave secreta en vivo, desde tu servidor o tu CI. Cord ignora id y predeterminado del archivo y responde el diseño nuevo con su id en tu cuenta real:

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

Tu entorno de prueba usa la biblioteca de medios de tu cuenta real, de solo lectura: un diseño que solo usa imágenes y videos de tu cuenta real sube a ella sin cambios. Los que subes en el entorno de prueba son solo suyos, y un diseño que los usa responde medio_desconocido en tu cuenta real: súbelos a la biblioteca de tu cuenta real y cambia sus ids, o quítalos, antes de subir el diseño. Para usarlo en tus cotizaciones, márcalo después con PATCH y predeterminado: true.

Desde los SDK

Los SDK de servidor tienen el recurso designs, con los mismos campos que la API:

SDK	Métodos
Node (`@flouviahq/node`, desde la 1.4.0)	`cord.designs.list`, `create`, `retrieve`, `update`, `validate` y `del`
Python (`cord-sdk`, desde la 1.2.0)	`cord.designs.list`, `create`, `retrieve`, `update`, `validate` y `delete`, también en `AsyncCord`
PHP (`flouviahq/cord`, desde la 1.2.0)	`$cord->designs->list`, `create`, `retrieve`, `update`, `validate` y `delete`

validate recibe el documento y responde como POST /api/v1/disenos/validar: un diseño inválido llega como error invalid_request con sus issues. Ver SDK de Node.

Desde el MCP

El servidor MCP de Cord tiene dos herramientas de diseños. No crean ni editan diseños: eso se hace en el editor, la API o el CLI.

Herramienta	Qué hace	Grupo y recurso
`listar_disenos`	Lista tus diseños en `items` (`id`, `nombre`, `descripcion` y `predeterminado`), y `elegir_por_cotizacion` dice si tu plan deja elegir uno por cotización.	Lectura, `disenos`
`aplicar_diseno`	Elige con qué diseño sale una cotización en borrador: recibe `cotizacion_id` y `diseno_id` (o `null` para el predeterminado). No envía nada al cliente.	Escritura de borradores, `cotizaciones`

Permisos y errores

Una llave restringida necesita el recurso disenos: Lectura para listar, leer y validar, y Escritura para crear, editar y archivar. Elegir el diseño de una cotización pide escritura sobre cotizaciones. La llave de cord login ya incluye disenos.

Código	Status	Cuándo
`insufficient_permissions`	403	La llave restringida no tiene permiso sobre `disenos`.
`invalid_request`	400	Un campo no es válido, mandaste `diseno` y `plantilla` juntos o el diseño no pasa la validación.
`subscription_required`	402	El diseño personaliza los bloques de Cord, o `diseno_id` elige un diseño, sin el plan Profesional.
`not_found`	404	El diseño no existe o está archivado, o `diseno_id` no es uno de tus diseños.
`disenos_tope`	409	Tu cuenta ya tiene 100 diseños sin archivar.
`no_archivable`	409	Intentaste archivar el diseño predeterminado.
`rate_limited`	429	Tu organización ya hizo 30 cambios de diseños en el último minuto (al crear o archivar) o 120 (al editar).