Descripción general
La emisión de pases individuales permite a operadores e integraciones backend generar una tarjeta digital personalizada a partir de cualquier plantilla en estado PUBLISHED. Ya sea desde el panel lateral Crear pase del Dashboard o de forma programática mediante API REST, Passinstance asigna un serialNumber y un authenticationToken criptográficamente únicos, rellena todos los campos dinámicos {variable}, firma el archivo .pkpass de Apple y el JWT de Google Wallet y devuelve una URL inteligente inmediata de distribución (passAccessUrl).

Arquitectura del sistema: emisión de pase individual y upsert idempotente
Emitir un pase individual manualmente en el panel
-
1
Vaya a la página de resumen de su plantilla Publicada.
-
2
Haga clic en Crear pase en la cabecera superior (o bajo Acciones rápidas).
-
3
Rellene cada Propiedad personalizada obligatoria marcada en el formulario (por ejemplo: nombre del cliente, correo/teléfono si se requiere envío, sello inicial o
externalId). -
4
Envíe el formulario para generar el pase al instante.
-
5
Copie la URL de descarga única (
passAccessUrl), muestre el código QR de instalación para escanearlo con un smartphone o lance un correo de entrega directamente desde el panel de detalles del pase.
Requisitos previos: Publique su plantilla (
POST /api/v1/templates/:id/publish) con credenciales válidas de Apple Pass Type ID / Google Wallet antes de emitir pases en producción. Internamente,resolvePassCreationTemplateIdresuelvetemplateIda su revisión basePRODUCTION/PUBLISHEDy rechaza plantillasDELETING/DELETED(BadRequestException/NotFoundException).
Referencia de la API de emisión programática
1. Crear un nuevo pase (POST /api/v1/passes)
Crea un nuevo registro de pase mediante request payload, respetando la cabecera opcional HTTP Idempotency-Key (idempotencyKey, máx. 128 caracteres según [A-Za-z0-9._:-]+, protegida con resumen SHA-256 de la solicitud) y los parámetros de consulta opcionales ?includePassSource=apple|google y ?pin=.
Parámetros de solicitud request payload
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
templateId | string (UUID) | Sí | UUID de plantilla (resuelto automáticamente a su fila base activa PRODUCTION/PUBLISHED). |
externalId | string | Opcional | Identificador de CRM/POS/pedido único por inquilino (máx. 255 caracteres; unicidad garantizada por pase activo no eliminado mediante @@unique([customerId, externalId])). |
serialNumber | string | Opcional | Número de serie único personalizado (generado automáticamente si se omite). |
barcodeValue | string | Opcional | Contenido explícito del código de barras. Por defecto usa la configuración de la plantilla o un valor autogenerado. |
barcodeAltText / barcodeAlternativeText | string | Opcional | Texto legible impreso debajo del código de barras para introducción manual por el cajero. |
attributes | Record<string, any> | Opcional | Diccionario clave-valor structured JSON coincidente con las claves de propiedades personalizadas de la plantilla. |
expirationDate | string | Opcional | Fecha/hora de vencimiento (<= 10 años en el futuro, interpretada en la zona horaria del espacio de trabajo). |
validityAsOfDate / validAsOfDate | string | Opcional | Fecha/hora de inicio de validez (issuedDate). |
enableDownloadUntil | string | Opcional | Límite temporal de descarga ("YYYY-MM-DD HH:mm" o marca temporal ISO). |
sharingProhibited | boolean | Opcional | Anula el ajuste anti-compartición de la plantilla (limitToOneActivePerPass). |
validationPlaces | string[] | Opcional | Lista personalizada de lugares de validación permitidos cuando está activado en la plantilla. |
skipDistributeOnCreate | boolean | Opcional | Suprime envíos automáticos tras la creación (correo/SMS) al emitir mediante API. |
Ejemplo de solicitud
POST /api/v1/passes?includePassSource=google Cabeceras: X-API-Key: <API_KEY> | Content-Type: application/json | Idempotency-Key: crm_usr_44910_v1
{
"templateId": "tmpl_01hxyz987654321",
"externalId": "crm_usr_44910",
"serialNumber": "PI-GOLD-2026-44910",
"barcodeValue": "PI-GOLD-2026-44910",
"barcodeAltText": "44910-GOLD",
"expirationDate": "2027-12-31 23:59",
"attributes": {
"firstName": "Marcus",
"lastName": "Vance",
"email": "marcus.vance@example.com",
"pointsBalance": 500,
"memberTier": "Gold"
}
}
Ejemplo de respuesta (API response envelope)
{
"success": true,
"data": {
"id": "pass_01j8k9m2n3p4q5r6",
"templateId": "tmpl_01hxyz987654321",
"customerId": "cust_ws_88219",
"externalId": "crm_usr_44910",
"bundleId": null,
"idempotencyKey": "crm_usr_44910_v1",
"serialNumber": "PI-GOLD-2026-44910",
"authenticationToken": "a9f4e2c81b7d60359e12c4b8f7a6d5e0",
"downloadCode": "dl_94f8a1",
"barcodeValue": "PI-GOLD-2026-44910",
"barcodeAltText": "44910-GOLD",
"status": "ACTIVE",
"lifecycleStatus": "ACTIVE",
"walletVoidStatus": "NONE",
"appleArtifactStatus": "NOT_GENERATED",
"googleArtifactStatus": "READY",
"downloadUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6",
"passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6",
"attributes": {
"firstName": "Marcus",
"lastName": "Vance",
"email": "marcus.vance@example.com",
"pointsBalance": 500,
"memberTier": "Gold"
},
"expirationDate": "2027-12-31T23:59:00.000Z",
"createdAt": "2026-11-15T15:04:12.000Z"
},
"description": "Pass created successfully",
"errors": [],
"statusCode": 201
}
Consejo — Agrupación multi-pase (
bundleId): Si crea pases complementarios para un hogar, tramo de vuelo o pedido VIP de un evento, asígnelos a unpass bundle(/api/v1/bundles/upsertoPassProject) para quePass.bundleIdagrupe hasta10pases en un enlace unificado.pkpasses/ multi-tarjeta.
2. Upsert idempotente y búsqueda por External ID (request payload)
En integraciones controladas por webhooks (Shopify, HubSpot o cajas POS), los reintentos de red pueden disparar la misma solicitud repetidamente. Passinstance proporciona endpoints dedicados de externalId restringidos a sus pases activos del inquilino (archivedAt: null):
-
POST /api/v1/passes/upsert-by-external-id: Crea un pase si ningún pase activo coincide conexternalId(action: "CREATED"), o combinaattributes,expirationDate,status(pass status) y unchangeMessageopcional (<=500caracteres) sobre el pase existente (action: "UPDATED"). -
PUT /api/v1/passes/by-external-id/:externalId: Ejecuta el upsert usando el parámetro:externalIdde la ruta (externalIden el cuerpo debe coincidir o puede omitirse). -
GET /api/v1/passes/by-external-id/:externalId: Obtiene directamente el pase activo porexternalIdsin necesidad de guardar UUID internos en sistemas externos.
Ejemplo de solicitud
POST /api/v1/passes/upsert-by-external-id Cabeceras: X-API-Key: <API_KEY> | Content-Type: application/json
{
"templateId": "tmpl_01hxyz987654321",
"externalId": "crm_usr_44910",
"status": "ACTIVE",
"changeMessage": "Tier updated to Platinum (%@ pts)",
"attributes": {
"pointsBalance": 750,
"memberTier": "Platinum"
}
}
Ejemplo de respuesta (200 OK)
{
"success": true,
"data": {
"pass": {
"id": "pass_01j8k9m2n3p4q5r6",
"externalId": "crm_usr_44910",
"serialNumber": "PI-GOLD-2026-44910",
"status": "ACTIVE",
"walletVoidStatus": "QUEUED"
},
"action": "UPDATED"
},
"description": "Pass updated successfully",
"errors": [],
"statusCode": 200
}
Para altas masivas por CSV o generación por lotes mediante arrays, consulte Creación masiva de pases y Operaciones por lotes.
