Designs

Les designs Cord Studio sous forme de code : gardez-les dans votre dépôt, vérifiez-les avant de les envoyer et choisissez celui avec lequel part chaque devis.

Vue d’ensemble

Un design Cord Studio détermine comment votre client voit le lien du devis : l’ordre des blocs, leur contenu, leur style et ce qu’il change du thème de votre entreprise. Par l’API, c’est le même document JSON que l’onglet Code de l’éditeur visuel, et Cord le valide avec les mêmes règles : les blocs dont votre client a besoin avant d’approuver, le contraste de 4,5 pour 1 et les médias de la médiathèque de votre entreprise.

Avec l’API, vous pouvez garder vos designs dans votre dépôt, les vérifier dans votre CI et les envoyer sur votre compte. Les opérations complètes, avec chaque champ, sont dans la Référence de l’API.

Champ	Description
`object`	Toujours `"diseno"`.
`id`	UUID du design.
`nombre`	De 1 à 80 caractères.
`descripcion`	Description interne, jusqu’à 280 caractères ; `null` sans description. Votre client ne la voit pas.
`predeterminado`	`true` si c’est le design avec lequel partent les devis qui n’en choisissent pas d’autre. Un seul est le design par défaut à la fois.
`actualizado`	Dernière modification, ISO 8601.
`diseno`	Le document : `esquema` (`1` aujourd’hui), `temaOverrides` (ce que le design change du thème de votre entreprise) et `paginas`, chacune avec ses `bloques` (`id`, `tipo`, `props` et `estilo`). Il ne figure que dans le détail et dans les réponses de création et de modification.

Lister et consulter

GET /api/v1/disenos renvoie vos designs non archivés, sans leur document : d’abord le design par défaut, puis du plus récemment modifié au plus ancien. La liste n’est pas paginée, car un compte en a au plus 100.

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

{
  "data": [
    { "object": "diseno", "id": "5b2e8c41-7d3a-4f19-9e6b-0c4a2d8f1b73", "nombre": "Proposition de chantier", "descripcion": "Avec couverture, calendrier et garantie", "predeterminado": true, "actualizado": "2026-11-10T16:42:08.000Z" },
    { "object": "diseno", "id": "c8d1f6a2-3e4b-4a7c-8f05-6b9e2d1c7a40", "nombre": "Maintenance mensuelle", "descripcion": null, "predeterminado": false, "actualizado": "2026-11-08T19:05:31.000Z" }
  ]
}

GET /api/v1/disenos/{id} renvoie un design avec son document dans diseno. L’id d’un design qui n’existe pas ou qui est archivé répond 404 not_found.

Créer un design

POST /api/v1/disenos accepte nombre, descripcion et l’une de ces deux sources, jamais les deux :

diseno : un document complet, par exemple un document téléchargé avec GET /api/v1/disenos/{id} ou copié depuis l’onglet Code.
plantilla : l’un des dix-huit modèles de la galerie : agencia, arquitectura, eventos, consultoria, software, fotografia, industrial, salud, educacion, inmobiliaria, minimal, editorial, noche, brutalista, tropical, gala, pop ou escenario. Ses textes sortent dans la langue de votre compte et avec les usages du pays de votre entreprise, et sans nombre le design prend le nom du modèle. gala, pop et escenario personnalisent les blocs Cord : sans l’offre Professionnel, ils répondent 402 subscription_required.

Sans aucune des deux, le design démarre comme la Carte Cord, le design habituel, et s’appelle "Diseño nuevo". Un nouveau design n’est pas le design par défaut : pour l’utiliser, définissez-le comme expliqué dans la section suivante.

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

La réponse contient le design créé, avec son document. Avec un diseno qui ne passe pas la validation, elle répond 400 invalid_request avec issues (voir Valider sans enregistrer), et si votre compte a déjà 100 designs non archivés, 409 disenos_tope.

Modifier et définir le design par défaut

PATCH /api/v1/disenos/{id} change ce que vous envoyez et conserve le reste :

Champ	Effet
`nombre`, `descripcion`	Remplacent ceux enregistrés ; `descripcion: null` la retire.
`diseno`	Remplace tout le document. Cord le valide comme à la création.
`predeterminado`	`true` l’utilise pour les devis envoyés à partir de maintenant, et le précédent cesse d’être le design par défaut. `false` sur le design par défaut cesse de l’utiliser : vos devis repartent avec la Carte 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: par-defaut-chantier-2027" \
     -d '{ "predeterminado": true }'

La réponse contient le design modifié. Modifier un design ou changer le design par défaut ne touche pas ce que vos clients ont déjà reçu : chaque devis fige son design à l’envoi.

Valider sans enregistrer

