Présentation
Sous Workspace Settings -> Company & Regional (/settings/workspace/general, /settings/workspace/company et /settings/workspace/regional), les administrateurs d'espace de travail configurent l'identité d'entreprise (Account Settings API), le profil fiscal de facturation (PUT /api/v1/billing/settings & PUT /api/v1/billing/tax-profile) ainsi que les valeurs régionales par défaut partagées entre tous les modèles de passes, les portails publics de téléchargement, les cumuls de séries temporelles analytiques et les factures fiscales Stripe.
Flux de configuration des métadonnées d'espace de travail et des paramètres régionaux
Important : Vérifiez et enregistrez toujours votre raison sociale, votre adresse de facturation et votre numéro de TVA / identifiant fiscal (
PUT /api/v1/billing/settings) avant d'effectuer une mise à niveau vers un forfait payant ou un renouvellement. Les factures fiscales PDF générées (GET /api/v1/billing/invoices/:id/download) sont immuables une fois finalisées par le moteur de facturation.
Profil de l'espace de travail (Account Settings API) et profil fiscal (Billing API)
La ressource client de base (GET /api/v1/customer/:id et PUT /api/v1/customer/:id, validée strictement par rapport à request payload avec forbidNonWhitelisted) gère l'identité principale de l'espace de travail, tandis que PUT /api/v1/billing/settings stocke les métadonnées de facturation fiscale et de TVA (request payload) :
| Champ | Point de terminaison (DTO) | Impact opérationnel | |
|---|---|---|---|
name / companyName | PUT /api/v1/customer/:id (request payload) | Nom d'affichage de l'espace de travail et raison sociale imprimée sur les passes. | |
email / notificationEmails | PUT /api/v1/customer/:id | Adresse e-mail de contact principale de l'espace de travail et liste des destinataires des alertes opérationnelles. | |
street, zipCode, city, state, country | PUT /api/v1/customer/:id | Champs de l'adresse du siège social (street2 facultatif). | |
subdomain / domain / logo / icon | PUT /api/v1/customer/:id | Slug de l'espace de travail, liaison de domaine personnalisé et URL de logo/icône. | |
exportFormat (`'legacy' | 'new'`) | PUT /api/v1/customer/:id | Disposition des colonnes CSV par défaut pour les exportations de l'espace de travail. |
taxId, vatNumber, billingEmail, address | PUT /api/v1/billing/settings (request payload) | Numéro de TVA intracommunautaire (par ex. DE301928374), identifiant fiscal et métadonnées du destinataire imprimés sur les factures PDF Stripe. |
Mise à jour du profil de l'espace de travail via l'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"
}
Charge utile de réponse (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"
}
Paramètres régionaux de l'espace de travail (request payload)
Les paramètres régionaux (GET /api/v1/customer/:customerId/regional-settings et PUT /api/v1/customer/:customerId/regional-settings) définissent les valeurs temporelles, monétaires et de localisation par défaut via request payload :
-
1
timezone(chaîne IANA, 50 caractères max.) : Détermine les heures de coupure à minuit pour les intervalles analytiques quotidiens (GET /api/v1/analytics), les planifications de workflows et les réinitialisations de délai de carence du scannerOncePerDayRule. -
2
countryIso(ISO 3166-1 alpha-2, par ex.,"DE") : Juridiction nationale principale de l'espace de travail. -
3
defaultCurrency(code ISO 4217 à 3 lettres, par ex.,"EUR") : Devise par défaut pour les grands livres à valeur stockéePREPAID_CARDet les échanges en point de vente (POST /v1/pos/redeem). -
4
defaultLocale(balise BCP-47, par ex.,"de-DE") : Langue de repli servie sur les pages publiques de téléchargement (/d/:slug,/s/:token) et dans les e-mails transactionnels. -
5
dataResidencyRegion(chaîne facultative, par ex.,"eu-central-1") : Métadonnées de résidence des données de l'espace de travail.
Mise à jour des paramètres régionaux via l'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"
}
Documentation connexe
-
Configurez des domaines personnalisés (
CNAME) et des expéditeurs d'e-mails SMTP/DKIM à votre marque dans Personnalisation de marque et options en marque blanche. -
Téléchargez des factures PDF conformes à la TVA dans Factures et historique de facturation.
-
Gérez des hiérarchies d'agence multi-espaces de travail dans Gestion multi-clients.
