Skip to content
Guía del Centro de ayuda · Agencias y socios
3 min de lecturaVerificado 2026-11-16

Gestión multicliente

Opera espacios de clientes separados con aislamiento estricto de datos y claves API dedicadas para agencias.

En esta guía

Jerarquía Multiespacio para Agencias y Aislamiento de Inquilinos

Las agencias digitales, los integradores de sistemas y las plataformas SaaS que gestionan múltiples marcas comerciales operan dentro de la arquitectura organizativa de dos niveles de Passinstance. Una Organización de nivel superior (modelo Organization) actúa como la entidad de gobernanza principal que posee y aprovisiona múltiples Espacios de Trabajo de Clientes estrictamente aislados (modelo Customer).

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
TENENCIA MULTIESPACIO PARA AGENCIAS
ETAPA 01 ORGANIZACIÓN DE LA AGENCIA (Modelo Organization)
Gobernanza Centralizada (OrganizationMemberRole: OWNER, ADMIN, MEMBER)
Resumen Consolidado (GET/api/v1/organizations/current/billing-summary)
ETAPA 02 1:N Espacios de Trabajo de Clientes Aislados
ESPACIO CLIENTE A (production)
ID de Inquilino: cust_client_a_01
Cert. .p12 Apple y Auth Google Ded.
Claves con Alcance: pi_live_...
Claves de Escáner y Webhooks Propios
ESPACIO CLIENTE B (sandbox)
ID de Inquilino: cust_client_b_02
Plantillas y Pases de Prueba Aislados
Claves con Alcance: pi_test_...
Cero Impacto en Cuotas de Producción

Invariantes Principales de Aislamiento

  • Particionado Estricto de Datos: Las plantillas, los pases emitidos (externalId, serialNumber), los certificados de firma criptográfica (.p12 con bundleId / passTypeIdentifier por comercio), los registros de validación del escáner, las suscripciones a webhooks y la PII de los clientes están delimitados al espacio de trabajo individual (customerId).
  • Cero Fugas entre Inquilinos: Las claves de API con alcance de espacio de trabajo (pi_live_ y pi_test_) y las claves de escáner móvil (x-scanner-key) están vinculadas criptográficamente a un único customerId y nunca pueden consultar, mutar ni escanear pases pertenecientes a un espacio de trabajo de cliente hermano.
  • Identidad de Billetera por Cliente: Las agencias cargan certificados dedicados de Apple Pass Type ID (bundleId) y credenciales de emisor de Google Wallet por espacio de trabajo para que las notificaciones en la pantalla de bloqueo y los encabezados de los pases de cada comercio muestren su propia identidad de marca.

Gestión de Espacios de Trabajo de Clientes mediante la API de Organizaciones

Los administradores de agencias pueden inspeccionar la estructura de su organización, aprovisionar nuevos espacios de trabajo de clientes, cambiar los contextos de inquilino activos y recuperar telemetría de facturación consolidada mediante Organizations API:

Ruta del EndpointMétodoAutenticaciónDescripción
/api/v1/organizations/currentGET / PUTBearerLee o actualiza la Organization activa, los roles de los miembros (OrganizationMemberRole: `OWNERADMINMEMBER) y todos los espacios de trabajo Customer` hermanos accesibles.
/api/v1/organizations/current/workspacesPOSTBearerAprovisiona un nuevo espacio de trabajo de cliente aislado (`kind: "production" \"sandbox"`).
/api/v1/organizations/current/workspaces/switchPOSTBearerCambia el contexto del espacio de trabajo activo y rota los tokens de autenticación de sesión.
/api/v1/organizations/current/billing-summaryGETBearerAgrega las cuotas del plan y los recuentos de pases de billetera activos en todos los espacios de trabajo secundarios.

Aprovisionamiento de un Nuevo Espacio de Trabajo de Cliente

Al incorporar un nuevo comercio o configurar un entorno de prueba dedicado, llame a POST /api/v1/organizations/current/workspaces con request payload (name y kind: estrictamente "production" o "sandbox", y luego configure los valores predeterminados regionales por separado mediante PUT /api/v1/customer/:customerId/regional-settings):

JSON
{
  "name": "Artisan Coffee Roasters — EU",
  "kind": "production"
}

Cambio de Espacios de Trabajo y Rotación de Sesión

Cuando un operador de agencia cambia entre cuentas de clientes en el panel o mediante POST /api/v1/organizations/current/workspaces/switch, Passinstance realiza una rotación atómica de la sesión para evitar la contaminación del estado entre inquilinos:

JSON
{
  "workspaceId": "cust_client_a_01"
}

Respuesta (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"
}

Resumen de Facturación Consolidada para Agencias

En lugar de conciliar facturas separadas para cada proyecto de cliente, los propietarios de agencias pueden supervisar las instalaciones acumuladas en billeteras activas en todos los espacios de trabajo de producción mediante 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: El campo kind del espacio de trabajo acepta estrictamente "production" o "sandbox" según lo exigido por request payload. Los espacios de trabajo de sandbox aíslan la creación de prototipos de plantillas y las pruebas de integración sin consumir capacidad de pases de billetera activos de la cuota de facturación de producción de su organización.

Consulte todas las capacidades multiinquilino en la Descripción General de Marca Blanca y Multiinquilino o explore las modalidades de asociación para agencias en /partners.

Documentación de producto y API relacionada

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.