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

Resumen y endpoints

4 endpoints
Webhooks

Resumen de Webhooks y verificación de firmas

Verifique X-Webhook-Signature como HMAC-SHA256 sobre el cuerpo original de la solicitud con el secreto de su suscripción. Compare en tiempo constante y procese los eventos de forma idempotente.

Encabezado de firma
X-Webhook-Signature: sha256=9f8e7d6c5b4a3...
Encabezado de marca temporal
X-Webhook-Timestamp: 2026-08-21T20:30:00.000Z
Protección contra repeticiones

Compruebe que X-Webhook-Id coincide con eventId firmado, elimine eventos duplicados y valide la marca temporal firmada según su política contra repeticiones.

Eventos compatibles

PASS_CREATED, PASS_UPDATED, PASS_VOIDED, PASS_DOWNLOADED, APP_SCAN_CREATED, LOCATION_ENTERED, NOTIFICATION_SENT, DEVICE_REGISTERED, DEVICE_UNREGISTERED, TEMPLATE_PUBLISHED

Respuesta esperada

Devuelva HTTP 200 OK en menos de 5.000 ms para confirmar la recepción

Clave pública de verificación

GET /api/v1/webhooks/public-key devuelve la clave pública activa para verificar firmas

POSThttps://api.passinstance.com/api/v1/webhooks/subscriptionsClave API
Resumen y endpoints

Crear suscripción de webhook

Registre un endpoint HTTPS para recibir notificaciones en tiempo real firmadas con HMAC sobre emisión, actualización, escaneo y desinstalación de pases.

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 la URL HTTPS de destino y matriz de elementos tipos de eventos webhook.

Cuerpo de la solicitud2 obligatorio(s) • 5 opcional(es)
urlstring (HTTPS URL)
Obligatorio

