bimetricsEntwickler
Layouts

Layout ändern

Als Markdown ansehen

Benötigte Berechtigung:layout:write(Layouts und Logo ändern)

Echte Wirkung

Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
patch/api/layouts/{id}

Kein Testversand aus der Dokumentation: Dieser Aufruf ist nicht als rein lesend gekennzeichnet. Nutze das Codebeispiel.

Ändert ein Layout wie der Editor: Alle Operationen zusammen ergeben eine neue Version. Sie gilt sofort für neue Belege und offene Entwürfe, ausgestellte Belege behalten ihre. Werte nur aus dem Katalog. Operationen: set (Eigenschaft path auf value, null setzt den Standard), preset und recipe (id aus dem Katalog), brandColor (Hausfarbe #RRGGBB oder null), addBlock (kind, slot, position), moveBlock (id, slot, position), removeBlock (id), setBlockValue (id, path, value), setNote (id, text), dazu jeweils allein rename (name, ohne neue Version) und restore (version). baseVersionId ist optional und empfohlen: Hat sich das Layout seit dem Lesen geändert, antwortet die Route mit 409 LayoutVersionConflict. Ändern die Operationen nichts, entsteht keine Version. Höchstens 200 neue Versionen je Firma und Stunde, über App, API und MCP zusammen (429 LayoutVersionLimit). Idempotency-Key bei Wiederholung unverändert senden.

Benötigt einen Schlüssel mit der Berechtigung layout:write.

Authentifizierung

headerAuthentifizierungBearer <bm_…>

Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.

Pfadparameter

id*string

ID des Layouts (UUID) oder standard, das Layout aller Belegarten ohne eigenes.

Header-Parameter

Idempotency-Key*string

Stabiler Schlüssel für genau diese Änderung: 1–128 druckbare ASCII-Zeichen ohne Leerzeichen. Bei Wiederholungen denselben Schlüssel und unveränderten Inhalt senden; das Ergebnis wird nicht nochmals erzeugt.

Muster^[!-~]+$
Länge1 <= length <= 128

Request-Body

operations (1 bis 20) und optional baseVersionId, die ID der zuletzt gelesenen Version.

application/json
  1. body

Antworten

Erfolg.

application/json
  1. response

Ein Rechnungslayout.

appliesTo?array<string>|

Belegarten, für die das Layout gilt; * für alle ohne eigenes. Leer, wenn es für keine gilt.

archivedAt?|

Archiviert seit; null, solange nicht archiviert.

Formatdate-time
editable?boolean

False für das bisherige Layout classic: Es lässt sich nicht ändern.

id?string

ID des Layouts (UUID); standard für das Layout einer Firma ohne eigenes.

module?string

Modul mit Version, etwa modern@2. classic@1 ist das bisherige Layout ohne Einstellungen.

name?string

Name, etwa „Angebote“.

own?boolean

False, solange die Firma kein eigenes Layout hat; die erste Änderung legt es an.

spec?

Die Gestaltung.

version?|

Aktuelle Version; null ohne eigenes Layout.

Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/layouts/string" \  -H "Authorization: Bearer $BIMETRICS_API_KEY" \  -H "Idempotency-Key: rechnung-2026-001" \  -H "Content-Type: application/json" \  -d '{"baseVersionId":"b1a72031-ace3-4bdc-a63d-477d6be5d7cb","operations":[{"op":"set","path":"header.logo.size","value":"L"},{"op":"brandColor","value":"#1F5F5B"}]}'
Beispielantwort
{  "appliesTo": [    "*"  ],  "archivedAt": null,  "editable": true,  "id": "243ee0cc-b1c7-4335-8817-6bc939f0f615",  "module": "modern@2",  "name": "Hansen & Kowalski Werbetechnik GmbH",  "own": true,  "spec": {    "blocks": {},    "brandColor": "#1F5F5B",    "module": "modern",    "preset": "modern",    "recipe": "",    "schema": 2,    "values": {      "footer.pageNumber": "auto",      "footer.titles": false,      "header.logo.size": "L",      "page.margin.left": 25    }  },  "version": {    "actor": {      "membershipId": "53cd10a9-c864-4dc3-a777-9860d59efe6c",      "name": "Jana Hansen"    },    "check": "passed",    "createdAt": "2026-11-04T10:15:00Z",    "id": "16f6234e-8667-42f0-9584-6a397dc5f36a",    "number": 2,    "origin": "api",    "originRef": null,    "parentId": "b1a72031-ace3-4bdc-a63d-477d6be5d7cb",    "summary": "Logo größer (L), Hausfarbe #1F5F5B"  }}

Layout lesen GET

Liefert ein Layout mit Gestaltung und aktueller Version. Eine ID einer anderen Firma ergibt `404 LayoutNotFound`, ohne Daten. Benötigt einen Schlüssel mit der Berechtigung `sales:read` oder `read`.

Layout archivieren POST

Archiviert ein Layout, für das keine Belegart gilt, sonst `409 LayoutAssigned`. Layouts werden nie gelöscht, ausgestellte Belege behalten ihre Version. Benötigt einen Schlüssel mit der Berechtigung `layout:write`.