Skip to content
Guía del Centro de ayuda · API para desarrolladores
6 min de lecturaVerificado 2026-11-16

Referencia de la API

Explora todo el catálogo REST para Pases, Plantillas, Escáner, Entrega, Webhooks y Operaciones en lote.

En esta guía

Descripción general

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
P1 Integración externa
P2 Passinstance /api/v1/*
P3 Proveedores Wallet y BD
PASO 1 SOLICITUD / ACCIÓN POST/api/v1/passes
PASO 2 SOLICITUD / ACCIÓN Validar DTO y ámbito inquilino
PASO 3 SOLICITUD / ACCIÓN Firmar .pkpass (bundleId)
›
idempotencyKey
›
y generar JWT Google Wallet
PASO 4 RESPUESTA 201 Created
›
API response (request payload)
PASO 5 SOLICITUD / ACCIÓN PATCH/api/v1/passes/:id
PASO 6 SOLICITUD / ACCIÓN Confirmar actualización
PASO 7 RESPUESTA 200 OK
›
7. Encolar push APNs y Google

Catálogo de endpoints REST por dominio

1. Pases, upserts y operaciones por lotes

VerboRutaDescripción
POST/api/v1/passesEmite 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-idCrea o actualiza de forma idempotente un pase emparejado por (templateId, externalId) (request payload).
GET/api/v1/passesLista instancias de pases con paginación, filtrado por estado (pass status) y consultas de búsqueda.
GET/api/v1/passes/:idRecupera detalles completos, atributos dinámicos, externalId, serialNumber y estado de registro.
PATCH / PUT/api/v1/passes/:idActualiza campos dinámicos, nivel o fecha de caducidad y envía actualizaciones en vivo a los Wallets instalados.
POST/api/v1/passes/voiding/:id/voidAnula un pase (request payload + VoidingReason) y envía una actualización push silenciosa con voided: true.
DELETE/api/v1/passes/:idElimina de forma lógica un pase y revoca las instalaciones activas en Wallet.
POST/api/v1/passes/exportExporta registros de pases filtrados como un trabajo descargable en CSV UTF-8 o JSON.
POST/api/v1/batch-pass-operations/createEjecuta creación masiva síncrona o encolada mediante Batch Operations API (también /update, /upsert, /activate, /deactivate, /delete).
POST/api/v1/batch-processingEnvía un trabajo masivo asíncrono de gran volumen en CSV/JSON supervisado mediante Batch Processing API.

2. Plantillas y mecánicas

VerboRutaDescripción
GET/api/v1/templatesLista 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/:idDevuelve el esquema de la plantilla, la configuración visual y las mecánicas activas.
POST/api/v1/templates/:id/publishPublica cambios en borrador (request payload) y envía actualizaciones push por lotes (consulte antes GET .../publish-risk-check).
GET/api/v1/templates/:templateId/attributesLista las claves y tipos de campos dinámicos necesarios al emitir pases (admite OAuth templates:read).
POST/api/v1/mechanics/redeemCanjea una recompensa desbloqueada de fidelización o tarjeta de sellos (request payload: UUID passId, mechanicId).
GET/api/v1/mechanics/:mechanicId/passes/:passId/ledgerDevuelve 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

VerboRutaDescripción
POST/api/v1/scansEvalú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/prepareEmite un scan nonce criptográfico de corta duración para protección antirréplica.
GET/api/v1/scans/passConsulta de pase de solo lectura por ?barcode=... (o parámetro de ruta GET /api/v1/scans/pass/:barcodeValue).
POST/api/v1/scans/pass/:passId/useEjecuta directamente una acción request payload (INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE, NOOP, SET).
GET/api/v1/scans/result/:scanIdRecupera el registro de auditoría y ruleTrace de un escaneo completado.
GET/api/v1/scans/offline-datasetInstantánea de pases paginada por cursor (offline scan dataset) para escáneres portátiles sin conexión.
POST/v1/pos/redeemEndpoint POS sin prefijo que ejecuta comandos atómicos PosOperation (DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID, CUSTOM).
POST/api/v1/reader/redeemProcesa canjes de lectores NFC de hardware autenticados mediante X-Reader-Secret (POST /api/v1/reader/validate para validación de acceso).

4. Notificaciones push, webhooks y flujos de trabajo

VerboRutaDescripción
POST/api/v1/push-notifications/templates/:id/sendEnvía una notificación inmediata a todos los dispositivos registrados en una plantilla (request payload en /passes/:id/schedule).
POST/api/v1/push-notifications/segmentationEnvía notificaciones push localizadas a un segmento filtrado de pases (request payload).
POST/api/v1/push-notifications/batchEnvía notificaciones por lotes sobre listas de pases o cargas CSV (request payload).
GET / POST/api/v1/webhooksRecupera la vista general de webhooks o gestiona endpoints salientes HTTPS (/api/v1/webhooks/subscriptions).
GET/webhook-payloadAPI Pull sin prefijo (también admite GET /api/v3/webhook-payload) que consulta eventos pendientes de confirmación para receptores tras cortafuegos.
POST/webhook-payload/acknowledgeConfirmación sin prefijo ({ upTo, webhookId }, o POST /api/v3/webhook-payload/acknowledge).
GET / POST/api/v1/workflowsLista o crea flujos de trabajo automatizados dirigidos por eventos (Workflow Engine API, junto con /api/v1/automations).

5. Analítica, facturación y gobernanza de privacidad

VerboRutaDescripción
GET/api/v1/analyticsInforme de telemetría multiserie (passes, registrations, walletAppsShare; consulte /api/v1/analytics/passes/overview).
GET/api/v1/analytics/wallet-installationsMatriz de instalaciones por dispositivo y por pase de Apple Wallet frente a Google Wallet (request payload).
GET/api/v1/billing/subscriptionDevuelve el plan de suscripción activo, el ciclo de facturación y el estado de renovación.
GET/api/v1/billing/invoices/:id/downloadDescarga la factura fiscal en PDF (application/pdf).
POST/api/v1/customer/:customerId/privacy-settings/data-subject-exportGenera un archivo de datos personales conforme al RGPD para un titular del pase.

Sobre estándar API response (T) y códigos de estado

Sobre de éxito (200 OK / 201 Created)

JSON
{
  "success": true,
  "data": {
    "id": "pass_01hxyz8821",
    "templateId": "tmpl_vip_member",
    "serialNumber": "PI-VIP-8821",
    "externalId": "crm_cust_44910",
    "bundleId": "pass.com.passinstance.vip",
    "status": "ACTIVE",
    "passAccessUrl": "https://api.passinstance.com/s/vip-8821-x9a2"
  },
  "meta": {
    "requestId": "req_99481a2b7c",
    "timestamp": "2026-11-16T10:10:00.000Z"
  }
}

Códigos de estado HTTP estándar

Código de estadoSignificadoResolución
200 OK / 201 CreatedLa solicitud se completó de forma síncrona.Lea el resultado en data.
400 Bad RequestError de validación de DTO o restricción de dominio incumplida.Inspeccione errorCode, messageKey y el arreglo details.
401 UnauthorizedAPI Key o token Bearer ausente, caducado o no válido.Verifique el encabezado x-api-key o Authorization (y la correspondencia de entorno pi_test_ frente a pi_live_).
403 ForbiddenLa clave válida carece del alcance requerido (por ejemplo, falta 'passes') o acceso al inquilino.Compruebe los alcances asignados mediante GET /api/v1/api-keys.
404 Not FoundEl ID de recurso de destino no existe en el espacio de trabajo autenticado.Verifique el UUID / serialNumber / externalId y el entorno del espacio de trabajo.
409 ConflictexternalId duplicado, serialNumber repetido o colisión concurrente de idempotencia.Use /api/v1/passes/upsert-by-external-id o proporcione una idempotencyKey única.
429 Too Many RequestsSe superó la ráfaga de 1 segundo o la cuota de límite de tasa.Respete los encabezados de respuesta Retry-After y RateLimit-Reset.

Explore las definiciones de esquema completas en el Centro de documentación para desarrolladores y en Descripción general y autenticación de la API.

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.