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
Inicio rápido en 5 minObtener clave API

Cree su primer pase de Wallet en menos de 5 minutos

Emita, firme criptográficamente y distribuya pases de Apple Wallet (.pkpass) y Google Wallet con una simple llamada REST.

Estudio de pases en vivo — edita los campos para actualizar código y tarjeta
Entrega Apple Wallet (.pkpass) y Google Wallet
Vista previa
ARAcme Rewards
Puntos
450
Miembro
Jane Doe
Gold VIP
MEMBER-2024-8891
PKCS#7 · .pkpassHTTP 201
POST/api/v1/passes
curl --max-time 30 -X POST https://api.passinstance.com/api/v1/passes \
  -H "X-API-Key: $PASSINSTANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -d '{
    "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b",
    "serialNumber": "MEMBER-2024-8891",
    "externalId": "CRM-CUST-99201",
    "name": "Acme VIP Customer Pass",
    "attributes": {
      "guestName": "Jane Doe",
      "tier": "Gold VIP",
      "points": "450"
    },
    "storedValue": "50.00",
    "organizationName": "Acme Rewards",
    "backgroundColor": "#1b2d3c",
    "foregroundColor": "#ffffff",
    "labelColor": "#7db4f0",
    "barcode": {
      "value": "PI-8891-JD-VIP",
      "alternativeText": "8891-VIP"
    },
    "images": {
      "icon": "https://assets.passinstance.com/media/icon.png",
      "logo": "https://assets.passinstance.com/media/logo.png",
      "strip": "https://assets.passinstance.com/media/strip.png"
    },
    "relevantDate": "2026-08-25T18:00:00.000Z"
  }'
Resumen

Introducción — Descripción general de la API

La API de Passinstance permite a los desarrolladores emitir, distribuir, actualizar y validar dinámicamente pases digitales para Apple Wallet (iOS) y Google Wallet (Android). Todas las solicitudes API deben realizarse por HTTPS y devuelven un sobre de respuesta API estandarizado con códigos de estado legibles por máquina.

URL base de Producción
Activo
https://api.passinstance.com/api/v1
URL base de Sandbox Staging
https://staging-api.passinstance.com/api/v1
Formato de solicitud y respuestaapplication/json (UTF-8) con sobre de respuesta estándar
Zona horaria del servidorEurope/Berlin (marcas de tiempo ISO 8601)
Seguridad

Autenticación — Claves API y autorización

Use X-API-Key: <key> o Authorization: ApiKey <key> en los endpoints compatibles con claves API. Bearer se reserva para JWT de acceso. Mantenga las credenciales en el servidor.

Claves de producción (Live)
Authorization: ApiKey pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Claves de sandbox (Test)
Authorization: ApiKey pi_test_xxxxxxxxxxxxxxxxxxxxxxxx
Claves de escáner hardware
x-scanner-key: scan_key_77a8b9c0d1e2f3a4...
Invariante de seguridad:Solo servidor a servidor. Nunca incluya claves secretas en el frontend.
Inicio rápido

Inicio rápido — Primera solicitud API

Cree su primer pase funcional en menos de 5 minutos. Configure el encabezado de su clave API, llame a POST /api/v1/passes con un templateId válido y entregue la passAccessUrl devuelta al usuario final.

Paso 1: Configurar clave
export PASSINSTANCE_API_KEY="pi_test_..."
Paso 2: Emitir pase

POST /api/v1/passes con templateId y serialNumber

Paso 3: Obtener URL

Extraer response.data.passAccessUrl de la respuesta 201 Created

Paso 4: Distribuir

Enviar URL por SMS/correo; el usuario toca "Añadir a Apple/Google Wallet"

Recursos

Colección Postman — Importar y probar solicitudes API

Importe la especificación OpenAPI 3.0 de Passinstance (/api/docs/openapi.json) directamente en Postman, Insomnia o Bruno para probar endpoints, inspeccionar esquemas y generar clientes HTTP tipados.

