Skip to content
Guia da Central de Ajuda · Definições de conta e área
3 min de leituraVerificado 2026-11-16

Definições da empresa

Mantenha designação legal, NIF/IVA, nome de remetente predefinido e domínios personalizados verificados.

Neste guia

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

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
IDENTIDADE DO ESPAÇO E PROPAGAÇÃO REGIONAL
ETAPA 01 CAMADA DE CONFIGURAÇÃO DO PAINEL / API
Identidade Corporativa e Legal
GET/ PUT /api/v1/customer/:idPUT/api/v1/billing/settings
companyName, NIF/IVA, Morada
Definições Regionais e Residência
`GET / PUT/api/v1/customer/
:customerId/regional-settings`
timezone, countryIso, currency
ETAPA 02 CONSUMIDORES DO SISTEMA A JUSANTE
Motor de Faturação/IVA
Cabeçalhos PDF
Autoliquidação IVA
Analítica e Mecânicas
Cortes Diários
Registo de Saldo
Modelo e PassFlow
Moeda Predefinida
Subdomínio

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):

CampoEndpoint (DTO)Impacto Operacional
name / companyNamePUT /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 / notificationEmailsPUT /api/v1/customer/:idE-mail de contacto principal do espaço de trabalho e lista de destinatários de alertas operacionais.
street, zipCode, city, state, countryPUT /api/v1/customer/:idCampos da morada da sede social (street2 opcional).
subdomain / domain / logo / iconPUT /api/v1/customer/:idSlug do espaço de trabalho, associação de domínio personalizado e URLs de logótipo/ícone.
exportFormat (`'legacy''new'`)PUT /api/v1/customer/:idDisposição predefinida de colunas CSV para exportações do espaço de trabalho.
taxId, vatNumber, billingEmail, addressPUT /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)

HTTP
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)

JSON
{
  "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. 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 em OncePerDayRule.
  2. 2
    countryIso (ISO 3166-1 alpha-2, por exemplo, "DE"): Jurisdição do país principal do espaço de trabalho.
  3. 3
    defaultCurrency (código ISO 4217 de 3 letras, por exemplo, "EUR"): Moeda predefinida para livros-razão de valor armazenado PREPAID_CARD e resgates POS de retalho (POST /v1/pos/redeem).
  4. 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. 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

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

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.