Skip to content
Referencia de API REST y SDKs

Documentación para desarrolladores de Passinstance

Cree integraciones de alto volumen con Apple Wallet (.pkpass) y Google Wallet. Emita, actualice, escanee y envíe notificaciones en tiempo real mediante APIs REST de nivel de producción.

Obtener claves API
Entorno interactivo — los fragmentos se actualizan mientras escribes
Conceptos clave

Arquitectura y ciclo de vida del pase

La gestión de pases sigue un ciclo de vida de 6 etapas: 1. Plantilla (diseño base) → 2. Pase (registro firmado criptográficamente) → 3. Distribución (passAccessUrl segura) → 4. Registro en Wallet (el dispositivo se registra con APNs / Google Push) → 5. Actualizaciones en vivo (notificaciones en tiempo real) → 6. Telemetría de escaneo y canje (validación y webhooks).

1. PlantillaPOST /api/v1/templates

Diseño maestro, tipo de código de barras, colores de marca y campos de esquema

Conceptos clave

Mecánicas de pases y motor de fidelización

Asocie mecánicas con estado a plantillas en 8 soluciones listas para usar (Fidelización, Tarjetas de sellos, Cupones, Tarjetas regalo/prepago, Entradas, Membresías, Credenciales de empleado, Tarjetas VIP). Las reglas se ejecutan atómicamente al escanear o llamar a la API.

LOYALTY_PROGRAM

LOYALTY_PROGRAM y Niveles

Acumulación de puntos por escaneo (defaultChangeValue) con ascenso automático de nivel

STAMP_CARD

STAMP_CARD_ADD / DEDUCT

Controla posiciones de sellos (0..maximumValue) con onCap ('noop' | 'reset') y rewardClaimBehavior

PREPAID_CARD

Libro mayor PREPAID_CARD

Contabilidad de libro mayor prepago en unidades menores ISO 4217 con aplicación de disallowNegativeBalance

VALID_ONCE_PER_DAY

VALID_ONCE_PER_DAY y RENEW

Límites diarios por zona horaria y extensión automática de expirationDate al escanear

Gestión de pases

11 endpoints
POSThttps://api.passinstance.com/api/v1/passesClave API
Gestión de pases

Emitir un nuevo pase

Cree y emita un nuevo pase de Apple Wallet (.pkpass) y Google Wallet a partir de una plantilla con campos de cliente, código de barras y valores dinámicos.

Encabezados2 obligatorio(s) • 1 opcional(es)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Obligatorio

Debe ser application/json.

Ejemplo: application/json
Parámetros de consulta2 opcional(es)

Carga útil Carga útil de solicitud con ID de plantilla, número de serie único, valores del cliente y configuración opcional de código de barras.

Cuerpo de la solicitud1 obligatorio(s) • 15 opcional(es)
templateIdstring (UUID)
Obligatorio

ID de la plantilla para el pase.

Ejemplo: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Códigos de estado de respuesta

POSThttps://api.passinstance.com/api/v1/passes/upsert-by-external-idClave API
Gestión de pases

Crear o actualizar pase por ID externo (Upsert)

Cree o actualice de forma idempotente un pase indexado por (customerId, externalId) para una sincronización fluida con CRM, TPV y comercio electrónico.

Encabezados1 obligatorio(s)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_98a7b6c5d4e3f2a1

Carga útil de solicitud con templateId, externalId y atributos dinámicos del pase.

Cuerpo de la solicitud2 obligatorio(s) • 3 opcional(es)
templateIdstring (UUID)
Obligatorio

UUID de la plantilla de destino.

Ejemplo: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
externalIdstring
Obligatorio

Identificador externo CRM/TPV estable único dentro de su espacio de trabajo.

Ejemplo: CRM-CUST-99201

Códigos de estado de respuesta

POSThttps://api.passinstance.com/api/v1/batch-pass-operations/createClave API
Gestión de pases

Emisión masiva de pases

Emita múltiples pases wallet en una operación por lotes atómica con validación e informe de errores.

Encabezados1 obligatorio(s)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_98a7b6c5d4e3f2a1

Carga útil de solicitud con matriz de configuraciones de pases.

Cuerpo de la solicitud1 obligatorio(s)
passesarray of objects
Obligatorio

Matriz de elementos de pase con templateId, barcodeValue y additionalData.

Ejemplo: [ { "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b", "barcodeValue": "BULK-001", "additionalData": { "name": "Member #001" } }, { "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b", "barcodeValue": "BULK-002", "additionalData": { "name": "Member #002" } } ]