Abrir especificación JSON OpenAPI 3.0
1. URL de especificación OpenAPI 3.0
https://passinstance.com/api/docs/openapi.json
2. Importar en Postman / Bruno

Haga clic en Import en Postman, Insomnia o Bruno y pegue /api/docs/openapi.json para cargar las rutas

3. Configurar entorno

Defina baseUrl = https://api.passinstance.com y PASSINSTANCE_API_KEY = pi_test_...

4. Verificar conectividad

Ejecute GET /api/v1/templates con X-API-Key: para validar su espacio de trabajo

Operaciones y FAQ

FAQ — Preguntas frecuentes y manejo de errores

Cada respuesta usa el sobre de respuesta API estándar. Corrija los errores 4xx antes de reintentar; espere ante respuestas 5xx y 429 usando el encabezado Retry-After.

200 OK / 201 CreatedÉxito
{
  "success": true,
  "data": { ... },
  "errors": [],
  "statusCode": 200
}
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

Guías de plataforma

Matriz Apple Wallet vs. Google Wallet

Passinstance firma automáticamente paquetes .pkpass para iOS y genera objetos JWT firmados para Google Wallet. Los recursos gráficos, códigos de barras y activadores se adaptan sin problemas a ambos sistemas.

Apple WalletiOS · .pkpass
Firma en Apple Wallet

Firma criptográfica PKCS#7 mediante certificado Pass Type ID de Apple

Google WalletAndroid · JWT
Emisor Google Wallet

Payload REST JWT de cuenta de servicio de Google Cloud

Paridad multiplataforma (una sola llamada REST)iOS + Android
Imágenes Hero / StripApple: 375×123 px (3:1) | Google: 1032×336 px (aprox. 3:1)
Códigos de barras universalesCódigo QR y PDF417 compatibles de forma nativa en ambas plataformas móviles
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 plantillas

7 endpoints
GEThttps://api.passinstance.com/api/v1/templatesClave API
Gestión de plantillas

Listar todas las plantillas

Recupere una lista paginada de plantillas de pases pertenecientes al contexto de cliente autenticado.

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

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

Obtener detalles de la plantilla

Recupere los detalles completos de una plantilla de pase, incluidos colores, configuración de código de barras, campos y reglas mecánicas.

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

Identificador único de la plantilla.

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

Códigos de estado de respuesta

GEThttps://api.passinstance.com/api/v1/templates/{id}/fieldsClave API
Gestión de plantillas

Obtener campos de plantilla

Recupere las definiciones de campos dinámicos y claves personalizadas que pueden completarse por pase para una plantilla determinada.

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 de la plantilla.

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

Códigos de estado de respuesta

POSThttps://api.passinstance.com/api/v1/templatesClave API
Gestión de plantillas

Crear una plantilla de pase

Diseñe y registre una nueva plantilla reutilizable con imagen de marca, tipo de código de barras, configuración NFC y campos de diseño.

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

Configuración de creación de plantilla acorde al esquema JSON OpenAPI.

Cuerpo de la solicitud6 obligatorio(s) • 4 opcional(es)
namestring
Obligatorio

Nombre visible de la plantilla.

Ejemplo: VIP Loyalty Card Template
descriptionstring
Obligatorio

Descripción detallada del propósito del pase y beneficios de nivel.

Ejemplo: Exclusive loyalty and rewards card for VIP customers
organizationNamestring
Obligatorio

Nombre de organización o marca impreso en el encabezado.

Ejemplo: Acme Rewards
kindstring (enum)
Obligatorio

storeCard, coupon, eventTicket, generic, boardingPass o membership.

Ejemplo: storeCard
statusstring (enum)
Obligatorio

DRAFT, PUBLISHED, ARCHIVED, DEPRECATED o UNDER_REVIEW.

Ejemplo: PUBLISHED
preferredStyleSchemestring (enum)
Obligatorio

