Designs

Die Designs von Cord Studio als Code: Legen Sie sie in Ihrem Repository ab, prüfen Sie sie vor dem Hochladen und wählen Sie, mit welchem Design jedes Angebot gesendet wird.

Überblick

Ein Design von Cord Studio bestimmt, wie Ihr Kunde den Angebotslink sieht: die Reihenfolge der Blöcke, ihren Inhalt, ihren Stil und was es am Theme Ihres Unternehmens ändert. Über die API ist es dasselbe JSON-Dokument, das der Tab Code des visuellen Editors zeigt, und Cord prüft es mit denselben Regeln: die Blöcke, die Ihr Kunde vor der Bestätigung braucht, den Kontrast von 4,5 zu 1 und die Medien aus der Mediathek Ihres Unternehmens.

Mit der API können Sie Ihre Designs in Ihrem Repository ablegen, in Ihrer CI prüfen und in Ihr Konto hochladen. Die vollständigen Operationen mit jedem Feld finden Sie in der API-Referenz.

Feld	Bedeutung
`object`	Immer `"diseno"`.
`id`	UUID des Designs.
`nombre`	1 bis 80 Zeichen.
`descripcion`	Interne Beschreibung, bis zu 280 Zeichen; `null` ohne Beschreibung. Ihr Kunde sieht sie nicht.
`predeterminado`	`true`, wenn es das Design ist, mit dem Angebote ohne eigene Wahl gesendet werden. Es gibt immer nur ein Standarddesign.
`actualizado`	Letzte Bearbeitung, ISO 8601.
`diseno`	Das Dokument: `esquema` (heute `1`), `temaOverrides` (was das Design am Theme Ihres Unternehmens ändert) und `paginas`, jede mit ihren `bloques` (`id`, `tipo`, `props` und `estilo`). Es ist nur in der Detailansicht und in den Antworten auf Anlegen und Bearbeiten enthalten.

Auflisten und abrufen

GET /api/v1/disenos liefert Ihre nicht archivierten Designs ohne ihr Dokument: zuerst das Standarddesign, dann vom zuletzt bearbeiteten bis zum ältesten. Die Liste ist nicht paginiert, weil ein Konto höchstens 100 hat.

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

{
  "data": [
    { "object": "diseno", "id": "5b2e8c41-7d3a-4f19-9e6b-0c4a2d8f1b73", "nombre": "Bauangebot", "descripcion": "Mit Titelseite, Zeitplan und Garantie", "predeterminado": true, "actualizado": "2026-11-10T16:42:08.000Z" },
    { "object": "diseno", "id": "c8d1f6a2-3e4b-4a7c-8f05-6b9e2d1c7a40", "nombre": "Monatliche Wartung", "descripcion": null, "predeterminado": false, "actualizado": "2026-11-08T19:05:31.000Z" }
  ]
}

GET /api/v1/disenos/{id} liefert ein Design mit seinem Dokument in diseno. Die ID eines Designs, das nicht existiert oder archiviert ist, ergibt 404 not_found.

Ein Design anlegen

POST /api/v1/disenos akzeptiert nombre, descripcion und eine dieser beiden Quellen, nie beide zusammen:

diseno: ein vollständiges Dokument, zum Beispiel eines, das Sie mit GET /api/v1/disenos/{id} heruntergeladen oder aus dem Tab Code kopiert haben.
plantilla: eine der achtzehn Vorlagen der Galerie: agencia, arquitectura, eventos, consultoria, software, fotografia, industrial, salud, educacion, inmobiliaria, minimal, editorial, noche, brutalista, tropical, gala, pop oder escenario. Ihre Texte kommen in der Sprache Ihres Kontos und mit den Gepflogenheiten des Landes Ihres Unternehmens, und ohne nombre übernimmt das Design den Namen der Vorlage. gala, pop und escenario passen die Cord-Blöcke an: Ohne den Professional-Tarif antworten sie mit 402 subscription_required.

Ohne beide beginnt das Design als Cord-Karte, das bisherige Design, und heißt "Diseño nuevo". Ein neues Design ist nicht das Standarddesign: Um es zu verwenden, legen Sie es fest, wie im nächsten Abschnitt beschrieben.

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

