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

Visión general y autenticación de la API

URLs base (api.passinstance.com/api/v1), claves API frente a tokens de Escáner/SDK, cabeceras y límites.

En esta guía

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_... o pi_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/:token o /d/:slug) a los dispositivos de los usuarios finales.

URL base y documentación interactiva OpenAPI

Recurso / EntornoURLDescripción
URL base de la API de producciónhttps://api.passinstance.com/api/v1Emisión en vivo del espacio de trabajo, actualizaciones push de Wallet y escaneo en producción.
URL base de Staging / Sandboxhttps://staging-api.passinstance.com/api/v1Entorno aislado de pruebas previas a producción.
Swagger UI interactivo públicoGET https://api.passinstance.com/api/public/docsEspecificación OpenAPI 3.0 filtrada para desarrolladores externos en todos los entornos.
Swagger UI completo (no producción)GET /api/docsSwagger 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):

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
AUTENTICACIÓN DE API Y VERIFICACIÓN DE ALCANCES
ACTORES DEL SISTEMA
P1 Cliente / Servidor backend
P2 API Gateway y Auth Guards
P3 Controlador de destino
PASO 1a SOLICITUD / ACCIÓN Authorization: ApiKey
›
(API Key Authentication)
›
pi_live_...
›
Verificar hash, caducidad
›
y entorno (test vs live)
›
Comprobar API_KEY_SCOPE_VALUES
›
(passes, templates, scans,
PASO 1b SOLICITUD / ACCIÓN x-api-key: pi_live_...
›
webhooks, analytics, *)
PASO 1c SOLICITUD / ACCIÓN x-scanner-key: <key>
›
(Scanner Key Authentication)
›
Restringir a /api/v1/scans
›
y /api/v1/scanner-keys
PASO 2 SOLICITUD / ACCIÓN Aplicar aislamiento de
›
inquilino
PASO 3 RESPUESTA 200 OK API response (T)
›
<-------------------------------

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 credencialEncabezado HTTPPrefijo / Formato del tokenSuperficie permitida
API Key de producciónAuthorization: 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 sandboxAuthorization: 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.0Authorization: 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ánerx-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étodoEndpointPermiso requerido (api-key-permissions)Descripción
GET/api/v1/api-keysapi:keys-read o api:keys-manageLista todas las API Keys activas (y opcionalmente ?includeInactive=true) con valores key enmascarados.
GET/api/v1/api-keys/:idapi:keys-read o api:keys-manageObtiene los metadatos de una única API Key mediante su UUID.
POST/api/v1/api-keysapi:keys-manageCrea 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/:idapi:keys-manageActualiza name, scopes o expiresAt de la clave (request payload).
DELETE/api/v1/api-keys/:idapi:keys-manageElimina 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/regenerateapi:keys-manageGenera un nuevo token secreto manteniendo id, name y scopes de la clave.
POST/api/v1/api-keys/:id/activateapi:keys-manageReactiva de inmediato una API Key previamente desactivada.
POST/api/v1/api-keys/:id/deactivateapi:keys-manageDesactiva de forma lógica una API Key (marca temporal archivedAt) sin perder su configuración.
POST/api/v1/api-keys/:id/testapi:keys-manageVerifica la configuración de la clave y su estado de validez (API key verification result).
GET/api/v1/api-keys/:id/usageapi:keys-read o api:keys-manageDevuelve 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 por externalId y descargas .pkpass asociadas a bundleId).
  • '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)

JSON
{
  "name": "Shopify Checkout Issuance Worker",
  "environment": "live",
  "scopes": ["passes", "templates"],
  "expiresAt": "2027-11-16T00:00:00.000Z"
}

Respuesta (201 Created):

JSON
{
  "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.key se devuelve una sola vez en la respuesta 201 Created o /regenerate. Las llamadas posteriores a GET /api/v1/api-keys devuelven un prefijo enmascarado en key.

Explore el catálogo completo de endpoints en Referencia de la API y las especificaciones interactivas en /docs.

Documentación de producto y API relacionada

¿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.