DARK, posterGeneric, posterEventTicket, bannerEventTicket o semanticBoardingPass.

Ejemplo: DARK

Códigos de estado de respuesta

POSThttps://api.passinstance.com/api/v1/templates/{id}/publishClave API
Gestión de plantillas

Publicar borrador de plantilla

Promueva una revisión en borrador (rowKind: DRAFT) a PUBLISHED, marque changesToPush: true y encole actualizaciones en segundo plano APNs y Google Wallet para todos los pases activos.

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 plantilla a publicar.

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

Carga útil de solicitud que controla la publicación inmediata o programada y la propagación push a wallets.

Cuerpo de la solicitud4 opcional(es)

Códigos de estado de respuesta

POSThttps://api.passinstance.com/api/v1/templates/{id}/copyClave API
Gestión de plantillas

Duplicar plantilla

Clone una plantilla de pase existente con su diseño, colores, imágenes y mecánicas dentro del mismo 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
Parámetros de ruta1 obligatorio(s)
idstring (UUID)
Obligatorio

UUID de la plantilla de origen que se desea duplicar.

Ejemplo: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Optional name, description, and ISO 4217 currency override for the duplicated template.

Cuerpo de la solicitud3 opcional(es)

Códigos de estado de respuesta

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

Eliminar plantilla

Elimine una plantilla de pase y programe una tarea asíncrona para revocar y desactivar los pases asociados 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 de la plantilla que se va a eliminar.

Ejemplo: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Códigos de estado de respuesta

Notificaciones de plantilla

3 endpoints
POSThttps://api.passinstance.com/api/v1/push-notifications/templates/{id}/sendClave API
Notificaciones de plantilla

Difundir push a los pases de una plantilla

Difunda una notificación push inmediata en pantalla de bloqueo a todos los pases activos de Apple Wallet y Google Wallet de una plantilla.

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 plantilla cuyos dispositivos registrados recibirán la difusión.

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

Carga útil Carga útil de solicitud con pushNotificationText (máx. 85 caracteres) y texto de encabezado opcional.

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

Mensaje en pantalla de bloqueo enviado a pases activos (máx. 85 caracteres; admite variables).

Ejemplo: Flash Sale starts now! Show your VIP pass at checkout for 2x points.

Códigos de estado de respuesta

GEThttps://api.passinstance.com/api/v1/templates/{id}/notificationClave API
Notificaciones de plantilla

Listar notificaciones programadas

Liste todas las campañas de notificaciones push programadas y ejecutadas recientemente 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)
idstring (UUID)
Obligatorio

Template UUID.

Ejemplo: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Códigos de estado de respuesta

DELETEhttps://api.passinstance.com/api/v1/templates/notification/{notificationId}Clave API
Notificaciones de plantilla

Cancelar notificación programada

Cancele una notificación push de plantilla programada pendiente antes de que se envíe a los dispositivos registrados.

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)
notificationIdstring (UUID)
Obligatorio

UUID de la notificación programada devuelto al listar o programar notificaciones.

Ejemplo: f1e2d3c4-b5a6-4987-8765-43210fedcba9

Códigos de estado de respuesta

Integraciones de plantilla

2 endpoints
POSThttps://api.passinstance.com/api/v1/integration-connections/embed-widgetsClave API
Integraciones de plantilla

Crear integración embebida (iFrame)

Cree una configuración de widget iFrame integrable para una plantilla publicada y permita el registro de pases directamente en su sitio web.

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

Configuration for the embedded download widget including templateId and allowed host domains.

Cuerpo de la solicitud3 obligatorio(s) • 1 opcional(es)
namestring
Obligatorio

Nombre visible para la integración del widget embebido.

Ejemplo: Checkout Loyalty Embed Widget
templateIdstring (UUID)
Obligatorio

UUID de la plantilla de pase de destino.

Ejemplo: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
allowedDomainsstring[]
Obligatorio

