API Branding

Personalizza le superfici rivolte ai clienti — chrome della SPA, email di invito, intestazioni e piè di pagina dei report PDF — con il tuo logo, i colori d'accento e il nome del prodotto. L'oggetto Branding è per org e si applica a ogni sessione creata sotto quell'org.

L'oggetto Branding

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

Campo	Tipo	Note
`logo_url`	URL	Quadrato o orizzontale; renderizzato a 40px di altezza nell'intestazione della SPA, 64px nell'intestazione del PDF.
`wordmark_url`	URL	Opzionale. Usato insieme a `logo_url` nelle chrome più larghe.
`favicon_url`	URL	PNG / ICO 32×32. Servito dal tuo CDN; non replicato.
`primary_color`	hex (#rrggbb)	Accento principale — usato per pulsanti, link e la fascia di copertina del PDF.
`accent_color`	hex (#rrggbb)	Accento secondario — usato per evidenziazioni, badge, tratti delle sparkline.
`product_name_override`	string ≤ 120	Sostituisce "NexBasira" nelle stringhe visibili all'utente (titolo della pagina, oggetto delle email).
`support_email`	email	Mostrata nelle pagine di errore e nei piè di pagina delle email di invito. Vuoto = valore predefinito della piattaforma.
`support_url`	URL	Uguale — collegata dal menu di aiuto della SPA.
`email_from_name`	string ≤ 120	Nome mittente nella posta transazionale in uscita (comunque instradata tramite il nostro dominio autenticato per preservare l'allineamento DMARC).
`pdf_footer_text`	string ≤ 255	Piè di pagina su una riga in ogni pagina del report di audit PDF.

Stringa vuota su qualsiasi campo = valore predefinito della piattaforma. La riga Branding viene creata automaticamente al primo GET, quindi non vedrai mai un 404 qui.

Leggi il branding

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

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

Aggiorna il branding

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

Aggiornamento parziale — fornisci solo i campi che vuoi modificare. Invia "" su qualsiasi campo per riportarlo al valore predefinito della piattaforma. I colori esadecimali vengono validati rispetto a #rrggbb; un valore non valido restituisce 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"
  }'

Restituisce l'oggetto Branding appena aggiornato. La modifica è immediata al successivo caricamento della pagina — non c'è cache CDN da invalidare per la SPA. Per le email di invito e i PDF, il nuovo branding si applica a tutto ciò che viene generato dopo che il PATCH è andato a buon fine.

Errori comuni

Stato	Codice	Quando
400	`validation_error`	Colore esadecimale non valido, URL malformato o stringa oltre la lunghezza massima.
403	`permission_denied`	La credenziale non dispone dello scope (`branding:read` per GET, `branding:write` per PATCH).

Note

Nessun caricamento di immagini. La piattaforma non ospita i tuoi asset — fornisci URL HTTPS delle immagini che servi già dal tuo CDN. In questo modo l'invalidazione della cache resta sotto il tuo controllo.
Applicazione della stessa origine. Gli URL di logo e favicon devono servire Access-Control-Allow-Origin: * (o l'origine della tua SPA) affinché il browser possa renderizzarli all'interno del widget iframe-embed.
Sottoposto ad audit. Ogni PATCH registra un evento di audit org.branding_updated con il diff a livello di campo, così un logo manomesso è tracciabile fino a una credenziale e a una marca temporale.