Die Antwort enthält das angelegte Design mit seinem Dokument. Mit einem diseno, das die Prüfung nicht besteht, lautet sie 400 invalid_request mit issues (siehe Ohne Speichern prüfen), und wenn Ihr Konto bereits 100 nicht archivierte Designs hat, 409 disenos_tope.

Bearbeiten und als Standard festlegen

PATCH /api/v1/disenos/{id} ändert, was Sie senden, und behält den Rest:

Feld	Wirkung
`nombre`, `descripcion`	Ersetzen die gespeicherten Werte; `descripcion: null` entfernt sie.
`diseno`	Ersetzt das ganze Dokument. Cord prüft es wie beim Anlegen.
`predeterminado`	`true` verwendet es für Angebote, die ab jetzt gesendet werden, und das bisherige ist nicht mehr Standard. `false` beim Standarddesign beendet seine Verwendung: Ihre Angebote werden wieder mit der Cord-Karte gesendet.

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: standard-bauangebot-2027" \
     -d '{ "predeterminado": true }'

Die Antwort enthält das geänderte Design. Ein Design zu bearbeiten oder das Standarddesign zu wechseln, ändert nichts an dem, was Ihre Kunden bereits erhalten haben: Jedes Angebot friert sein Design beim Senden ein.

Ohne Speichern prüfen

POST /api/v1/disenos/validar nimmt { "diseno": { … } } entgegen und prüft es wie der Editor, ohne etwas zu speichern. Verwenden Sie es in Ihrer CI, bevor Sie ein Design hochladen; ein Schlüssel mit Leseberechtigung für disenos genügt.

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

Lässt sich das Design speichern, lautet die Antwort 200 mit object: "diseno_validacion", valido: true, avisos (was das Speichern nicht verhindert, aber einen Blick wert ist, etwa eine Variable, die es nicht gibt, oder ein schwer lesbarer Text), diseno (das Dokument, wie Cord es speichern würde, mit den ergänzten Standardwerten) und personaliza_bloques_cord, das angibt, ob das Speichern in dieser Form den Professional-Tarif braucht.

Andernfalls lautet sie 400 invalid_request. issues enthält jedes Problem mit seinem Pfad in path (durch Punkte getrennt), was falsch ist, in message und einen festen Code in codigo, etwa esquema, falta_bloque, orden_aprobacion, contraste, superficie_no_solida oder medio_desconocido. field ist der Pfad des ersten:

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

Die Texte in message kommen auf Spanisch. Ein Design umfasst bis zu 60 Blöcke und 64 KB und verwendet nur Bilder und Videos aus der Mediathek Ihres Unternehmens, die Sie im Tab Medien des Editors hochladen; in der Testumgebung auch die Ihres echten Kontos. Anlegen und Bearbeiten liefern dieselbe 400-Antwort, wenn das Design die Prüfung nicht besteht.

Archivieren

DELETE /api/v1/disenos/{id} archiviert das Design und antwortet mit { "data": { "id": "…", "archivado": true } }. Es erscheint nicht mehr in der Liste und zählt nicht mehr zum Limit von 100. Bereits damit gesendete Angebote ändern sich nicht, und ein Entwurf, der es gewählt hatte, wird mit dem Standarddesign gesendet.

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

Das Standarddesign lässt sich nicht archivieren: Die Antwort lautet 409 no_archivable. Legen Sie ein anderes Design als Standard fest oder entfernen Sie die Markierung mit predeterminado: false, und versuchen Sie es erneut.

Das Design eines Angebots wählen

POST /api/v1/cotizaciones und PATCH /api/v1/cotizaciones/{id} akzeptieren diseno_id: die ID eines Ihrer Designs oder null, damit das Angebot mit dem Standarddesign gesendet wird. Es ändert nur einen Entwurf: Ein gesendetes Angebot behält das Design, mit dem es gesendet wurde. Mit einem öffentlichen Schlüssel ignoriert Cord 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-angebot-2a9d8e4f" \
     -d '{ "diseno_id": "c8d1f6a2-3e4b-4a7c-8f05-6b9e2d1c7a40" }'

