bimetricsEntwickler
Layouts

Layout lesen

Als Markdown ansehen

Benötigte Berechtigung:sales:read(Ausgangsrechnungen und Entwürfe lesen)

GET
/api/layouts/{id}

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.

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.

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

Version wiederherstellen POST

Legt eine neue Version mit dem Stand einer älteren Version desselben Layouts an, wie „Wiederherstellen“ im Editor; `originRef` nennt die wiederhergestellte. So lässt sich jede Änderung zurücknehmen. Eine Version mit `check: failed` lässt sich nicht wiederherstellen. Idempotency-Key bei Wiederholung unverändert senden. Benötigt einen Schlüssel mit der Berechtigung `layout:write`.

Layout ändern PATCH

Ä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`.