Lista de orígenes (dominios) autorizados para incrustar el widget.

Ejemplo: ["shop.yourbrand.com", "app.yourbrand.com"]

Códigos de estado de respuesta

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

Gestión de paquetes

4 endpoints
POSThttps://api.passinstance.com/api/v1/bundles/upsertClave API
Gestión de paquetes

Crear o actualizar paquete de pases

Cree o actualice un paquete multipase (.pkpasses) que permite a los usuarios instalar varios pases relacionados en un solo toque.

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

Array of pass UUIDs (up to 10) and optional existing bundleId.

Cuerpo de la solicitud1 obligatorio(s) • 1 opcional(es)
passesstring[] (UUID)
Obligatorio

Lista de 1 a 10 UUID de pases para agrupar en el paquete.

Ejemplo: ["b1d972dc-eccf-4f87-ab21-25939d9213d8", "c2e083ed-fddf-4a98-bc32-36040e0324e9"]

Códigos de estado de respuesta

GEThttps://api.passinstance.com/api/v1/bundles/{id}/passesClave API
Gestión de paquetes

Listar pases en el paquete

Liste todos los pases individuales asociados actualmente a un paquete de pases, incluyendo su estado y números de serie.

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 paquete de pases.

Ejemplo: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b
Parámetros de consulta3 opcional(es)

Códigos de estado de respuesta

POSThttps://api.passinstance.com/api/v1/bundles/{id}/voidClave API
Gestión de paquetes

Anular pases del paquete

Anule o reactive todos los pases pertenecientes a un paquete de pases en una sola operación.

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 paquete de pases.

Ejemplo: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b

Confirmation flag and optional audit reason for voiding all passes in the bundle.

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

Debe establecerse en true para anular todos los pases del paquete.

Ejemplo: true

Códigos de estado de respuesta

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

Eliminar paquete de pases

Elimine un contenedor de paquete de pases de 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
Parámetros de ruta1 obligatorio(s)
idstring (UUID)
Obligatorio

UUID del paquete de pases que se desea eliminar.

Ejemplo: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b

Códigos de estado de respuesta

Seguridad

Resumen — Cómo funciona la validación de pases

Cada lectura de código de barras o NFC ejecuta una canalización determinista de 14 reglas (estado, vencimiento, franjas horarias, geofencing, mecánicas, límites de tasa, antirrepetición) con nonces criptográficos opcionales y sincronización sin conexión.

Nonce antirrepetición

POST /api/v1/scans/prepare emite un nonce criptográfico antirrepetición efímero vinculado al código de barras

Canalización de 14 reglas

PassStatus → Expiration → TimeWindow → Geofencing → Mechanics → RateLimit → AntiReplay

Sincronización offline

GET /api/v1/scans/offline-dataset entrega instantáneas paginadas por cursor para terminales sin conexión

Emparejamiento de clave escáner

POST /api/v1/scanner-keys/from-link intercambia un token de emparejamiento + PIN por una x-scanner-key

Configuración de escáner

3 endpoints
GEThttps://api.passinstance.com/api/v1/validation/configsClave API
Configuración de escáner

Listar configuraciones de escáner

Liste todos los perfiles de configuración de escáner (app móvil, escáner web, TPV) y sus permisos de plantilla en 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
Parámetros de consulta2 opcional(es)

Códigos de estado de respuesta

GEThttps://api.passinstance.com/api/v1/validation/configs/{id}Clave API
Configuración de escáner

Obtener configuración de escáner

Obtenga los detalles de una configuración de escáner específica, incluyendo plantillas permitidas, mensaje post-lectura y reglas.

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 configuración de escáner.

Ejemplo: 7a8b9c0d-1e2f-4a3b-8c9d-0e1f2a3b4c5d

Códigos de estado de respuesta

POSThttps://api.passinstance.com/api/v1/validation/configsClave API
Configuración de escáner

