Skip to content
Guía del Centro de ayuda · Introducción a PassinstanceFase de incorporación 2
6 min de lecturaVerificado 2026-11-16

Conceptos clave y terminología

Definiciones claras de Plantillas, Pases, Mecánicas, Atributos, Wallet Experiences (Proyectos), PassFlow y Registros activos.

En esta guía

Recorridos visuales interactivos

Abrir en la guía de 6 fases

Inspecciona las pantallas reales del panel y las anotaciones ampliadas de esta guía.

Enfoque de interfaz ampliado
Elementos clave de la interfaz

Propiedades y atributos personalizados (Zoom)

Define atributos reutilizables del cliente ({serviceOrDuration}, {holderName}, {passReference}, {validUntil}, {memberQrToken}) y configura sus tipos y reglas.

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.

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
RELACIONES ENTRE ENTIDADES
ETAPA 01 Template (Diseño base y versionado)
Diseño: StoreCard, EventTicket, Coupon, Membership
Colores, simbología de barras, mapeo de campos, imágenes
ETAPA 02 Emisión 1:N | Regla 1:1 vinculada
Pass (Instancia concreta)
SerialNumber y AuthToken
Valores de campo dinámicos
Estado y ExpirationDate
Registro en dispositivo 1:N (App
pass mechanic (Motor de estado)
Tipo: STAMP_CARD_ADD, LOYALTY_PROGRAM, PREPAID_CARD,
VALID_ONCE_PER_DAY rdados en Google)

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:

ConceptoModelo Passinstance databaseResponsabilidades y atributos almacenados
Plantilla (Template)TemplateAlmacena 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)PassRepresenta 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 mechanicConfigura 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 accountGestiona 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 bundleAgrupa hasta 10 pases complementarios mediante Pass.bundleId (bundle grouping mode: `AUTO \MANUAL, BundleStatus: ACTIVE \CANCELLED) para descargar archivos multi-tarjeta .pkpasses`.
Wallet ExperiencePassProjectCoordina 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.
PassFlowPassFlowGestiona 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ánerScannerConfigurationConfigura 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:

CampoColumna / Ámbito Passinstance databaseMutabilidad y formatoPropósito principal
idClave primaria UUIDGenerado por el sistema, inmutableReferencia interna de recurso en la API (GET /api/v1/passes/:id).
serialNumberCadena única globalmenteGenerado por el sistema (o personalizado si se configura), inmutableIdentificador canónico .pkpass de Apple Wallet y sufijo de objeto en Google.
externalId@unique([customerId, externalId]) donde archivedAt IS NULLCadena 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.
bundleIdbundleId (clave foránea UUID hacia pass bundle)Gestionado por el sistema vía /api/v1/bundles/* o PassProjectAgrupa 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 / authenticationTokenTokens de seguridad por paseCadenas criptográficas generadas por el sistemaCó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 fecha expirationDate; los escáneres lo rechazan con el motivo PASS_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 con PASS_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:
TEXT
ACTIVE  --->  VOIDING  --->  VOIDED  --->  DELETING  --->  DELETED
  • PassDeletionMode: Diferencia entre eliminación lógica (SOFT, conserva el historial de auditoría y libera la unicidad de externalId para nuevos pases activos) y eliminación permanente (HARD, DELETE /api/v1/passes/:id/hard).
  • ArtifactStatus (appleArtifactStatus y googleArtifactStatus): 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 el PATCH REST 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.

¿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.