Descripción general
La API REST de Passinstance permite la emisión de pases servidor a servidor, la gestión de plantillas, las mutaciones de saldo en tiempo real, la orquestación de webhooks y la extracción de analíticas. Todos los endpoints estándar están montados bajo la ruta base versionada https://api.passinstance.com/api/v1, aceptan y devuelven JSON en UTF-8 (Content-Type: application/json) y envuelven las respuestas estándar en un sobre determinista API response (T).
Importante: Nunca incruste claves API del espacio de trabajo (
pi_live_...opi_test_...) dentro de código JavaScript ejecutado en el navegador del cliente, binarios de aplicaciones móviles o repositorios Git públicos. Llame siempre a la API de Passinstance desde su servidor backend y entregue únicamente la URL de descarga inteligente resultante (/s/:tokeno/d/:slug) a los dispositivos de los usuarios finales.
URL base y documentación interactiva OpenAPI
| Recurso / Entorno | URL | Descripción |
|---|---|---|
| URL base de la API de producción | https://api.passinstance.com/api/v1 | Emisión en vivo del espacio de trabajo, actualizaciones push de Wallet y escaneo en producción. |
| URL base de Staging / Sandbox | https://staging-api.passinstance.com/api/v1 | Entorno aislado de pruebas previas a producción. |
| Swagger UI interactivo público | GET https://api.passinstance.com/api/public/docs | Especificación OpenAPI 3.0 filtrada para desarrolladores externos en todos los entornos. |
| Swagger UI completo (no producción) | GET /api/docs | Swagger UI interno completo generado en entornos no productivos (también integrado en /settings/workspace/developer en el Panel de control). |
Arquitectura de autenticación y reglas de entorno
Passinstance impone una separación estricta del radio de impacto entre tres familias de credenciales (API Key Authentication, OAuth 2.0 Authentication y Scanner Key Authentication):
Encabezados de autenticación admitidos y API_KEY_ENVIRONMENT_VALUES
request payload.environment utiliza API_KEY_ENVIRONMENT_VALUES ('test' | 'live'). Las claves de sandbox (pi_test_...) son válidas únicamente en espacios de trabajo sandbox, mientras que las claves en vivo (pi_live_...) son válidas únicamente en espacios de trabajo de producción:
| Tipo de credencial | Encabezado HTTP | Prefijo / Formato del token | Superficie permitida |
|---|---|---|---|
| API Key de producción | Authorization: ApiKey pi_live_... o x-api-key: pi_live_... | pi_live_<secret> (environment: "live") | Llamadas a la API del espacio de trabajo de producción que coincidan con los API_KEY_SCOPE_VALUES asignados. |
| API Key de sandbox | Authorization: ApiKey pi_test_... o x-api-key: pi_test_... | pi_test_<secret> (environment: "test") | Pruebas en espacio de trabajo sandbox y suites automatizadas de integración CI/CD. |
| Token Bearer OAuth 2.0 | Authorization: Bearer <jwt> | JWT firmado (OAuth 2.0 Authentication + Permission Scope Validation) | Plataformas iPaaS conectadas (Zapier, Make) mediante alcances granulares de OAuth (webhooks:read, webhooks:write, templates:read). |
| Clave de dispositivo escáner | x-scanner-key: <scanner-key> | <scanner-key> (Scanner Key Authentication) | Estrictamente aislada a /api/v1/scans, /api/v1/scanner-keys y rutas de escaneo de mecánicas. |
Gestión de API Keys (API Keys API e interfaz del Panel de control)
Gestione las credenciales visualmente en Ajustes del espacio de trabajo -> Desarrollador -> Credenciales de API (/settings/workspace/developer/api-credentials o /platform/api-keys) o de forma programática mediante /api/v1/api-keys:
| Método | Endpoint | Permiso requerido (api-key-permissions) | Descripción |
|---|---|---|---|
| GET | /api/v1/api-keys | api:keys-read o api:keys-manage | Lista todas las API Keys activas (y opcionalmente ?includeInactive=true) con valores key enmascarados. |
| GET | /api/v1/api-keys/:id | api:keys-read o api:keys-manage | Obtiene los metadatos de una única API Key mediante su UUID. |
| POST | /api/v1/api-keys | api:keys-manage | Crea una nueva API Key pi_live_ o pi_test_ (request payload); devuelve el campo key en texto claro una sola vez. |
PATCH / PUT | /api/v1/api-keys/:id | api:keys-manage | Actualiza name, scopes o expiresAt de la clave (request payload). |
| DELETE | /api/v1/api-keys/:id | api:keys-manage | Elimina de forma permanente una API Key y registra una entrada API_KEY_DELETED en el registro de auditoría. |
| POST | /api/v1/api-keys/:id/regenerate | api:keys-manage | Genera un nuevo token secreto manteniendo id, name y scopes de la clave. |
| POST | /api/v1/api-keys/:id/activate | api:keys-manage | Reactiva de inmediato una API Key previamente desactivada. |
| POST | /api/v1/api-keys/:id/deactivate | api:keys-manage | Desactiva de forma lógica una API Key (marca temporal archivedAt) sin perder su configuración. |
| POST | /api/v1/api-keys/:id/test | api:keys-manage | Verifica la configuración de la clave y su estado de validez (API key verification result). |
| GET | /api/v1/api-keys/:id/usage | api:keys-read o api:keys-manage | Devuelve telemetría de solicitudes, latencias promedio y desglose por código de estado HTTP (API key usage summary). |
Alcances disponibles para API Keys (API_KEY_SCOPE_VALUES)
Siga el principio de mínimo privilegio asignando únicamente los alcances necesarios a cada worker backend (por defecto ["*"] si se omite):
-
'passes'— Emitir, inspeccionar, actualizar, anular y buscar instancias de pases (incluidas búsquedas porexternalIdy descargas.pkpassasociadas abundleId). -
'templates'— Leer esquemas de plantillas, atributos personalizados y mecánicas. -
'scans'— Ejecutar validaciones, inspeccionar resultados de escaneo y activar mecánicas. -
'webhooks'— Gestionar suscripciones de webhooks y consultar colas de pull-webhooks. -
'analytics'— Consultar métricas de emisión de pases, registro de dispositivos y cuota por plataforma Wallet. -
'*'— Acceso administrativo completo en todos los dominios de la API de desarrolladores.
Creación de una API Key con alcances limitados (POST /api/v1/api-keys)
{
"name": "Shopify Checkout Issuance Worker",
"environment": "live",
"scopes": ["passes", "templates"],
"expiresAt": "2027-11-16T00:00:00.000Z"
}
Respuesta (201 Created):
{
"success": true,
"data": {
"id": "2c668b45-2b28-4c65-b17d-a6c7272e27ea",
"name": "Shopify Checkout Issuance Worker",
"key": "pi_live_89a1f4c2e90b41d7a6c3e2f10984b2c1",
"keyPrefix": "pi_live_",
"environment": "live",
"scopes": ["passes", "templates"],
"customerId": "89a12b34-56c7-4d89-9e01-23456789abcd",
"isActive": true,
"expiresAt": "2027-11-16T00:00:00.000Z",
"createdAt": "2026-11-16T10:00:00.000Z"
},
"description": "API key created successfully",
"errors": [],
"statusCode": 201
}
Importante: El secreto sin hash
data.keyse devuelve una sola vez en la respuesta201 Createdo/regenerate. Las llamadas posteriores aGET /api/v1/api-keysdevuelven un prefijo enmascarado enkey.
Explore el catálogo completo de endpoints en Referencia de la API y las especificaciones interactivas en /docs.
