Visão Geral
Em Definições do Espaço de Trabalho -> Empresa e Regional (/settings/workspace/general, /settings/workspace/company e /settings/workspace/regional), os administradores do espaço de trabalho configuram a identidade corporativa (Account Settings API), o perfil fiscal de faturação (PUT /api/v1/billing/settings e PUT /api/v1/billing/tax-profile) e as predefinições de formatação regional partilhadas entre todos os modelos de passes, portais públicos de transferência, consolidações de séries temporais de analítica e faturas fiscais da Stripe.
Fluxo de Metadados do Espaço de Trabalho e Configuração Regional
Importante: Verifique e guarde sempre a sua Denominação Social da Empresa, Morada de Faturação e NIF / Número de IVA (
PUT /api/v1/billing/settings) antes de executar uma atualização ou renovação de plano pago. As faturas fiscais em PDF geradas (GET /api/v1/billing/invoices/:id/download) são imutáveis depois de finalizadas pelo motor de faturação.
Perfil do Espaço de Trabalho (Account Settings API) e Perfil Fiscal (Billing API)
O recurso base de cliente (GET /api/v1/customer/:id e PUT /api/v1/customer/:id, validado estritamente com base em request payload com forbidNonWhitelisted) gere a identidade principal do espaço de trabalho, enquanto PUT /api/v1/billing/settings armazena os metadados de faturação de IVA/impostos (request payload):
| Campo | Endpoint (DTO) | Impacto Operacional | |
|---|---|---|---|
name / companyName | PUT /api/v1/customer/:id (request payload) | Nome de apresentação do espaço de trabalho e denominação corporativa da organização impressos nos passes. | |
email / notificationEmails | PUT /api/v1/customer/:id | E-mail de contacto principal do espaço de trabalho e lista de destinatários de alertas operacionais. | |
street, zipCode, city, state, country | PUT /api/v1/customer/:id | Campos da morada da sede social (street2 opcional). | |
subdomain / domain / logo / icon | PUT /api/v1/customer/:id | Slug do espaço de trabalho, associação de domínio personalizado e URLs de logótipo/ícone. | |
exportFormat (`'legacy' | 'new'`) | PUT /api/v1/customer/:id | Disposição predefinida de colunas CSV para exportações do espaço de trabalho. |
taxId, vatNumber, billingEmail, address | PUT /api/v1/billing/settings (request payload) | Número de IVA da UE (por exemplo, DE301928374), NIF e metadados do destinatário da fatura impressos nas faturas PDF da Stripe. |
Atualizar o Perfil do Espaço de Trabalho via 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 de Resposta (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"
}
Definições Regionais do Espaço de Trabalho (request payload)
As definições regionais (GET /api/v1/customer/:customerId/regional-settings e PUT /api/v1/customer/:customerId/regional-settings) definem as predefinições temporais, monetárias e de localização através de request payload:
-
1
timezone(string IANA, máx. 50 caracteres): Determina os limites da meia-noite para intervalos diários de analítica (GET /api/v1/analytics), agendamentos de fluxos de trabalho e reposições do período de arrefecimento do leitor emOncePerDayRule. -
2
countryIso(ISO 3166-1 alpha-2, por exemplo,"DE"): Jurisdição do país principal do espaço de trabalho. -
3
defaultCurrency(código ISO 4217 de 3 letras, por exemplo,"EUR"): Moeda predefinida para livros-razão de valor armazenadoPREPAID_CARDe resgates POS de retalho (POST /v1/pos/redeem). -
4
defaultLocale(etiqueta BCP-47, por exemplo,"de-DE"): Idioma de recurso apresentado nas páginas públicas de transferência (/d/:slug,/s/:token) e nos e-mails transacionais. -
5
dataResidencyRegion(string opcional, por exemplo,"eu-central-1"): Metadados de residência de dados do espaço de trabalho.
Atualizar Definições Regionais via 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"
}
Documentação Relacionada
-
Configure domínios personalizados (
CNAME) e remetentes de e-mail SMTP/DKIM com a sua marca em Personalização de Marca e Opções White-Label. -
Transfira faturas em PDF em conformidade com o IVA em Faturas e Histórico de Faturação.
-
Gira hierarquias de agências com múltiplos espaços de trabalho em Gestão Multicliente.