Die Detailansicht des Angebots enthält diseno_id, das gewählte Design (null, wenn es mit dem Standarddesign gesendet wird), und diseno_propio, true, wenn jemand das Angebot im Editor einzeln gestaltet hat; dieses Design hat Vorrang vor diseno_id. Beim Senden nimmt Cord das eigene Design, das gewählte, das Standarddesign oder die Cord-Karte, in dieser Reihenfolge, und friert es ein. Mehr dazu in der Angebots-API und unter Ein einzelnes Angebot gestalten.

Auf Ihrer Seite legt <CordBuilder disenoId> von Cord Elements das Angebot mit einem Design an: Auch ein öffentlicher Schlüssel oder der Elements-Proxy akzeptieren es, mit derselben Tarifregel. Das eingebettete Angebot zeigt das Theme, mit dem das Angebot verschickt wurde, und nur seine Cord-Blöcke (Erscheinungsbild).

Tarife

Die Routen auf dieser Seite funktionieren in allen Tarifen, außer zwei Dingen, die zum Professional-Tarif gehören (und auch zu Scale und Developer):

Cord-Blöcke anpassen: ihre Texte, ihre Darstellung und ihre Fläche, in props und estilo.superficie eines Cord-Blocks. Ein Design anzulegen oder zu bearbeiten, das eine Anpassung hinzufügt, ergibt 402 subscription_required; was bereits gespeichert war, bleibt erhalten. personaliza_bloques_cord aus der Prüfung zeigt es Ihnen vor dem Hochladen.
Das Design eines Angebots wählen mit diseno_id, was ohne den Tarif 402 subscription_required ergibt. null wird immer akzeptiert.

Die 402-Antwort enthält plan (den aktuellen) und plan_required. Ohne den Tarif bleibt das Gespeicherte erhalten, wird aber nicht angewendet: Ihre Angebote werden mit dem Standarddesign gesendet, und die Cord-Blöcke sehen aus wie immer.

Über die CLI

Ab Version 2.3.0 lädt die Cord-CLI Ihre Designs als JSON-Dateien herunter und hoch. Da die CLI nur Testschlüssel verwendet, arbeitet cord disenos in Ihrer Testumgebung, die mit einer Kopie der nicht archivierten Designs Ihres echten Kontos entsteht. Beim Zurücksetzen werden sie erneut kopiert, mit neuen IDs: Führen Sie nach einem Zurücksetzen pull noch einmal aus. Eine Testumgebung, die es schon gab, erhält die Kopie beim nächsten Zurücksetzen.

cord disenos pull --dir disenos
cord disenos validar disenos
cord disenos push disenos/bauangebot.json

pull schreibt pro Design eine Datei nach ./disenos oder in den Ordner von --dir. Gibt es schon eine Datei mit derselben id, wird sie überschrieben.
validar prüft eine Datei oder alle .json eines Ordners wie POST /api/v1/disenos/validar, ohne etwas zu speichern.
push aktualisiert die Designs, deren Datei eine id enthält, legt die übrigen an und schreibt die neue id in die Datei. Gesendet werden nombre, descripcion und diseno; welches Design der Standard ist, ändert sich nicht.
push und validar listen jedes Problem mit Pfad und Code auf, machen mit der nächsten Datei weiter und enden mit dem Exit-Code 1.
Mit --json gibt jeder Befehl {"type":"disenos_pull",…}, {"type":"disenos_push",…} oder {"type":"disenos_validar",…} mit dem Ergebnis jeder Datei aus.

Jede Datei enthält id, nombre, descripcion, predeterminado und diseno. Hier gekürzt, denn beim Herunterladen ergänzt Cord props und estilo jedes Blocks mit ihren Standardwerten:

