Panoramica
In Impostazioni del workspace -> Azienda e impostazioni regionali (/settings/workspace/general, /settings/workspace/company e /settings/workspace/regional), gli amministratori del workspace configurano l'identità aziendale (Account Settings API), il profilo fiscale di fatturazione (PUT /api/v1/billing/settings e PUT /api/v1/billing/tax-profile) e le impostazioni predefinite di formattazione regionale condivise tra tutti i modelli di pass, i portali di download pubblici, le aggregazioni temporali delle analitiche e le fatture fiscali di Stripe.
Flusso di configurazione dei metadati del workspace e delle impostazioni regionali
Importante: Verifichi e salvi sempre la Ragione sociale, l'Indirizzo di fatturazione e la Partita IVA / Codice fiscale (
PUT /api/v1/billing/settings) prima di eseguire l'upgrade o il rinnovo di un piano a pagamento. Le fatture fiscali PDF generate (GET /api/v1/billing/invoices/:id/download) sono immutabili una volta finalizzate dal motore di fatturazione.
Profilo del workspace (Account Settings API) e profilo fiscale (Billing API)
La risorsa cliente di base (GET /api/v1/customer/:id e PUT /api/v1/customer/:id, convalidata rigorosamente rispetto a request payload con forbidNonWhitelisted) gestisce l'identità principale del workspace, mentre PUT /api/v1/billing/settings memorizza i metadati di fatturazione fiscale e IVA (request payload):
| Campo | Endpoint (DTO) | Impatto operativo | |
|---|---|---|---|
name / companyName | PUT /api/v1/customer/:id (request payload) | Nome visualizzato del workspace e ragione sociale dell'organizzazione stampati sui pass. | |
email / notificationEmails | PUT /api/v1/customer/:id | Email di contatto principale del workspace ed elenco dei destinatari degli avvisi operativi. | |
street, zipCode, city, state, country | PUT /api/v1/customer/:id | Campi dell'indirizzo della sede legale (street2 facoltativo). | |
subdomain / domain / logo / icon | PUT /api/v1/customer/:id | Slug del workspace, associazione del dominio personalizzato e URL di logo e icona. | |
exportFormat (`'legacy' | 'new'`) | PUT /api/v1/customer/:id | Layout predefinito delle colonne CSV per le esportazioni del workspace. |
taxId, vatNumber, billingEmail, address | PUT /api/v1/billing/settings (request payload) | Numero di Partita IVA UE (ad es. DE301928374), codice fiscale e metadati del destinatario stampati sulle fatture PDF di Stripe. |
Aggiornamento del profilo del workspace tramite API (PUT /api/v1/customer/:id)
PUT /api/v1/customer/cus_89a12b34-56c7-4d89-9e01-23456789abcd HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"name": "Phenix Hospitality Europe",
"companyName": "Phenix Hospitality GmbH",
"email": "passes@phenix-hospitality.example.com",
"street": "Friedrichstrasse 114A",
"zipCode": "10117",
"city": "Berlin",
"country": "DE",
"exportFormat": "new"
}
Payload di risposta (200 OK)
{
"id": "cus_89a12b34-56c7-4d89-9e01-23456789abcd",
"name": "Phenix Hospitality Europe",
"companyName": "Phenix Hospitality GmbH",
"email": "passes@phenix-hospitality.example.com",
"street": "Friedrichstrasse 114A",
"city": "Berlin",
"zipCode": "10117",
"country": "DE",
"exportFormat": "new",
"isActive": true,
"updatedAt": "2026-11-16T09:33:12.000Z"
}
Impostazioni regionali del workspace (request payload)
Le impostazioni regionali (GET /api/v1/customer/:customerId/regional-settings e PUT /api/v1/customer/:customerId/regional-settings) definiscono i valori predefiniti relativi a fuso orario, valuta e localizzazione tramite request payload:
-
1
timezone(stringa IANA, max 50 caratteri): determina il limite di mezzanotte per gli intervalli giornalieri delle analitiche (GET /api/v1/analytics), le pianificazioni dei flussi di lavoro e i ripristini del tempo di attesa dello scanner perOncePerDayRule. -
2
countryIso(ISO 3166-1 alpha-2, ad es."DE"): giurisdizione nazionale principale per il workspace. -
3
defaultCurrency(codice ISO 4217 a 3 lettere, ad es."EUR"): valuta predefinita per i registri di valore prepagatoPREPAID_CARDe i riscatti POS retail (POST /v1/pos/redeem). -
4
defaultLocale(tag BCP-47, ad es."de-DE"): lingua di fallback servita sulle pagine di download pubbliche (/d/:slug,/s/:token) e nelle email transazionali. -
5
dataResidencyRegion(stringa facoltativa, ad es."eu-central-1"): metadati sulla residenza dei dati del workspace.
Aggiornamento delle impostazioni regionali tramite API
PUT /api/v1/customer/cus_89a12b34-56c7-4d89-9e01-23456789abcd/regional-settings HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"timezone": "Europe/Berlin",
"countryIso": "DE",
"defaultCurrency": "EUR",
"defaultLocale": "de-DE",
"dataResidencyRegion": "eu-central-1"
}
{
"customerId": "cus_89a12b34-56c7-4d89-9e01-23456789abcd",
"timezone": "Europe/Berlin",
"countryIso": "DE",
"defaultCurrency": "EUR",
"defaultLocale": "de-DE",
"dataResidencyRegion": "eu-central-1",
"updatedAt": "2026-11-16T09:34:00.000Z"
}
Documentazione correlata
-
Configuri domini vanity personalizzati (
CNAME) e mittenti email SMTP/DKIM personalizzati in Branding personalizzato e opzioni White-Label. -
Scarichi fatture PDF conformi ai requisiti IVA in Fatture e cronologia di fatturazione.
-
Gestisca gerarchie di agenzie multi-workspace in Gestione multi-cliente.