Crear configuración de escáner

Cree un nuevo perfil de configuración de escáner con plantillas asignadas, acción de lectura predeterminada y mensaje de confirmación.

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

Scanner configuration profile name, allowed template UUIDs, scan mode, and optional cooldown window.

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

Nombre descriptivo para la configuración del escáner.

Ejemplo: Main Entrance Gate Scanners
templateIdsstring[] (UUID)
Obligatorio

UUID de las plantillas autorizadas para validación bajo este perfil.

Ejemplo: ["8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b"]

Códigos de estado de respuesta

Operaciones de escaneo

4 endpoints
GEThttps://api.passinstance.com/api/v1/validation/scansClave API
Operaciones de escaneo

Listar registros de escaneo

Consulte el registro paginado de auditoría de escaneos de pases filtrando por plantilla, pase, escáner, decisión e intervalo de fechas.

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/scansClave de escáner
Operaciones de escaneo

Procesar escaneo de código de barras / NFC

Valide un código de barras óptico, QR o lectura NFC de Apple VAS / Google Smart Tap desde un terminal o escáner móvil a través del motor de validación de 14 reglas.

Encabezados2 obligatorio(s) • 2 opcional(es)
x-scanner-keystring
Obligatorio

Clave de configuración de escáner aprovisionada en el panel o mediante enlace de emparejamiento.

Ejemplo: scan_key_77a8b9c0d1e2f3a4b5c6d7e8
Content-Typestring
Obligatorio

Debe ser application/json.

Ejemplo: application/json

Carga útil Carga útil de solicitud con el código escaneado, nonce antirrepetición opcional, metadatos de canal/protocolo y contexto de operador.

Cuerpo de la solicitud1 obligatorio(s) • 8 opcional(es)
scannedBarcodeValuestring
Obligatorio

Cadena sin procesar leída desde QR, PDF417, CODE128, AZTEC o lectura NFC.

Ejemplo: PI-8891-JD-VIP

Códigos de estado de respuesta

POSThttps://api.passinstance.com/api/v1/scans/prepareClave de escáner
Operaciones de escaneo

Preparar nonce de escaneo antirrepetición

Emita un nonce criptográfico antirrepetición de corta duración vinculado a un código de barras antes de ejecutar POST /api/v1/scans.

Encabezados1 obligatorio(s)
x-scanner-keystring
Obligatorio

Clave de configuración de escáner aprovisionada en el panel o mediante enlace de emparejamiento.

Ejemplo: scan_key_77a8b9c0d1e2f3a4b5c6d7e8

Carga útil de solicitud con el valor del código escaneado al que vincular el nonce criptográfico.

Cuerpo de la solicitud1 obligatorio(s)
scannedBarcodeValuestring
Obligatorio

Cadena de código de barras o token NFC al que vincular el nonce antirrepetición.

Ejemplo: PI-8891-JD-VIP

Códigos de estado de respuesta

GEThttps://api.passinstance.com/api/v1/scans/offline-datasetClave de escáner
Operaciones de escaneo

Obtener conjunto de datos offline del escáner

Descargue un conjunto de instantáneas paginadas por cursor restringido a la x-scanner-key invocante para validación local sin conexión.

Encabezados1 obligatorio(s)
x-scanner-keystring
Obligatorio

Clave de configuración de escáner aprovisionada en el panel o mediante enlace de emparejamiento.

Ejemplo: scan_key_77a8b9c0d1e2f3a4b5c6d7e8
Parámetros de consulta3 opcional(es)

Códigos de estado de respuesta

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

Documentación integral de Plataforma y API

Centro de ayuda de Passinstance: Explore los 10 temas y 94 guías

Explore guías paso a paso, diagramas de arquitectura de flujos, esquemas de payloads JSON y recursos de solución de problemas en cada dominio.

Abrir el Centro de ayuda

Todo lo que necesitas para empezar a usar Passinstance con éxito.