{
  "id": "5b2e8c41-7d3a-4f19-9e6b-0c4a2d8f1b73",
  "nombre": "Bauangebot",
  "descripcion": "Mit Titelseite und den Cord-Blöcken",
  "predeterminado": true,
  "diseno": {
    "esquema": 1,
    "temaOverrides": {},
    "paginas": [
      {
        "id": "principal",
        "bloques": [
          { "id": "portada", "tipo": "portada", "props": { "titulo": "Angebot für {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" }
        ]
      }
    ]
  }
}

Ein Design in Ihr echtes Konto übernehmen

Die CLI lädt nichts in Ihr echtes Konto hoch. Senden Sie dafür dieselbe Datei mit einem geheimen Live-Schlüssel an POST /api/v1/disenos, von Ihrem Server oder Ihrer CI aus. Cord ignoriert id und predeterminado der Datei und antwortet mit dem neuen Design und seiner id in Ihrem echten Konto:

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

Ihre Testumgebung nutzt die Mediathek Ihres echten Kontos, nur lesend: Ein Design, das nur Bilder und Videos Ihres echten Kontos verwendet, lässt sich unverändert dorthin hochladen. Was Sie in der Testumgebung hochladen, gehört nur ihr, und ein Design, das es verwendet, ergibt in Ihrem echten Konto medio_desconocido: Laden Sie diese Medien in die Mediathek Ihres echten Kontos hoch und ersetzen Sie ihre IDs, oder entfernen Sie sie, bevor Sie das Design hochladen. Um es für Ihre Angebote zu verwenden, legen Sie es danach mit PATCH und predeterminado: true als Standard fest.

Über die SDKs

Die Server-SDKs haben die Ressource designs mit denselben Feldern wie die API:

SDK	Methoden
Node (`@flouviahq/node`, ab 1.4.0)	`cord.designs.list`, `create`, `retrieve`, `update`, `validate` und `del`
Python (`cord-sdk`, ab 1.2.0)	`cord.designs.list`, `create`, `retrieve`, `update`, `validate` und `delete`, auch in `AsyncCord`
PHP (`flouviahq/cord`, ab 1.2.0)	`$cord->designs->list`, `create`, `retrieve`, `update`, `validate` und `delete`

validate nimmt das Dokument entgegen und antwortet wie POST /api/v1/disenos/validar: Ein ungültiges Design kommt als Fehler invalid_request mit seinen issues zurück. Siehe Node-SDK.

Über MCP

Der MCP-Server von Cord hat zwei Tools für Designs. Sie legen keine Designs an und bearbeiten keine: Das geschieht im Editor, über die API oder die CLI.

Tool	Funktion	Gruppe und Ressource
`listar_disenos`	Listet Ihre Designs in `items` (`id`, `nombre`, `descripcion` und `predeterminado`), und `elegir_por_cotizacion` gibt an, ob Ihr Tarif ein Design pro Angebot erlaubt.	Lesen, `disenos`
`aplicar_diseno`	Wählt, mit welchem Design ein Angebot im Entwurf gesendet wird: nimmt `cotizacion_id` und `diseno_id` entgegen (oder `null` für das Standarddesign). Sendet nichts an den Kunden.	Entwürfe schreiben, `cotizaciones`

Berechtigungen und Fehler

Ein eingeschränkter Schlüssel braucht die Ressource disenos: Lesen zum Auflisten, Abrufen und Prüfen und Schreiben zum Anlegen, Bearbeiten und Archivieren. Das Design eines Angebots zu wählen, braucht Schreibberechtigung für cotizaciones. Der Schlüssel von cord login enthält disenos bereits.

Code	Status	Wann
`insufficient_permissions`	403	Der eingeschränkte Schlüssel hat keine Berechtigung für `disenos`.
`invalid_request`	400	Ein Feld ist ungültig, Sie haben `diseno` und `plantilla` zusammen gesendet, oder das Design besteht die Prüfung nicht.
`subscription_required`	402	Das Design passt Cord-Blöcke an, oder `diseno_id` wählt ein Design, ohne den Professional-Tarif.
`not_found`	404	Das Design existiert nicht oder ist archiviert, oder `diseno_id` ist keines Ihrer Designs.
`disenos_tope`	409	Ihr Konto hat bereits 100 nicht archivierte Designs.
`no_archivable`	409	Sie haben versucht, das Standarddesign zu archivieren.
`rate_limited`	429	Ihre Organisation hat in der letzten Minute bereits 30 Designänderungen vorgenommen (beim Anlegen oder Archivieren) oder 120 (beim Bearbeiten).