Skip to content
Guía del Centro de ayuda · Herramientas de desarrollo
3 min de lecturaVerificado 2026-11-16

Pruebas y depuración

Depura cargas API con registros de webhook, códigos de error API estandarizados y pases de prueba en plan gratuito.

En esta guía

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 (.pkpass firmado con bundleId y 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 de changeMessage en pantalla bloqueada.

Flujo de verificación de integraciones y depuración

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
PRUEBAS SANDBOX, IDEMPOTENCIA Y DEPURACIÓN WEBHOOK
ACTORES DEL SISTEMA
P1 Desarrollador / Bruno CLI
P2 API Passinstance (pi_test_...)
P3 Diagnóstico y Auditoría
PASO 1 SOLICITUD / ACCIÓN POST/api/v1/passes
›
Header: x-api-key: pi_test_...
›
Valida DTO contra Plantilla
›
Body: externalId,
›
Firma .pkpass (bundleId) y JWT
›
idempotencyKey
›
emite webhook pass_created
PASO 2 RESPUESTA 201 Created { requestId }
PASO 3 SOLICITUD / ACCIÓN Reintentar POST/api/v1/scans
›
Header: x-idempotency-key: k_01
PASO 4 RESPUESTA 200 OK (Acierto de caché idemp.)
PASO 5 SOLICITUD / ACCIÓN Consultar salud y registros
›
GET/health/detailed
›
/settings/workspace/developer/logs

1. Claves Sandbox (pi_test_), herramientas del Panel y pases de prueba

  • Claves API Sandbox (pi_test_<secret>): Generadas mediante POST /api/v1/api-keys con "environment": "test" (API_KEY_ENVIRONMENT_VALUES) en espacios sandbox. Ejercitan validaciones, firma bundleId y 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-health y /settings/workspace/developer/query-helper.
  • Endpoints de salud (sin prefijo /api/v1): Consulte GET /health, GET /health/liveness, GET /health/readiness, GET /health/detailed y GET /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 BrunoFlujos y aserciones cubiertos
Auth & API KeysCreación de claves (pi_test_), control de API_KEY_SCOPE_VALUES, rotación y telemetría de uso.
Templates & MechanicsCRUD de plantillas, hidratación de activos por nivel, tarjetas de sellos y valor almacenado.
Passes & DistributionEmisión individual (externalId, idempotencyKey), upsert-by-external-id, enlaces inteligentes (/d/:slug, /s/:token) y POST /api/v1/passes/export.
Scanner RuntimeNonces POST /api/v1/scans/prepare, motor de 14 reglas POST /api/v1/scans, /api/v1/scanner-keys/verify y sincronización offline.
BillingVista previa de suscripción, cambios de plan, SetupIntents de Stripe y descarga de facturas PDF.
Webhooks InboxRegistro de webhooks Push (/api/v1/webhooks/subscriptions), verificación HMAC y consulta de cola Pull (/webhook-payload).
IntegrationsEndpoints OAuth para Zapier/Make (/api/v1/me, /api/v1/webhook-subscriptions) y hooks Shopware/Shopify.
AnalyticsConsultas 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: Incluya idempotencyKey en request payload (o externalId con POST /api/v1/passes/upsert-by-external-id).
  • POST /api/v1/scans: Envíe la cabecera x-idempotency-key: test-scan-retry-001 (Idempotency Engine); el reintento devuelve el request payload idéntico, consultable en GET /api/v1/scans/operations/test-scan-retry-001.
  • POST /api/v1/scans/pass/:passId/use: Envíe la cabecera Idempotency-Key (coincidente con el campo opcional idempotencyKey).
  • POST /v1/pos/redeem y POST /api/v1/reader/redeem: Envíe idempotencyKey en 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:

JSON
{
  "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 o await 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 2xx o 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 ejecute POST /api/v1/webhooks/subscriptions/:id/test para restablecerlo.

Para fragmentos de código productivos en Node.js, Python, PHP y cURL, consulte Utilidades de integración.

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.