Arquitectura central y entidades de la plataforma
Para construir flujos de trabajo de monederos digitales fiables, desarrolladores y administradores deben comprender cómo Passinstance organiza las plantillas, los registros dinámicos de pases, las mecánicas de lógica de negocio y los estados de registro de dispositivos.
Esquema de entidades del backend y mapeo de modelos Passinstance database
Cada concepto de la plataforma corresponde directamente a una entidad estructurada de Passinstance database dentro de la capa de base de datos de Passinstance API:
| Concepto | Modelo Passinstance database | Responsabilidades y atributos almacenados | |||||
|---|---|---|---|---|---|---|---|
Plantilla (Template) | Template | Almacena la configuración visual, el tipo de diseño (pass type), relaciones de recursos (image asset slot), reglas de códigos de barras, expresiones regulares de identificadores personalizados y versionado en una tabla (groupId, versionNumber, rowKind: `PRODUCTION \ | PUBLISHED \ | ARCHIVED \ | DRAFT, status`: template status). | ||
Pase (Pass) | Pass | Representa una tarjeta individual emitida. Contiene id, serialNumber único, authenticationToken, downloadCode, externalId opcional único por inquilino, bundleId opcional (bundleId), idempotencyKey opcional, attributes en structured JSON, expirationDate, estado de artefactos (appleArtifactStatus, googleArtifactStatus) y banderas de ciclo de vida y anulación. | |||||
Mecánica de pase (pass mechanic) | pass mechanic | Configura reglas con estado asociadas a una plantilla. Almacena mechanicType (mechanic type), minimumValue, maximumValue, defaultChangeValue, niveles (PassTier) y reglas de control de límites. | |||||
Cuenta prepago (prepaid account) | prepaid account | Gestiona el valor monetario almacenado para tarjetas de regalo y prepago. Realiza el seguimiento del saldo en unidades enteras y enlaza con registros inmutables de transacciones prepaid ledger entry. | |||||
Paquete de pases (pass bundle) | pass bundle | Agrupa hasta 10 pases complementarios mediante Pass.bundleId (bundle grouping mode: `AUTO \ | MANUAL, BundleStatus: ACTIVE \ | CANCELLED) para descargar archivos multi-tarjeta .pkpasses`. | |||
| Wallet Experience | PassProject | Coordina una plantilla principal (mainTemplateId) y plantillas vinculadas (PassProjectTemplateRole: `PRIMARY \ | LINKED \ | PRIVACY_MODE \ | INACTIVE \ | VIP \ | CUSTOM`), páginas unificadas de descarga, paquetes, segmentos y flujos de automatización visual. |
| PassFlow | PassFlow | Gestiona páginas de registro autoservicio de varios pasos (/f/:url, PassFlowType, PassFlowStatus) con formularios personalizables, verificación OTP por SMS/correo, protección anti-bots (SpamProtectionMode), pasarelas de pago y entrega directa al monedero. | |||||
| Configuración de escáner | ScannerConfiguration | Configura ubicaciones físicas de registro (ValidationPlace), tokens con alcance limitado ScannerKey, modos de validación (ScanMode), ajustes de lectores NFC (NfcReaderMode) y sincronización de datos sin conexión. |
Identificadores principales y claves de correlación del pase
Al integrar sistemas CRM, pasarelas de pago de comercio electrónico o plataformas de venta de entradas, tenga en cuenta el propósito exacto de cada identificador en un Pass:
| Campo | Columna / Ámbito Passinstance database | Mutabilidad y formato | Propósito principal |
|---|---|---|---|
id | Clave primaria UUID | Generado por el sistema, inmutable | Referencia interna de recurso en la API (GET /api/v1/passes/:id). |
serialNumber | Cadena única globalmente | Generado por el sistema (o personalizado si se configura), inmutable | Identificador canónico .pkpass de Apple Wallet y sufijo de objeto en Google. |
externalId | @unique([customerId, externalId]) donde archivedAt IS NULL | Cadena proporcionada por el cliente API (máx. 255 caracteres) | Clave de negocio procedente de su CRM, POS o base de entradas que permite sincronización idempotente con POST /api/v1/passes/upsert-by-external-id y consulta mediante GET /api/v1/passes/by-external-id/:externalId. |
bundleId | bundleId (clave foránea UUID hacia pass bundle) | Gestionado por el sistema vía /api/v1/bundles/* o PassProject | Agrupa hasta 10 pases en un paquete Apple multi-tarjeta .pkpasses o en una experiencia unificada de descarga. |
idempotencyKey | @unique([customerId, idempotencyKey]) | Proporcionado mediante cabecera Idempotency-Key (<=128 caracteres [A-Za-z0-9._:-]+) | Evita la emisión duplicada de pases si se reintenta una petición HTTP POST /api/v1/passes; verificado mediante hash SHA-256 del cuerpo de la solicitud. |
downloadCode / authenticationToken | Tokens de seguridad por pase | Cadenas criptográficas generadas por el sistema | Código corto de descarga pública y secreto compartido Authorization: ApplePass <token> para el Apple Web Service. |
Enums de máquinas de estados y ciclo de vida
Los registros de pases avanzan a través de máquinas de estados estrictas definidas en los enums de Passinstance database durante la creación, la sincronización con el monedero y la anulación o eliminación:
Estado del pase (pass status)
-
DRAFT: Provisionado como borrador sin emitir y aún no disponible para su instalación pública. -
AWAITING_OPT_IN: Generado durante flujos de registro con confirmación/OTP; a la espera de verificación antes de activarse. -
GENERATING: En proceso de generación asíncrona del pase o de sus artefactos. -
ACTIVE: Emitido y válido. Disponible para instalación en el monedero y validación en escáneres. -
INACTIVE: Pausado o desactivado temporalmente; los escáneres rechazan su validación hasta su reactivación. -
EXPIRED: Ha superado su fechaexpirationDate; los escáneres lo rechazan con el motivoPASS_EXPIRED. -
REDEEMED: Cupón o vale de un solo uso que ya ha completado su canje. -
CANCELLED,SUSPENDED,PENDING_ACTIVATION: Estados especializados para facturación, administración y preactivación. -
VOIDED: Revocado o anulado por un administrador o por una regla de escaneo; los escáneres lo rechazan conPASS_VOIDED.
Ciclo de vida del pase, modo de eliminación y disponibilidad de artefactos
-
PassLifecycleStatus: Controla las transiciones irreversibles de anulación y purga definitiva:
ACTIVE ---> VOIDING ---> VOIDED ---> DELETING ---> DELETED
-
PassDeletionMode: Diferencia entre eliminación lógica (SOFT, conserva el historial de auditoría y libera la unicidad deexternalIdpara nuevos pases activos) y eliminación permanente (HARD,DELETE /api/v1/passes/:id/hard). -
ArtifactStatus(appleArtifactStatusygoogleArtifactStatus): Realiza el seguimiento del estado de generación por ecosistema (NOT_GENERATED,GENERATING,READY,FAILED,INVALIDATED).
Estado de anulación y propagación al monedero (walletVoidStatus / WalletPropagationStatus)
Supervisa la propagación asíncrona del estado de anulación o actualización hacia Apple APNs y Google Wallet en el campo Pass.walletVoidStatus:
-
NONE: No hay ninguna propagación pendiente. -
PENDING: Estado guardado en la base de datos; a la espera de entrar en cola. -
QUEUED: Despachado a los workers de background job queue encargados de sincronizar con el monedero. -
SUCCEEDED: Confirmado por el despertar APNs de Apple o por elPATCHREST de Google. -
FAILED: Falló el envío push al proveedor de monedero (elegible para reintento automático o regeneración manual).
Propiedades personalizadas e interpolación dinámica de tokens
Passinstance utiliza la sintaxis dinámica con llaves {propertyName} para enlazar datos de clientes en los campos de la tarjeta:
-
Sintaxis: Inserte
{firstName},{pointsBalance}o{membershipTier}en cualquier etiqueta o valor de los campos principales, secundarios, auxiliares o del reverso. -
Mensajes de cambio: Configure
changeMessage: "¡Ha ganado un sello! Ahora tiene %@ sellos."en los campos de Apple Wallet. Al actualizarse, el marcador%@se sustituye por el nuevo valor y genera una notificación inmediata en la pantalla de bloqueo de iOS. -
Valores con formato: Los campos del reverso en Apple Wallet admiten etiquetas HTML de enlace (
<a href="https://example.com">Condiciones</a>) para enlaces web interactivos, números de teléfono y direcciones de correo electrónico.
Importante: La capacidad de facturación mide los Pases de monedero activos (el número total de dispositivos registrados actualmente mediante Apple APNs o mediante objetos en Google Wallet), no los borradores sin emitir ni los pases caducados.
