Branding-API

Passen Sie die kundenseitigen Oberflächen an — SPA-Chrome, Einladungs-E-Mails, PDF-Bericht-Kopf- + Fußzeilen — mit Ihrem Logo, Ihren Akzentfarben und Ihrem Produktnamen. Das Branding-Objekt gilt pro Organisation und für jede unter dieser Organisation erstellte Sitzung.

Das Branding-Objekt

{
  "logo_url": "https://cdn.acme.com/logo.png",
  "wordmark_url": "",
  "favicon_url": "https://cdn.acme.com/favicon.ico",
  "primary_color": "#0F3D91",
  "accent_color": "#FFB400",
  "product_name_override": "Acme FieldView",
  "support_email": "support@acme.com",
  "support_url": "https://help.acme.com",
  "email_from_name": "Acme Claims",
  "pdf_footer_text": "Acme Insurance — claim report",
  "updated_at": "2026-05-10T14:00:00Z"
}

Feld	Typ	Hinweise
`logo_url`	URL	Quadratisch oder im Querformat; im SPA-Header mit 40px Höhe gerendert, im PDF-Header mit 64px.
`wordmark_url`	URL	Optional. Wird neben `logo_url` auf breiteren Oberflächen verwendet.
`favicon_url`	URL	32×32 PNG / ICO. Wird von Ihrem CDN ausgeliefert; nicht gespiegelt.
`primary_color`	hex (#rrggbb)	Hauptakzent — für Buttons, Links und das PDF-Deckblattband.
`accent_color`	hex (#rrggbb)	Sekundärakzent — für Highlights, Badges, Sparkline-Striche.
`product_name_override`	string ≤ 120	Ersetzt „NexBasira“ in nutzersichtbaren Texten (Seitentitel, E-Mail-Betreffzeilen).
`support_email`	email	Wird auf Fehlerseiten + in den Fußzeilen von Einladungs-E-Mails angezeigt. Leer = Plattform-Standard.
`support_url`	URL	Ebenso — verlinkt aus dem SPA-Hilfemenü.
`email_from_name`	string ≤ 120	Absendername für ausgehende Transaktions-E-Mails (weiterhin über unsere authentifizierte Domain geleitet, um die DMARC-Ausrichtung zu wahren).
`pdf_footer_text`	string ≤ 255	Einzeilige Fußzeile auf jeder Seite des PDF-Audit-Berichts.

Leerer String bei einem beliebigen Feld = Plattform-Standard. Die Branding-Zeile wird beim ersten GET automatisch erstellt, sodass Sie hier nie einen 404 sehen.

Branding lesen

GET /api/v1/public/branding — Bereich branding:read

curl https://app.nexbasira.com/api/v1/public/branding \
  -H "Authorization: Bearer nb_sec_..."

Branding aktualisieren

PATCH /api/v1/public/branding — Bereich branding:write

Partielles Update — geben Sie nur die Felder an, die Sie ändern möchten. Senden Sie "" für ein Feld, um es auf den Plattform-Standard zurückzusetzen. Hex-Farben werden gegen #rrggbb validiert; ein ungültiger Wert liefert 400.

curl -X PATCH https://app.nexbasira.com/api/v1/public/branding \
  -H "Authorization: Bearer nb_sec_..." \
  -H "Content-Type: application/json" \
  -d '{
    "primary_color": "#0F3D91",
    "logo_url": "https://cdn.acme.com/logo-2026.png"
  }'

Gibt das frisch aktualisierte Branding-Objekt zurück. Die Änderung ist beim nächsten Seitenaufruf sofort wirksam — für die SPA gibt es keinen CDN-Cache zu leeren. Bei Einladungs-E-Mails + PDFs gilt das neue Branding für alles, was nach Eintreffen des PATCH generiert wird.

Häufige Fehler

Status	Code	Wann
400	`validation_error`	Ungültige Hex-Farbe, fehlerhafte URL oder String über der Maximallänge.
403	`permission_denied`	Dem Credential fehlt der Scope (`branding:read` für GET, `branding:write` für PATCH).

Hinweise

Kein Bild-Upload. Die Plattform hostet Ihre Assets nicht — geben Sie HTTPS-URLs zu Bildern an, die Sie bereits über Ihr CDN ausliefern. So behalten Sie die Cache-Invalidierung in Ihrer Kontrolle.
Same-Origin-Durchsetzung. Logo- + Favicon-URLs müssen Access-Control-Allow-Origin: * (oder Ihren SPA-Origin) liefern, damit der Browser sie im iframe-Embed-Widget rendern kann.
Auditiert. Jeder PATCH erzeugt ein org.branding_updated-Audit-Event mit dem Diff auf Feldebene, sodass ein manipuliertes Logo einem Credential + Zeitstempel zugeordnet werden kann.