Descripción general
Antes de pasar una integración de Wallet a tráfico productivo, puede validar cada llamada API, regla de escaneo, bloqueo de idempotencia y firma webhook utilizando claves sandbox de Passinstance (pi_test_...), la consola de desarrolladores del Panel (/settings/workspace/developer/*) y nuestra Colección Bruno API preconfigurada (en docs/bruno/).
Importante: Pruebe siempre la emisión de pases (
.pkpassfirmado conbundleIdy enlace Save de Google Wallet) y sus actualizaciones dinámicas en al menos un dispositivo físico iOS (Apple Wallet) y un Android (Google Wallet) antes del lanzamiento. La vista previa web valida la disposición visual, pero la instalación real verifica latencia APNs y el renderizado dechangeMessageen pantalla bloqueada.
Flujo de verificación de integraciones y depuración
1. Claves Sandbox (pi_test_), herramientas del Panel y pases de prueba
-
Claves API Sandbox (
pi_test_<secret>): Generadas mediantePOST /api/v1/api-keyscon"environment": "test"(API_KEY_ENVIRONMENT_VALUES) en espacios sandbox. Ejercitan validaciones, firmabundleIdy colas push sin consumir cuota de producción. -
Diagnósticos del Panel para desarrolladores: Inspeccione registros de peticiones en vivo, colas de trabajos en segundo plano, salud del sistema y payloads API directamente en
/settings/workspace/developer/logs,/settings/workspace/developer/jobs,/settings/workspace/developer/system-healthy/settings/workspace/developer/query-helper. -
Endpoints de salud (sin prefijo
/api/v1): ConsulteGET /health,GET /health/liveness,GET /health/readiness,GET /health/detailedyGET /health/circuit-breakers.
2. Colección Bruno API
Passinstance mantiene una Colección Bruno API oficial en docs/bruno/ con solicitudes listas organizadas por dominio:
| Área Bruno | Flujos y aserciones cubiertos |
|---|---|
Auth & API Keys | Creación de claves (pi_test_), control de API_KEY_SCOPE_VALUES, rotación y telemetría de uso. |
Templates & Mechanics | CRUD de plantillas, hidratación de activos por nivel, tarjetas de sellos y valor almacenado. |
Passes & Distribution | Emisión individual (externalId, idempotencyKey), upsert-by-external-id, enlaces inteligentes (/d/:slug, /s/:token) y POST /api/v1/passes/export. |
Scanner Runtime | Nonces POST /api/v1/scans/prepare, motor de 14 reglas POST /api/v1/scans, /api/v1/scanner-keys/verify y sincronización offline. |
Billing | Vista previa de suscripción, cambios de plan, SetupIntents de Stripe y descarga de facturas PDF. |
Webhooks Inbox | Registro de webhooks Push (/api/v1/webhooks/subscriptions), verificación HMAC y consulta de cola Pull (/webhook-payload). |
Integrations | Endpoints OAuth para Zapier/Make (/api/v1/me, /api/v1/webhook-subscriptions) y hooks Shopware/Shopify. |
Analytics | Consultas multiserie (passes/overview, wallet-installations) y exportaciones CSV. |
3. Pruebas de idempotencia (x-idempotency-key, Idempotency-Key e idempotencyKey)
Los endpoints de escritura protegen frente a reintentos de red mediante contratos explícitos de idempotencia:
-
POST /api/v1/passes: IncluyaidempotencyKeyenrequest payload(oexternalIdconPOST /api/v1/passes/upsert-by-external-id). -
POST /api/v1/scans: Envíe la cabecerax-idempotency-key: test-scan-retry-001(Idempotency Engine); el reintento devuelve elrequest payloadidéntico, consultable enGET /api/v1/scans/operations/test-scan-retry-001. -
POST /api/v1/scans/pass/:passId/use: Envíe la cabeceraIdempotency-Key(coincidente con el campo opcionalidempotencyKey). -
POST /v1/pos/redeemyPOST /api/v1/reader/redeem: EnvíeidempotencyKeyen el cuerpo JSON (request payload/request payload).
4. Envolvente estándar de error
Cuando falla una validación o un límite de tasa, API Error Handler devuelve una respuesta estructurada con su requestId de correlación y un errorCode legible por máquina:
{
"success": false,
"error": "BAD_REQUEST",
"messageKey": "api.errors.invalidInput",
"message": "Invalid input provided: attribute 'memberName' is required by template",
"statusCode": 400,
"timestamp": "2026-11-16T10:20:00.000Z",
"path": "/api/v1/passes",
"requestId": "req_8f192b0e4c1a",
"code": "VALIDATION_ERROR",
"errorCode": "MISSING_REQUIRED_TEMPLATE_ATTRIBUTE",
"details": [
{
"field": "attributes.memberName",
"issue": "Required string attribute is missing"
}
]
}
5. Depuración de firmas webhook e interruptores de circuito
Si su endpoint receptor no recibe eventos o falla al verificar HMAC:
-
Revise la lectura del cuerpo sin procesar: Asegúrese de que su servidor web (
express.raw({ type: 'application/json' })en Express,await req.text()en Next.js oawait request.body()en FastAPI) lea el flujo exacto de bytes antes de parsear JSON. -
Compruebe el estado del circuit breaker: Recuerde que 10 respuestas consecutivas distintas de
2xxo tiempos agotados (10s) abren el disyuntor del endpoint (CIRCUIT_BREAKER_THRESHOLD = 10) durante una pausa de 30 minutos (CIRCUIT_BREAKER_COOLDOWN_MS). Corrija el receptor y ejecutePOST /api/v1/webhooks/subscriptions/:id/testpara restablecerlo.
Para fragmentos de código productivos en Node.js, Python, PHP y cURL, consulte Utilidades de integración.
