Hierarquia Multi-Espaço de Agências e Isolamento de Inquilinos
Agências digitais, integradores de sistemas e plataformas SaaS que gerem várias marcas comerciais operam na arquitetura organizacional de dois níveis do Passinstance. Uma Organização de topo (Organization) atua como entidade central de governação que detém e aprovisiona múltiplos Espaços de Trabalho de Cliente (Customer) rigorosamente isolados.
Invariantes Nucleares de Isolamento
-
Particionamento Estrito de Dados: Modelos, cartões emitidos (
externalId,serialNumber), certificados criptográficos de assinatura (.p12combundleId/passTypeIdentifierpróprios por comerciante), registos de validação de scanner, subscrições webhook e dados pessoais de clientes são delimitados ao espaço individual (customerId). -
Ausência de Fugas Entre Inquilinos: Chaves API delimitadas ao espaço (
pi_live_epi_test_) e chaves do scanner móvel (x-scanner-key) ficam vinculadas criptograficamente a um únicocustomerId, nunca podendo consultar, modificar ou ler cartões pertencentes a outro cliente. -
Identidade Wallet por Cliente: As agências carregam certificados Apple Pass Type ID (
bundleId) e credenciais de emissor Google Wallet próprios por espaço, para que notificações no ecrã bloqueado e cabeçalhos dos cartões exibam sempre a marca do comerciante correto.
Gerir Espaços de Clientes via API de Organização
Os administradores de agência podem consultar a estrutura da organização, aprovisionar novos espaços de clientes, alternar o contexto ativo de inquilino e obter telemetria consolidada de faturação através de Organizations API:
| Caminho do Endpoint | Método | Autenticação | Descrição | ||
|---|---|---|---|---|---|
/api/v1/organizations/current | GET / PUT | Bearer | Lê ou atualiza a Organization ativa, funções dos membros (OrganizationMemberRole: `OWNER | ADMIN | MEMBER) e todos os espaços Customer` acessíveis. |
/api/v1/organizations/current/workspaces | POST | Bearer | Aprovisiona um novo espaço de trabalho isolado (`kind: "production" \ | "sandbox"`). | |
/api/v1/organizations/current/workspaces/switch | POST | Bearer | Alterna o contexto de espaço de trabalho ativo e roda os tokens de autenticação da sessão. | ||
/api/v1/organizations/current/billing-summary | GET | Bearer | Agrega quotas do plano e totais de cartões ativos na Wallet por todos os espaços subordinados. |
Aprovisionar um Novo Espaço de Cliente
Ao integrar um novo comerciante ou configurar um ambiente de testes dedicado, invoque POST /api/v1/organizations/current/workspaces com request payload (name e kind: estritamente "production" ou "sandbox", definindo depois as predefinições regionais separadamente via PUT /api/v1/customer/:customerId/regional-settings):
{
"name": "Artisan Coffee Roasters — EU",
"kind": "production"
}
Alternar de Espaço e Rotação de Sessão
Quando um operador de agência muda entre contas de cliente no painel ou via POST /api/v1/organizations/current/workspaces/switch, o Passinstance executa uma rotação atómica de sessão para impedir contaminação entre inquilinos:
{
"workspaceId": "cust_client_a_01"
}
Resposta (200 OK):
{
"activeWorkspace": {
"id": "cust_client_a_01",
"name": "Artisan Coffee Roasters — EU",
"kind": "production",
"role": "ADMIN"
},
"sessionRotated": true,
"issuedAt": "2026-11-15T14:22:10.000Z"
}
Resumo Consolidado de Faturação de Agência
Em vez de conciliar faturas separadas por projeto de cliente, os proprietários de agência acompanham o total acumulado de instalações ativas na Wallet em todos os espaços de produção via GET /api/v1/organizations/current/billing-summary:
{
"organizationId": "org_agency_8841",
"planTier": "SCALE_10K",
"includedActivePasses": 10000,
"totalActivePassesAcrossWorkspaces": 6420,
"workspaces": [
{
"workspaceId": "cust_client_a_01",
"name": "Artisan Coffee Roasters — EU",
"kind": "production",
"activePasses": 4120
},
{
"workspaceId": "cust_client_b_02",
"name": "Artisan Coffee — Sandbox",
"kind": "sandbox",
"activePasses": 0
}
]
}
Importante: O campo
kinddo espaço aceita estritamente"production"ou"sandbox", conforme imposto porrequest payload. Os espaçossandboxisolam a criação de modelos e testes de integração sem consumir capacidade de cartões ativos da quota de produção da sua organização.
Explore todas as capacidades multi-inquilino na Visão Geral White-Label e Multi-Inquilino ou conheça os programas de parceiros em /partners.