Códigos de estado de respuesta

GEThttps://api.passinstance.com/api/v1/passesClave API
Gestión de pases

Listar todos los pases

Recupere una lista paginada de pases del espacio de trabajo autenticado con filtros de búsqueda y estado.

Encabezados1 obligatorio(s)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_98a7b6c5d4e3f2a1
Parámetros de consulta13 opcional(es)

Códigos de estado de respuesta

GEThttps://api.passinstance.com/api/v1/passes/{id}Clave API
Gestión de pases

Recuperar un pase

Obtenga todos los detalles, estado de instalación y enlaces de descarga de un único pase mediante su ID único.

Encabezados1 obligatorio(s)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_98a7b6c5d4e3f2a1
Parámetros de ruta1 obligatorio(s)
idstring (UUID)
Obligatorio

Identificador UUID único del pase.

Ejemplo: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Códigos de estado de respuesta

PATCHhttps://api.passinstance.com/api/v1/passes/{id}Clave API
Gestión de pases

Actualizar pase y enviar push

Actualice campos dinámicos, colores o código de barras del pase y envíe automáticamente notificaciones push APNs y Google Wallet a los dispositivos instalados.

Encabezados1 obligatorio(s)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_98a7b6c5d4e3f2a1
Parámetros de ruta1 obligatorio(s)
idstring (UUID)
Obligatorio

UUID único del pase a actualizar.

Ejemplo: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Campos Carga útil de solicitud a modificar en el pase. Los dispositivos instalados recibirán actualizaciones instantáneas en segundo plano.

Cuerpo de la solicitud13 opcional(es)

Códigos de estado de respuesta

POSThttps://api.passinstance.com/api/v1/passes/voiding/{id}/voidClave API
Gestión de pases

Desactivar un pase

Marque un pase como anulado o reactivado en Apple Wallet y Google Wallet con propagación push instantánea.

Encabezados1 obligatorio(s)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_98a7b6c5d4e3f2a1
Parámetros de ruta1 obligatorio(s)
idUUID
Obligatorio

ID único de instancia del pase para anular o reactivar.

Ejemplo: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Carga útil Carga útil de solicitud que controla el estado anulado, motivo de auditoría y opciones de propagación wallet.

Cuerpo de la solicitud1 obligatorio(s) • 1 opcional(es)
voidedboolean
Obligatorio

Establecer en true para anular el pase o false para reactivarlo.

Ejemplo: true

Códigos de estado de respuesta

DELETEhttps://api.passinstance.com/api/v1/passes/{id}Clave API
Gestión de pases

Eliminar pase

Elimine permanentemente un pase de su espacio de trabajo y revoque cualquier instalación activa en Apple Wallet y Google Wallet.

Encabezados1 obligatorio(s)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_98a7b6c5d4e3f2a1
Parámetros de ruta1 obligatorio(s)
idstring (UUID)
Obligatorio

UUID único del pase que se va a eliminar.

Ejemplo: b1d972dc-eccf-4f87-ab21-25939d9213d8

Códigos de estado de respuesta

POSThttps://api.passinstance.com/api/v1/passes/{id}/useClave API
Gestión de pases

Aplicar acción de mecánica

Ejecute una operación atómica sobre la mecánica del pase: INCREMENT (tarjeta de sellos), DECREMENT, DEBIT (saldo prepago), CREDIT o VALIDATE (cupón de un solo uso).

Encabezados3 obligatorio(s)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Obligatorio

Debe ser application/json.

Ejemplo: application/json
Idempotency-Keystring
Obligatorio

UUID obligatorio para garantizar ejecución atómica y evitar deducciones duplicadas de saldo o sellos.

Ejemplo: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Parámetros de ruta1 obligatorio(s)
idstring (UUID)
Obligatorio

UUID único del pase sobre el que operar.

Ejemplo: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Carga útil de solicitud con la acción mecánica, monto decimal opcional, ID de operador y ubicación.

Cuerpo de la solicitud1 obligatorio(s) • 4 opcional(es)
actionstring (enum)
Obligatorio

INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE o NOOP.

Ejemplo: INCREMENT

Códigos de estado de respuesta

POSThttps://api.passinstance.com/api/v1/passes/{id}/adjust-valueClave API
Gestión de pases

Ajustar saldo del pase

Acredite (añada) o debite (deduzca) manualmente saldo o puntos de recompensa en un pase con registro de auditoría de transacciones.

Encabezados3 obligatorio(s)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Obligatorio

Debe ser application/json.