POST /api/v1/disenos/validar reçoit { "diseno": { … } } et le vérifie comme l’éditeur, sans rien enregistrer. Utilisez-le dans votre CI avant d’envoyer un design ; une clé avec la lecture sur disenos suffit.

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

Si le design peut être enregistré, la réponse est 200 avec object: "diseno_validacion", valido: true, avisos (ce qui n’empêche pas d’enregistrer mais mérite une relecture, comme une variable qui n’existe pas ou un texte difficile à lire), diseno (le document tel que Cord l’enregistrerait, avec les valeurs par défaut qu’il complète) et personaliza_bloques_cord, qui indique si l’enregistrer ainsi nécessite l’offre Professionnel.

Sinon, la réponse est 400 invalid_request. issues donne chaque problème avec son chemin dans path (séparé par des points), ce qui ne va pas dans message et un code stable dans codigo, comme esquema, falta_bloque, orden_aprobacion, contraste, superficie_no_solida ou medio_desconocido. field est le chemin du premier :

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

Les textes de message arrivent en espagnol. Un design accepte jusqu’à 60 blocs et 64 Ko, et n’utilise que des images et des vidéos de la médiathèque de votre entreprise, que vous envoyez dans l’onglet Médias de l’éditeur ; dans l’environnement de test, aussi celles de votre compte réel. La création et la modification renvoient la même réponse 400 quand le design ne passe pas.

Archiver

DELETE /api/v1/disenos/{id} archive le design et répond { "data": { "id": "…", "archivado": true } }. Il n’apparaît plus dans la liste et ne compte plus dans la limite de 100. Les devis déjà envoyés avec lui ne changent pas, et un brouillon qui l’avait choisi part avec le design par défaut.

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

Le design par défaut ne s’archive pas : la réponse est 409 no_archivable. Définissez un autre design par défaut, ou retirez-lui ce statut avec predeterminado: false, puis réessayez.

Choisir le design de chaque devis

POST /api/v1/cotizaciones et PATCH /api/v1/cotizaciones/{id} acceptent diseno_id : l’id de l’un de vos designs, ou null pour que le devis parte avec le design par défaut. Seul un brouillon change : un devis envoyé garde le design avec lequel il est parti. Avec une clé publiable, Cord ignore 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-devis-2a9d8e4f" \
     -d '{ "diseno_id": "c8d1f6a2-3e4b-4a7c-8f05-6b9e2d1c7a40" }'

Le détail du devis contient diseno_id, le design choisi (null s’il part avec le design par défaut), et diseno_propio, true si quelqu’un a conçu ce devis à part dans l’éditeur ; ce design l’emporte sur diseno_id. À l’envoi, Cord prend son propre design, celui choisi, le design par défaut ou la Carte Cord, dans cet ordre, et le fige. Plus de détails dans API des devis et dans Concevez un seul devis.

Depuis votre page, <CordBuilder disenoId> de Cord Elements crée le devis avec un design : une clé publiable ou le proxy d’Elements l’acceptent aussi, avec la même règle de forfait. Le devis intégré affiche le thème avec lequel le devis est parti et seulement ses blocs Cord (Apparence).

Offres

Les routes de cette page fonctionnent avec toutes les offres, sauf deux choses qui font partie de l’offre Professionnel (et aussi de Scale et Developer) :

Personnaliser les blocs Cord : leurs textes, leur affichage et leur surface, dans props et estilo.superficie d’un bloc Cord. Créer ou modifier un design qui ajoute une personnalisation répond 402 subscription_required ; ce qui était déjà enregistré est conservé. Le champ personaliza_bloques_cord de la validation vous le signale avant l’envoi.
Choisir le design d’un devis avec diseno_id, qui répond 402 subscription_required sans cette offre. null est toujours accepté.

La réponse 402 contient plan (l’offre actuelle) et plan_required. Sans l’offre, ce qui est enregistré est conservé mais ne s’applique pas : vos devis partent avec le design par défaut et les blocs Cord s’affichent comme d’habitude.

Depuis la CLI

Depuis la version 2.3.0, la CLI de Cord télécharge et envoie vos designs en fichiers JSON. Comme la CLI n’utilise que des clés de test, cord disenos travaille sur votre environnement de test, qui est créé avec une copie des designs non archivés de votre compte réel. Le réinitialiser les copie de nouveau avec de nouveaux id : après une réinitialisation, relancez pull ; un environnement de test qui existait déjà reçoit la copie à sa prochaine réinitialisation.

cord disenos pull --dir disenos
cord disenos validar disenos
cord disenos push disenos/proposition-de-chantier.json

