La API REST de Passinstance está organizada en controladores de dominio modulares montados principalmente bajo /api/v1 (con montajes dedicados sin prefijo para POS /v1/pos/*, Pull Webhooks /webhook-payload, webhooks entrantes de proveedores /webhooks/*, sondas de salud /health/* y Smart Links /s/:token y /d/:slug). Cada endpoint utiliza verbos HTTP estándar (GET, POST, PUT, PATCH, DELETE), aplica aislamiento por inquilino del espacio de trabajo a partir de su credencial de API y devuelve una carga útil JSON determinista (API response (T) en las APIs del espacio de trabajo).
Requisitos previos: Genere una API Key del espacio de trabajo (pi_live_... o pi_test_...) con los API_KEY_SCOPE_VALUES necesarios (passes, templates, scans, webhooks, analytics o *) en /settings/workspace/developer/api-credentials antes de invocar rutas /api/v1/*. La documentación interactiva OpenAPI está disponible en GET /api/public/docs y en /docs.
Ciclo de vida de solicitudes y respuestas
FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
SOLICITUD REST API Y CICLO DE VIDA DEL SOBRE
ACTORES DEL SISTEMA
P1Integración externa
P2Passinstance /api/v1/*
P3Proveedores Wallet y BD
PASO 1SOLICITUD / ACCIÓNPOST/api/v1/passes
PASO 2SOLICITUD / ACCIÓNValidar DTO y ámbito inquilino
PASO 3SOLICITUD / ACCIÓNFirmar .pkpass (bundleId)
›
idempotencyKey
›
y generar JWT Google Wallet
PASO 4RESPUESTA201 Created
›
API response (request payload)
PASO 5SOLICITUD / ACCIÓNPATCH/api/v1/passes/:id
PASO 6SOLICITUD / ACCIÓNConfirmar actualización
PASO 7RESPUESTA200 OK
›
7. Encolar push APNs y Google→
[ FLUJO DE ARQUITECTURA: SOLICITUD REST API Y CICLO DE VIDA DEL SOBRE ]
Integración externa Passinstance /api/v1/* Proveedores Wallet y BD
| | |
|-- 1. POST /api/v1/passes --------->| |
| Header: x-api-key: pi_live_.. |-- 2. Validar DTO y ámbito inquilino|
| Body: externalId, |-- 3. Firmar .pkpass (bundleId) |
| idempotencyKey | y generar JWT Google Wallet ->|
|<-- 4. 201 Created -----------------| |
| API response (request payload) | |
| | |
|-- 5. PATCH /api/v1/passes/:id ---->| |
| Body: { attributes: {...} } |-- 6. Confirmar actualización ----->|
|<-- 7. 200 OK ----------------------|-- 7. Encolar push APNs y Google -->|
Catálogo de endpoints REST por dominio
1. Pases, upserts y operaciones por lotes
Verbo
Ruta
Descripción
POST
/api/v1/passes
Emite una instancia de pase (request payload: templateId, externalId opcional, idempotencyKey, attributes) firmada con el certificado de la plantilla (bundleId = passTypeIdentifier de Apple).
POST
/api/v1/passes/upsert-by-external-id
Crea o actualiza de forma idempotente un pase emparejado por (templateId, externalId) (request payload).
GET
/api/v1/passes
Lista instancias de pases con paginación, filtrado por estado (pass status) y consultas de búsqueda.
GET
/api/v1/passes/:id
Recupera detalles completos, atributos dinámicos, externalId, serialNumber y estado de registro.
PATCH / PUT
/api/v1/passes/:id
Actualiza campos dinámicos, nivel o fecha de caducidad y envía actualizaciones en vivo a los Wallets instalados.
POST
/api/v1/passes/voiding/:id/void
Anula un pase (request payload + VoidingReason) y envía una actualización push silenciosa con voided: true.
DELETE
/api/v1/passes/:id
Elimina de forma lógica un pase y revoca las instalaciones activas en Wallet.
POST
/api/v1/passes/export
Exporta registros de pases filtrados como un trabajo descargable en CSV UTF-8 o JSON.
POST
/api/v1/batch-pass-operations/create
Ejecuta creación masiva síncrona o encolada mediante Batch Operations API (también /update, /upsert, /activate, /deactivate, /delete).
POST
/api/v1/batch-processing
Envía un trabajo masivo asíncrono de gran volumen en CSV/JSON supervisado mediante Batch Processing API.
2. Plantillas y mecánicas
Verbo
Ruta
Descripción
GET
/api/v1/templates
Lista las plantillas de pases del espacio de trabajo, tipos de pase (PassKind), enlaces de certificado bundleId y estados de publicación.
GET
/api/v1/templates/:id
Devuelve el esquema de la plantilla, la configuración visual y las mecánicas activas.
POST
/api/v1/templates/:id/publish
Publica cambios en borrador (request payload) y envía actualizaciones push por lotes (consulte antes GET .../publish-risk-check).
GET
/api/v1/templates/:templateId/attributes
Lista las claves y tipos de campos dinámicos necesarios al emitir pases (admite OAuth templates:read).
POST
/api/v1/mechanics/redeem
Canjea una recompensa desbloqueada de fidelización o tarjeta de sellos (request payload: UUID passId, mechanicId).
Devuelve el libro mayor de transacciones de la mecánica de valor almacenado o fidelización de un pase (GET /api/v1/balance-changes para el flujo del inquilino).
3. Escaneos, dispositivos y validación POS
Verbo
Ruta
Descripción
POST
/api/v1/scans
Evalúa un escaneo de código de barras o NFC frente al motor de 14 reglas Validation Rules Engine (ScanMode y scan status).
POST
/api/v1/scans/prepare
Emite un scan nonce criptográfico de corta duración para protección antirréplica.
GET
/api/v1/scans/pass
Consulta de pase de solo lectura por ?barcode=... (o parámetro de ruta GET /api/v1/scans/pass/:barcodeValue).