URL de su servidor (debe comenzar por https://, máx. 2048 caracteres).

Ejemplo: https://your-server.com/webhooks/passinstance
eventsstring[] (enum)
Obligatorio

Valores tipos de eventos webhook: PASS_CREATED, PASS_UPDATED, PASS_VOIDED, PASS_DOWNLOADED, APP_SCAN_CREATED, LOCATION_ENTERED, NOTIFICATION_SENT, DEVICE_REGISTERED, DEVICE_UNREGISTERED, TEMPLATE_PUBLISHED.

Ejemplo: ["PASS_CREATED", "PASS_UPDATED", "APP_SCAN_CREATED"]

Códigos de estado de respuesta

DELETEhttps://api.passinstance.com/api/v1/webhooks/subscriptions/{id}Clave API
Resumen y endpoints

Cancelar suscripción a Webhook

Elimine una suscripción de webhook activa por su identificador y detenga el envío de eventos futuros a esa URL.

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 de la suscripción webhook que se desea eliminar.

Ejemplo: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Códigos de estado de respuesta

GEThttps://api.passinstance.com/api/v1/webhooks/subscriptionsClave API
Resumen y endpoints

Listar suscripciones de webhooks

Recupere todas las suscripciones de webhooks activas registradas para su espacio de trabajo.

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

Códigos de estado de respuesta

GEThttps://api.passinstance.com/api/v1/webhooks/public-keyPúblico
Resumen y endpoints

Obtener clave pública de firma Webhook

Obtenga la clave pública PEM activa de Passinstance para verificar criptográficamente las firmas de webhooks salientes.

Códigos de estado de respuesta

Webhooks basados en Pull

2 endpoints
Webhooks

Cómo funcionan los Pull Webhooks y sus limitaciones

Consuma eventos de pases y escaneos en tiempo real mediante webhooks Push firmados HMAC-SHA256 (con retroceso exponencial y disyuntores) o sondeo Pull Webhook para redes protegidas por firewall, además de flujos sin código.

Resiliencia Push Webhook

5 reintentos con retroceso exponencial con fluctuación; disyuntor abierto tras 10 fallos consecutivos

Sondeo Pull Webhook

GET /api/v1/webhook-payload y POST /api/v1/webhook-payload/acknowledge para redes privadas

Disparadores de flujo

PASS_CREATED, APP_SCAN_CREATED, PASS_INSTALLED, TIER_CHANGED, BALANCE_CHANGED, SCHEDULED

Acciones de flujo

SEND_PUSH_NOTIFICATION, UPDATE_PASS_FIELDS, SEND_EMAIL, WEBHOOK, MOVE_TO_SEGMENT

GEThttps://api.passinstance.com/api/v1/webhook-payloadClave API
Webhooks basados en Pull

Consultar eventos pull-webhook en cola

Recupere cargas útiles de eventos webhook pendientes mediante HTTPS GET saliente para redes privadas o restringidas por firewall sin abrir puertos entrantes.

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 consulta3 opcional(es)

Códigos de estado de respuesta

POSThttps://api.passinstance.com/api/v1/webhook-payload/acknowledgeClave API
Webhooks basados en Pull

Confirmar eventos pull-webhook

Confirme las cargas útiles pull-webhook procesadas hasta un ID específico para marcarlas como entregadas y eliminarlas de la cola.

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 el ID límite superior procesado (upTo).

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

Último ID de carga útil procesado; todos los eventos hasta este ID quedan confirmados.

Ejemplo: whp_55a4b3c2-1d0e-9f8a-7b6c-5d4e3f2a1b0c

Códigos de estado de respuesta

Eventos Webhook

4 guías
Eventos WebhookNotificación Webhook HTTP POST saliente

Eventos de plantilla (Template Events)

Notificaciones webhook HTTP POST enviadas cuando una plantilla de pase se crea, actualiza, publica o elimina.

Plantilla creada
POST
TEMPLATE_CREATED

Se emite cuando se crea una nueva plantilla de pase

Plantilla actualizada
POST
TEMPLATE_UPDATED

Se emite cuando se modifican campos, diseño o mecánicas de la plantilla

Plantilla publicada
POST
TEMPLATE_PUBLISHED

Se emite cuando un borrador se publica hacia los pases activos

Plantilla eliminada
POST
TEMPLATE_DELETED

Se emite cuando comienza la eliminación de la plantilla y revocación en wallet

Eventos WebhookNotificación Webhook HTTP POST saliente

Eventos de pase (Pass Events)

Notificaciones webhook HTTP POST que registran cada etapa del ciclo de vida de un pase desde su emisión hasta su eliminación del dispositivo.

Pase creado
POST
PASS_CREATED

Se emite inmediatamente cuando se crea un nuevo pase mediante la API REST o PassFlow

Pase actualizado
POST
PASS_UPDATED

Se emite cuando cambian los atributos, puntos de fidelidad, nivel o saldo del pase

Pase anulado
POST
PASS_VOIDED

Se emite cuando un pase se anula o desactiva en Apple Wallet y Google Wallet

Primera descarga del pase
POST
PASS_FIRST_DOWNLOAD

Se emite la primera vez que un cliente reclama o descarga el pase

Pase descargado
POST
PASS_DOWNLOADED

Se emite en cada descarga posterior del paquete o enlace de Google Wallet

Pase eliminado del dispositivo
POST
PASS_REMOVED

Se emite cuando el cliente elimina el pase de Apple Wallet o Google Wallet

Eventos WebhookNotificación Webhook HTTP POST saliente

Eventos de escaneo (Scan Events)

Notificaciones webhook HTTP POST emitidas en tiempo real cada vez que se escanea y valida un código de barras o credencial NFC.

Escaneo de pase creado
POST
APP_SCAN_CREATED

Se emite cuando POST /api/v1/scans o un escáner registra una lectura

Metadatos del resultado

Incluye passId, serialNumber, templateId, configId, decisión de validación y cambio de saldo

Garantía de entrega

Entrega HTTPS POST al menos una vez con encabezados X-Webhook-Id y X-Webhook-Signature

Compatibilidad con cola Pull

También disponible mediante GET /api/v1/webhook-payload para sistemas TPV tras firewall

Eventos WebhookNotificación Webhook HTTP POST saliente

Eventos de mensajes y referencia de estado (Message Events)

Notificaciones webhook HTTP POST y códigos de estado de entrega para notificaciones push, envíos por correo y SMS.

Mensaje enviado
POST
MESSAGE_SENTNOTIFICATION_SENT

Se emite al despachar un mensaje o actualización push

Entrega fallida
POST
MESSAGE_FAILED

Se emite cuando falla la entrega de un correo, SMS o notificación push

Referencia de estados de mensaje

QUEUED -> SENT -> DELIVERED (o FAILED / BOUNCED con código de diagnóstico)

Correlación idempotente

Correlacione eventId y passId en su receptor webhook para deduplicar reintentos