Ejemplo: application/json
Idempotency-Keystring
Obligatorio

UUID obligatorio para garantizar ajuste atómico y evitar abonos duplicados.

Ejemplo: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Parámetros de ruta1 obligatorio(s)
idUUID
Obligatorio

ID de la instancia del pase objetivo.

Ejemplo: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Carga útil de ajuste que especifica operación CREDIT o DEBIT, monto y motivo.

Cuerpo de la solicitud2 obligatorio(s) • 2 opcional(es)
actionstring
Obligatorio

Acción de transacción: 'CREDIT' para añadir saldo o 'DEBIT' para deducirlo.

Ejemplo: CREDIT
amountstring
Obligatorio

Monto numérico a acreditar o debitar como cadena.

Ejemplo: 25.00

Códigos de estado de respuesta

POSThttps://api.passinstance.com/api/v1/mechanics/redeemClave API
Gestión de pases

Canjear recompensa de mecánica

Canjee una recompensa de fidelización o tarjeta de sellos acumulada en un pase utilizando su mecánica configurada con protección de idempotencia.

Encabezados1 obligatorio(s) • 1 opcional(es)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx

Solicitud de canje que especifica passId, mechanicId y opcionalmente idempotencyKey.

Cuerpo de la solicitud2 obligatorio(s) • 3 opcional(es)
passIdstring (UUID)
Obligatorio

UUID del pase que canjea la recompensa.

Ejemplo: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
mechanicIdstring (UUID)
Obligatorio

UUID de la regla de mecánica de pase asociada a la plantilla.

Ejemplo: mech_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d

Códigos de estado de respuesta

Búsqueda y analíticas

4 endpoints
GEThttps://api.passinstance.com/api/v1/passes/searchClave API
Búsqueda y analíticas

Buscar pases

Realice una búsqueda de texto completo sobre los pases emitidos por número de serie, ID externo, correo electrónico, titular o atributos.

Encabezados1 obligatorio(s)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_98a7b6c5d4e3f2a1
Parámetros de consulta1 obligatorio(s)
querystring
Obligatorio

Cadena de búsqueda (hasta 500 caracteres).

Ejemplo: Jane Doe

Códigos de estado de respuesta

GEThttps://api.passinstance.com/api/v1/passes/statistics/{templateId}Clave API
Búsqueda y analíticas

Obtener estadísticas de pases

Obtenga estadísticas agregadas de emisión, activación, instalación en wallet y canjes para una plantilla de pase específica.

Encabezados1 obligatorio(s)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_98a7b6c5d4e3f2a1
Parámetros de ruta1 obligatorio(s)
templateIdstring (UUID)
Obligatorio

UUID de la plantilla de destino.

Ejemplo: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
Parámetros de consulta2 opcional(es)

Códigos de estado de respuesta

GEThttps://api.passinstance.com/api/v1/passes/{id}/historyClave API
Búsqueda y analíticas

Obtener historial de estado del pase

Recupere el historial cronológico de auditoría de cambios de estado, actualizaciones de saldo/puntos, escaneos y anulaciones de un pase.

Encabezados1 obligatorio(s)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_98a7b6c5d4e3f2a1
Parámetros de ruta1 obligatorio(s)
idstring (UUID)
Obligatorio

Pass UUID.

Ejemplo: b1d972dc-eccf-4f87-ab21-25939d9213d8
Parámetros de consulta1 opcional(es)

Códigos de estado de respuesta

POSThttps://api.passinstance.com/api/v1/passes/exportClave API
Búsqueda y analíticas

Exportar pases a CSV

Transmita una exportación CSV UTF-8 (text/csv; charset=utf-8) de las instancias de pases seleccionadas por ID.

Encabezados1 obligatorio(s)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_98a7b6c5d4e3f2a1

Carga útil de solicitud especificando de 1 a 2.000 UUID de pases y el formato de exportación.

Cuerpo de la solicitud2 obligatorio(s)
passIdsstring[] (UUID v4)
Obligatorio

Matriz de 1 a 2.000 UUID de pases a incluir en la exportación CSV.

Ejemplo: ["pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"]
formatstring (enum)
Obligatorio

Formato de salida de exportación ('csv').

Ejemplo: csv

Códigos de estado de respuesta

Entrega de pases

4 endpoints
GEThttps://api.passinstance.com/api/v1/passes/{id}/urisClave API
Entrega de pases

Obtener URLs de recursos del pase

Obtenga las URL directas de descarga y distribución de un pase, incluyendo la página PassFlow, .pkpass, JWT de Google Wallet y código QR.

