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

Utilidades de integración

Aprovecha tokens SDK, URLs Wallet dinámicas con parámetros, flujos de diseño con IA y esquemas OpenAPI.

En esta guía

Descripción General

Para acelerar la integración del backend en entornos Node.js/TypeScript, Python, PHP y shell —junto con las utilidades para desarrolladores del Panel en /settings/workspace/integrations/link-generator, /settings/workspace/developer/embed-sdk, /settings/workspace/developer/sdks, /settings/workspace/developer/query-helper y /settings/workspace/developer/qr-generator—, esta guía proporciona patrones de producción para inserciones o actualizaciones idempotentes de pases (POST /api/v1/passes/upsert-by-external-id), enlaces de descarga parametrizados (PARAMETERIZED_PASS_LINK / CREATE_PASS_URL), paginación basada en cursores y verificación de webhooks HMAC-SHA256 en tiempo constante.

Importante: Sincronice un registro de negocio mediante upsert por (templateId, externalId). El pase devuelto está en data.pass y el resultado en data.action (CREATED o UPDATED). Para POST /api/v1/passes, envíe una cabecera Idempotency-Key para que los reintentos reutilicen la misma solicitud de creación. El endpoint de upsert no procesa esa cabecera.

Flujo de Upsert Idempotente y Paginación por Cursores

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
PATRÓN DE UPSERT IDEMPOTENTE Y PAGINACIÓN POR CURSOR
ACTORES DEL SISTEMA
P1 Su Aplicación Backend
P2 API REST de Passinstance (/api/v1)
PASO 1 SOLICITUD / ACCIÓN POST/passes/upsert-by-external-id
›
{ templateId, externalId, attributes }
›
Coincide (templateId + externalId)
›
Crea si es nuevo O Actualiza y Envía Push
PASO 2 RESPUESTA 200 OK data: { pass, action }
PASO 3 SOLICITUD / ACCIÓN GET/scans/offline-dataset
›
?limit=250
PASO 4 RESPUESTA 200 OK { data: { passes, nextCursor: "c_1" } }
PASO 5 SOLICITUD / ACCIÓN GET/scans/offline-dataset
›
?limit=250&cursor=c_1&snapshotAt=...
PASO 6 RESPUESTA 200 OK { data: { passes, hasMore: false } }

Patrones de Código de Producción Multilenguaje

1. Node.js / TypeScript: Asistente de Upsert Idempotente de Pases

TYPESCRIPT
interface IUpsertPassPayload {
  templateId: string;
  externalId: string;
  attributes: Record<string, string | number | boolean>;
  expirationDate?: string;
}

export async function upsertWalletPass(payload: IUpsertPassPayload) {
  const response = await fetch('https://api.passinstance.com/api/v1/passes/upsert-by-external-id', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.PASSINSTANCE_API_KEY ?? '',
    },
    body: JSON.stringify(payload),
  });

  const body = await response.json();
  if (!response.ok || !body.success) {
    throw new Error(`Passinstance API error [${body.errorCode ?? response.status}]: ${body.message}`);
  }
  return body.data.pass as { id: string; serialNumber: string; externalId?: string; passAccessUrl: string };
}

2. Python: Upsert Idempotente y Verificador de Webhooks HMAC

PYTHON
import hmac
import hashlib
import os
import requests

API_BASE_URL = "https://api.passinstance.com/api/v1"
API_KEY = os.environ["PASSINSTANCE_API_KEY"]

def upsert_pass_by_external_id(template_id: str, external_id: str, attributes: dict) -> dict:
    response = requests.post(
        f"{API_BASE_URL}/passes/upsert-by-external-id",
        headers={
            "x-api-key": API_KEY,
            "Content-Type": "application/json",
        },
        json={
            "templateId": template_id,
            "externalId": external_id,
            "attributes": attributes,
        },
        timeout=10,
    )
    response.raise_for_status()
    return response.json()["data"]["pass"]

def verify_webhook_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    if not signature_header or not signature_header.startswith("sha256="):
        return False
    digest = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    expected = f"sha256={digest}"
    return hmac.compare_digest(signature_header, expected)

3. PHP: Emisión y Actualización de un Pase + Verificación de Webhooks

PHP
<?php
function upsertPassinstancePass(string $templateId, string $externalId, array $attributes): array {
    $payload = json_encode([
        'templateId' => $templateId,
        'externalId' => $externalId,
        'attributes' => $attributes,
    ], JSON_THROW_ON_ERROR);

    $ch = curl_init('https://api.passinstance.com/api/v1/passes/upsert-by-external-id');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $payload,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'x-api-key: ' . getenv('PASSINSTANCE_API_KEY'),
        ],
    ]);
    $raw = curl_exec($ch);
    curl_close($ch);
    return json_decode($raw, true, 512, JSON_THROW_ON_ERROR)['data']['pass'];
}

function verifyPassinstanceWebhook(string $rawBody, string $signatureHeader, string $secret): bool {
    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signatureHeader);
}

4. cURL: Referencia Rápida de CLI

BASH
curl -X POST "https://api.passinstance.com/api/v1/passes/upsert-by-external-id" \
  -H "Content-Type: application/json" \
  -H "x-api-key: pi_live_89a1f4c2e90b41d7a6c3e2f10984b2c1" \
  -d '{
    "templateId": "6f2c5130-2f2a-4f40-8c68-f7192c5b4f43",
    "externalId": "cust_9012",
    "attributes": {
      "memberName": "Clara Oswald",
      "points": 1250,
      "tier": "GOLD"
    }
  }'

Paginación de instantáneas del escáner sin conexión

GET /api/v1/scans/offline-dataset requiere x-scanner-key y devuelve la instantánea dentro de una respuesta con success, data y metadata. Mantenga el mismo snapshotAt en todas las páginas.

Parámetro / Campo de respuestaTipoDescripción
limitnumberPases por página (valor predeterminado 500, máximo 1000).
cursorstringUse data.nextCursor de la respuesta anterior; omítalo en la primera solicitud.
snapshotAtstring (ISO 8601)Reutilice data.snapshotAt de la primera respuesta como límite superior de la instantánea en las páginas siguientes.
data.passesArrayInstantáneas de pases dentro del ámbito de la configuración del escáner.
data.hasMorebooleanContinúe solicitando páginas mientras este valor sea true.
data.nextCursorstringÚselo como cursor cuando data.hasMore sea true; se omite en la última página.

Explore esquemas OpenAPI en vivo en /docs, realice pruebas con nuestra colección de Bruno en Pruebas y Depuración o diseñe plantillas de pases con IA en Cree su Primer Pase de Billetera.

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.