Skip to content
Guia da Central de Ajuda · Agências e parceiros
3 min de leituraVerificado 2026-11-16

Gestão multi-cliente

Opere áreas de trabalho isoladas por cliente com separação estrita de dados e chaves API para agências.

Neste guia

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.

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
MULTI-INQUILINO POR ESPAÇOS DE AGÊNCIA
ETAPA 01 ORGANIZAÇÃO DE AGÊNCIA (Modelo Organization)
Governação Central (OrganizationMemberRole: OWNER, ADMIN, MEMBER)
Faturação Consolidada (GET/api/v1/organizations/current/billing-summary)
ETAPA 02 1:N Espaços de Cliente Isolados
ESPAÇO CLIENTE A (production)
Tenant ID: cust_client_a_01
.p12 Apple & Google Auth Dedicados
Chaves Delimitadas: pi_live_...
Chaves de Scanner & Webhooks Próprios
ESPAÇO CLIENTE B (sandbox)
Tenant ID: cust_client_b_02
Modelos & Cartões de Teste Isolados
Chaves Delimitadas: pi_test_...
Impacto Zero nas Quotas Produção

Invariantes Nucleares de Isolamento

  • Particionamento Estrito de Dados: Modelos, cartões emitidos (externalId, serialNumber), certificados criptográficos de assinatura (.p12 com bundleId / passTypeIdentifier pró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_ e pi_test_) e chaves do scanner móvel (x-scanner-key) ficam vinculadas criptograficamente a um único customerId, 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 EndpointMétodoAutenticaçãoDescrição
/api/v1/organizations/currentGET / PUTBearerLê ou atualiza a Organization ativa, funções dos membros (OrganizationMemberRole: `OWNERADMINMEMBER) e todos os espaços Customer` acessíveis.
/api/v1/organizations/current/workspacesPOSTBearerAprovisiona um novo espaço de trabalho isolado (`kind: "production" \"sandbox"`).
/api/v1/organizations/current/workspaces/switchPOSTBearerAlterna o contexto de espaço de trabalho ativo e roda os tokens de autenticação da sessão.
/api/v1/organizations/current/billing-summaryGETBearerAgrega 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):

JSON
{
  "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:

JSON
{
  "workspaceId": "cust_client_a_01"
}

Resposta (200 OK):

JSON
{
  "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:

JSON
{
  "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 kind do espaço aceita estritamente "production" ou "sandbox", conforme imposto por request payload. Os espaços sandbox isolam 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.

Documentação de produto e API 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.