pull écrit un fichier par design dans ./disenos, ou dans le dossier de --dir. Si un fichier avec le même id existe déjà, elle le réécrit.
validar vérifie un fichier ou tous les .json d’un dossier, comme POST /api/v1/disenos/validar, sans rien enregistrer.
push met à jour les designs dont le fichier contient un id, crée les autres et écrit le nouvel id dans le fichier. Elle envoie nombre, descripcion et diseno ; elle ne change pas le design par défaut.
push et validar listent chaque problème avec son chemin et son code, passent au fichier suivant et se terminent avec le code 1.
Avec --json, chaque commande affiche {"type":"disenos_pull",…}, {"type":"disenos_push",…} ou {"type":"disenos_validar",…} avec le résultat de chaque fichier.

Chaque fichier contient id, nombre, descripcion, predeterminado et diseno. Il est abrégé ici, car au téléchargement Cord complète props et estilo de chaque bloc avec leurs valeurs par défaut :

{
  "id": "5b2e8c41-7d3a-4f19-9e6b-0c4a2d8f1b73",
  "nombre": "Proposition de chantier",
  "descripcion": "Avec couverture et les blocs Cord",
  "predeterminado": true,
  "diseno": {
    "esquema": 1,
    "temaOverrides": {},
    "paginas": [
      {
        "id": "principal",
        "bloques": [
          { "id": "portada", "tipo": "portada", "props": { "titulo": "Proposition pour {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" }
        ]
      }
    ]
  }
}

Passer un design sur votre compte réel

La CLI n’envoie rien sur votre compte réel. Pour cela, envoyez le même fichier à POST /api/v1/disenos avec une clé secrète live, depuis votre serveur ou votre CI. Cord ignore l’id et le predeterminado du fichier et répond avec le nouveau design et son id sur votre compte réel :

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

Votre environnement de test utilise la médiathèque de votre compte réel, en lecture seule : un design qui n’utilise que des images et des vidéos de votre compte réel s’y envoie sans changement. Celles que vous importez dans l’environnement de test n’appartiennent qu’à lui, et un design qui les utilise répond medio_desconocido sur votre compte réel : envoyez-les dans la médiathèque de votre compte réel et changez leurs id, ou retirez-les, avant d’envoyer le design. Pour l’utiliser sur vos devis, définissez-le ensuite avec PATCH et predeterminado: true.

Depuis les SDK

Les SDK serveur ont la ressource designs, avec les mêmes champs que l’API :

SDK	Méthodes
Node (`@flouviahq/node`, depuis la 1.4.0)	`cord.designs.list`, `create`, `retrieve`, `update`, `validate` et `del`
Python (`cord-sdk`, depuis la 1.2.0)	`cord.designs.list`, `create`, `retrieve`, `update`, `validate` et `delete`, aussi dans `AsyncCord`
PHP (`flouviahq/cord`, depuis la 1.2.0)	`$cord->designs->list`, `create`, `retrieve`, `update`, `validate` et `delete`

validate reçoit le document et répond comme POST /api/v1/disenos/validar : un design non valide arrive comme une erreur invalid_request avec ses issues. Voir SDK Node.

Depuis le MCP

Le serveur MCP de Cord a deux outils pour les designs. Ils ne créent ni ne modifient de designs : cela se fait dans l’éditeur, l’API ou la CLI.

Outil	Ce qu’il fait	Groupe et ressource
`listar_disenos`	Liste vos designs dans `items` (`id`, `nombre`, `descripcion` et `predeterminado`), et `elegir_por_cotizacion` indique si votre offre permet d’en choisir un par devis.	Lecture, `disenos`
`aplicar_diseno`	Choisit avec quel design part un devis en brouillon : reçoit `cotizacion_id` et `diseno_id` (ou `null` pour le design par défaut). N’envoie rien au client.	Écriture de brouillons, `cotizaciones`

Droits et erreurs

Une clé restreinte a besoin de la ressource disenos : Lecture pour lister, consulter et valider, et Écriture pour créer, modifier et archiver. Choisir le design d’un devis demande l’écriture sur cotizaciones. La clé de cord login inclut déjà disenos.

Code	Statut	Quand
`insufficient_permissions`	403	La clé restreinte n’a pas de droit sur `disenos`.
`invalid_request`	400	Un champ n’est pas valide, vous avez envoyé `diseno` et `plantilla` ensemble, ou le design ne passe pas la validation.
`subscription_required`	402	Le design personnalise les blocs Cord, ou `diseno_id` choisit un design, sans l’offre Professionnel.
`not_found`	404	Le design n’existe pas ou est archivé, ou `diseno_id` n’est pas l’un de vos designs.
`disenos_tope`	409	Votre compte a déjà 100 designs non archivés.
`no_archivable`	409	Vous avez tenté d’archiver le design par défaut.
`rate_limited`	429	Votre organisation a déjà fait 30 changements de designs dans la dernière minute (à la création ou à l’archivage) ou 120 (à la modification).