Übersicht
Unter Workspace-Einstellungen -> Unternehmen & Regionales (/settings/workspace/general, /settings/workspace/company und /settings/workspace/regional) konfigurieren Workspace-Administratoren die Unternehmensidentität (Account Settings API), das Steuerprofil für die Abrechnung (PUT /api/v1/billing/settings & PUT /api/v1/billing/tax-profile) sowie regionale Formatierungsstandards, die für alle Kartenvorlagen, öffentlichen Download-Portale, Zeitreihen-Rollups in den Analysen und Stripe-Steuerrechnungen gleichermaßen gelten.
Ablauf für Workspace-Metadaten & regionale Konfiguration
Wichtig: Überprüfen und speichern Sie Ihren offiziellen Firmennamen, Ihre Rechnungsadresse und Ihre USt-IdNr. / Steuernummer (
PUT /api/v1/billing/settings) immer, bevor Sie ein kostenpflichtiges Tarif-Upgrade oder eine Verlängerung durchführen. Generierte PDF-Steuerrechnungen (GET /api/v1/billing/invoices/:id/download) sind unveränderlich, sobald sie von der Abrechnungs-Engine finalisiert wurden.
Workspace-Profil (Account Settings API) & Steuerprofil (Billing API)
Die Basis-Kundenressource (GET /api/v1/customer/:id und PUT /api/v1/customer/:id, strikt validiert gegen request payload mit forbidNonWhitelisted) verwaltet die zentrale Workspace-Identität, während PUT /api/v1/billing/settings die USt.- und Steuerrechnungsmetadaten speichert (request payload):
| Feld | Endpunkt (DTO) | Operative Auswirkung | |
|---|---|---|---|
name / companyName | PUT /api/v1/customer/:id (request payload) | Anzeigename des Workspaces und offizieller Unternehmensname, der auf Karten gedruckt wird. | |
email / notificationEmails | PUT /api/v1/customer/:id | Primäre Kontakt-E-Mail-Adresse des Workspaces und Empfängerliste für operative Warnmeldungen. | |
street, zipCode, city, state, country | PUT /api/v1/customer/:id | Adressfelder des eingetragenen Firmensitzes (street2 optional). | |
subdomain / domain / logo / icon | PUT /api/v1/customer/:id | Workspace-Slug, Verknüpfung benutzerdefinierter Domains sowie Logo-/Icon-URLs. | |
exportFormat (`'legacy' \ | 'new'`) | PUT /api/v1/customer/:id | Standard-CSV-Spaltenlayout für Workspace-Exporte. |
taxId, vatNumber, billingEmail, address | PUT /api/v1/billing/settings (request payload) | EU-Umsatzsteuer-Identifikationsnummer (z. B. DE301928374), Steuernummer und Rechnungsempfänger-Metadaten auf Stripe-PDF-Rechnungen. |
Aktualisieren des Workspace-Profils per 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"
}
Antwort-Payload (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"
}
Regionale Einstellungen des Workspaces (request payload)
Regionale Einstellungen (GET /api/v1/customer/:customerId/regional-settings und PUT /api/v1/customer/:customerId/regional-settings) definieren die Zeit-, Währungs- und Lokalisierungsstandards über das request payload:
-
1
timezone(IANA-Zeichenfolge, max. 50 Zeichen): Bestimmt den Mitternachts-Cutoff für tägliche Analyseintervalle (GET /api/v1/analytics), Workflow-Zeitpläne und das Zurücksetzen der Scanner-Abklingzeit beiOncePerDayRule. -
2
countryIso(ISO 3166-1 alpha-2, z. B."DE"): Primäres Rechtsgebiet (Land) für den Workspace. -
3
defaultCurrency(3-stelliger ISO-4217-Code, z. B."EUR"): Standardwährung fürPREPAID_CARD-Guthabenkonten und POS-Einlösungen im Einzelhandel (POST /v1/pos/redeem). -
4
defaultLocale(BCP-47-Tag, z. B."de-DE"): Fallback-Sprache für öffentliche Download-Seiten (/d/:slug,/s/:token) und Transaktions-E-Mails. -
5
dataResidencyRegion(optionale Zeichenfolge, z. B."eu-central-1"): Metadaten zur Datenresidenz des Workspaces.
Aktualisieren der regionalen Einstellungen per 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"
}
Weiterführende Dokumentation
-
Konfigurieren Sie benutzerdefinierte Vanity-Domains (
CNAME) und gebrandete SMTP-/DKIM-E-Mail-Absender unter Individuelles Branding & White-Label-Optionen. -
Laden Sie USt.-konforme PDF-Rechnungen unter Rechnungen & Abrechnungshistorie herunter.
-
Verwalten Sie Agenturhierarchien mit mehreren Workspaces unter Mandantenverwaltung (Multi-Client Management).