Encabezados1 obligatorio(s)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_98a7b6c5d4e3f2a1
Parámetros de ruta1 obligatorio(s)
idstring (UUID)
Obligatorio

Pass UUID.

Ejemplo: b1d972dc-eccf-4f87-ab21-25939d9213d8

Códigos de estado de respuesta

GEThttps://api.passinstance.com/d/{slug}/infoPúblico
Entrega de pases

Obtener página de descarga personalizada

Resuelva la página pública personalizada de descarga de un pase por slug (GET /d/{slug}/info sin prefijo). Para consultas de gestión autenticadas utilice GET /api/v1/download-pages/slug/{slug}.

Parámetros de ruta1 obligatorio(s)
slugstring
Obligatorio

Slug personalizado único de la página de descarga alojada.

Ejemplo: acme-vip-2026
Parámetros de consulta2 opcional(es)

Códigos de estado de respuesta

POSThttps://api.passinstance.com/api/v1/passes/{id}/enabledownloadClave API
Entrega de pases

Habilitar descarga del pase

Reactive o desbloquee el enlace de descarga de un pase cuando la plantilla tenga activado el bloqueo de redescarga.

Encabezados1 obligatorio(s)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_98a7b6c5d4e3f2a1
Parámetros de ruta1 obligatorio(s)
idstring (UUID)
Obligatorio

UUID del pase cuya descarga se desea desbloquear.

Ejemplo: b1d972dc-eccf-4f87-ab21-25939d9213d8

Optional timestamp specifying how long re-download remains unlocked.

Cuerpo de la solicitud1 opcional(es)

Códigos de estado de respuesta

POSThttps://api.passinstance.com/api/v1/passes/{id}/send-emailClave API
Entrega de pases

Enviar pase por correo electrónico

Envíe un correo electrónico transaccional al titular con el enlace directo de instalación para Apple Wallet y Google Wallet.

Encabezados1 obligatorio(s)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_98a7b6c5d4e3f2a1
Parámetros de ruta1 obligatorio(s)
idstring (UUID)
Obligatorio

UUID del pase que se enviará por correo electrónico.

Ejemplo: b1d972dc-eccf-4f87-ab21-25939d9213d8

Recipient email address(es) and optional custom subject and message body.

Cuerpo de la solicitud4 opcional(es)

Códigos de estado de respuesta

Notificaciones push

2 endpoints
POSThttps://api.passinstance.com/api/v1/passes/{id}/notificationsClave API
Notificaciones push

Enviar notificación en pantalla de bloqueo

Envíe una notificación push inmediata a un pase instalado de Apple Wallet (.pkpass) o Google Wallet. Para envíos programados o personalización de encabezado, utilice POST /api/v1/push-notifications/passes/{id}.

Encabezados1 obligatorio(s)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_98a7b6c5d4e3f2a1
Parámetros de ruta1 obligatorio(s)
idUUID
Obligatorio

UUID único de instancia del pase que recibirá la notificación.

Ejemplo: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Carga útil de solicitud con el cuerpo del mensaje y título de encabezado opcional.

Cuerpo de la solicitud1 obligatorio(s) • 1 opcional(es)
messagestring
Obligatorio

Mensaje de texto que se mostrará en la pantalla de bloqueo del usuario.

Ejemplo: Your reward points have been updated! You now have 250 points.

Códigos de estado de respuesta

POSThttps://api.passinstance.com/api/v1/passes/sendpushnotificationsClave API
Notificaciones push

Enviar notificaciones push masivas

Envíe una notificación push de pantalla de bloqueo simultáneamente a una lista seleccionada de ID de pases vía APNs y Google Wallet.

Encabezados1 obligatorio(s)
X-API-Keystring
Obligatorio

Clave API secreta del espacio de trabajo (pi_live_... o pi_test_...). Alternativamente puede enviar Authorization: ApiKey <key>.

Ejemplo: pi_live_98a7b6c5d4e3f2a1

Target pass UUID array (up to 500 passes) and notification message text supporting {attribute} placeholders.

Cuerpo de la solicitud2 obligatorio(s)
listOfPassesstring[] (UUID)
Obligatorio

Lista de 1 a 500 UUID de pases.

Ejemplo: ["b1d972dc-eccf-4f87-ab21-25939d9213d8"]
pushNotificationTextstring
Obligatorio

Mensaje de notificación en pantalla de bloqueo (admite variables como {holderName}).

Ejemplo: Hi {holderName}, you unlocked a new reward!

Códigos de estado de respuesta