Skip to content
Guía del Centro de ayuda · Emisión de pasesFase de incorporación 3
4 min de lecturaVerificado 2026-11-16

Crear pases individuales

Genera un pase único desde una plantilla publicada con datos del cliente y enlace/QR de prueba inmediato.

En esta guía

Recorridos visuales interactivos

Abrir en la guía de 6 fases

Inspecciona las pantallas reales del panel y las anotaciones ampliadas de esta guía.

Enfoque de interfaz ampliado
Elementos clave de la interfaz

Crear pase individual y Acciones rápidas (Zoom)

Haz clic en «+ Create pass» en el encabezado o en «Create single pass» dentro de Acciones rápidas para generar un pase de prueba.

Descripción general

La emisión de pases individuales permite a operadores e integraciones backend generar una tarjeta digital personalizada a partir de cualquier plantilla en estado PUBLISHED. Ya sea desde el panel lateral Crear pase del Dashboard o de forma programática mediante API REST, Passinstance asigna un serialNumber y un authenticationToken criptográficamente únicos, rellena todos los campos dinámicos {variable}, firma el archivo .pkpass de Apple y el JWT de Google Wallet y devuelve una URL inteligente inmediata de distribución (passAccessUrl).

Acciones rápidas de plantilla para crear un pase individual
Acciones rápidas de plantilla para crear un pase individual

Arquitectura del sistema: emisión de pase individual y upsert idempotente

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
EMISIÓN DE PASE INDIVIDUAL Y UPSERT IDEMPOTENTE
ETAPA 01 PANEL LATERAL / CRM / BACKEND DE PUNTO DE VENTA
Emisión estándar: POST/api/v1/passes (request payload)
Upsert idempotente: POST/api/v1/passes/upsert-by-external-id
ETAPA 02 SERVICIO DE EMISIÓN DE PASES (Pass Issuance Engine)
1
Verifica Template en PUBLISHED y ámbito del espacio (customerId)
2
Evalúa clave compuesta (customerId, externalId) para deduplicación
3
Genera serialNumber único y authenticationToken hex de 32 bytes
4
Valida structured JSON attributes frente al esquema de propiedades de la plantilla
5
Persiste fila Pass (status: ACTIVE) e inicia libro mayor pass mechanic
ETAPA 03 FIRMA DEL MONEDERO Y EMPAQUETADO DEL ENLACE INTELIGENTE
Genera enlace inteligente de descarga (passAccessUrl) y endpoint de QR
Prepara flujo .pkpass firmado de Apple y JWT Save de Google Wallet
Devuelve API response (request payload) con 201 Created o 200 OK

Emitir un pase individual manualmente en el panel

  1. 1
    Vaya a la página de resumen de su plantilla Publicada.
  2. 2
    Haga clic en Crear pase en la cabecera superior (o bajo Acciones rápidas).
  3. 3
    Rellene cada Propiedad personalizada obligatoria marcada en el formulario (por ejemplo: nombre del cliente, correo/teléfono si se requiere envío, sello inicial o externalId).
  4. 4
    Envíe el formulario para generar el pase al instante.
  5. 5
    Copie la URL de descarga única (passAccessUrl), muestre el código QR de instalación para escanearlo con un smartphone o lance un correo de entrega directamente desde el panel de detalles del pase.

Requisitos previos: Publique su plantilla (POST /api/v1/templates/:id/publish) con credenciales válidas de Apple Pass Type ID / Google Wallet antes de emitir pases en producción. Internamente, resolvePassCreationTemplateId resuelve templateId a su revisión base PRODUCTION/PUBLISHED y rechaza plantillas DELETING/DELETED (BadRequestException / NotFoundException).

Referencia de la API de emisión programática

1. Crear un nuevo pase (POST /api/v1/passes)

Crea un nuevo registro de pase mediante request payload, respetando la cabecera opcional HTTP Idempotency-Key (idempotencyKey, máx. 128 caracteres según [A-Za-z0-9._:-]+, protegida con resumen SHA-256 de la solicitud) y los parámetros de consulta opcionales ?includePassSource=apple|google y ?pin=.

Parámetros de solicitud request payload

CampoTipoObligatorioDescripción
templateIdstring (UUID)SíUUID de plantilla (resuelto automáticamente a su fila base activa PRODUCTION/PUBLISHED).
externalIdstringOpcionalIdentificador de CRM/POS/pedido único por inquilino (máx. 255 caracteres; unicidad garantizada por pase activo no eliminado mediante @@unique([customerId, externalId])).
serialNumberstringOpcionalNúmero de serie único personalizado (generado automáticamente si se omite).
barcodeValuestringOpcionalContenido explícito del código de barras. Por defecto usa la configuración de la plantilla o un valor autogenerado.
barcodeAltText / barcodeAlternativeTextstringOpcionalTexto legible impreso debajo del código de barras para introducción manual por el cajero.
attributesRecord<string, any>OpcionalDiccionario clave-valor structured JSON coincidente con las claves de propiedades personalizadas de la plantilla.
expirationDatestringOpcionalFecha/hora de vencimiento (<= 10 años en el futuro, interpretada en la zona horaria del espacio de trabajo).
validityAsOfDate / validAsOfDatestringOpcionalFecha/hora de inicio de validez (issuedDate).
enableDownloadUntilstringOpcionalLímite temporal de descarga ("YYYY-MM-DD HH:mm" o marca temporal ISO).
sharingProhibitedbooleanOpcionalAnula el ajuste anti-compartición de la plantilla (limitToOneActivePerPass).
validationPlacesstring[]OpcionalLista personalizada de lugares de validación permitidos cuando está activado en la plantilla.
skipDistributeOnCreatebooleanOpcionalSuprime envíos automáticos tras la creación (correo/SMS) al emitir mediante API.

Ejemplo de solicitud

POST /api/v1/passes?includePassSource=google Cabeceras: X-API-Key: <API_KEY> | Content-Type: application/json | Idempotency-Key: crm_usr_44910_v1

JSON
{
  "templateId": "tmpl_01hxyz987654321",
  "externalId": "crm_usr_44910",
  "serialNumber": "PI-GOLD-2026-44910",
  "barcodeValue": "PI-GOLD-2026-44910",
  "barcodeAltText": "44910-GOLD",
  "expirationDate": "2027-12-31 23:59",
  "attributes": {
    "firstName": "Marcus",
    "lastName": "Vance",
    "email": "marcus.vance@example.com",
    "pointsBalance": 500,
    "memberTier": "Gold"
  }
}

Ejemplo de respuesta (API response envelope)

JSON
{
  "success": true,
  "data": {
    "id": "pass_01j8k9m2n3p4q5r6",
    "templateId": "tmpl_01hxyz987654321",
    "customerId": "cust_ws_88219",
    "externalId": "crm_usr_44910",
    "bundleId": null,
    "idempotencyKey": "crm_usr_44910_v1",
    "serialNumber": "PI-GOLD-2026-44910",
    "authenticationToken": "a9f4e2c81b7d60359e12c4b8f7a6d5e0",
    "downloadCode": "dl_94f8a1",
    "barcodeValue": "PI-GOLD-2026-44910",
    "barcodeAltText": "44910-GOLD",
    "status": "ACTIVE",
    "lifecycleStatus": "ACTIVE",
    "walletVoidStatus": "NONE",
    "appleArtifactStatus": "NOT_GENERATED",
    "googleArtifactStatus": "READY",
    "downloadUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6",
    "passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6",
    "attributes": {
      "firstName": "Marcus",
      "lastName": "Vance",
      "email": "marcus.vance@example.com",
      "pointsBalance": 500,
      "memberTier": "Gold"
    },
    "expirationDate": "2027-12-31T23:59:00.000Z",
    "createdAt": "2026-11-15T15:04:12.000Z"
  },
  "description": "Pass created successfully",
  "errors": [],
  "statusCode": 201
}

Consejo — Agrupación multi-pase (bundleId): Si crea pases complementarios para un hogar, tramo de vuelo o pedido VIP de un evento, asígnelos a un pass bundle (/api/v1/bundles/upsert o PassProject) para que Pass.bundleId agrupe hasta 10 pases en un enlace unificado .pkpasses / multi-tarjeta.

2. Upsert idempotente y búsqueda por External ID (request payload)

En integraciones controladas por webhooks (Shopify, HubSpot o cajas POS), los reintentos de red pueden disparar la misma solicitud repetidamente. Passinstance proporciona endpoints dedicados de externalId restringidos a sus pases activos del inquilino (archivedAt: null):

  • POST /api/v1/passes/upsert-by-external-id: Crea un pase si ningún pase activo coincide con externalId (action: "CREATED"), o combina attributes, expirationDate, status (pass status) y un changeMessage opcional (<=500 caracteres) sobre el pase existente (action: "UPDATED").
  • PUT /api/v1/passes/by-external-id/:externalId: Ejecuta el upsert usando el parámetro :externalId de la ruta (externalId en el cuerpo debe coincidir o puede omitirse).
  • GET /api/v1/passes/by-external-id/:externalId: Obtiene directamente el pase activo por externalId sin necesidad de guardar UUID internos en sistemas externos.

Ejemplo de solicitud

POST /api/v1/passes/upsert-by-external-id Cabeceras: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "templateId": "tmpl_01hxyz987654321",
  "externalId": "crm_usr_44910",
  "status": "ACTIVE",
  "changeMessage": "Tier updated to Platinum (%@ pts)",
  "attributes": {
    "pointsBalance": 750,
    "memberTier": "Platinum"
  }
}

Ejemplo de respuesta (200 OK)

JSON
{
  "success": true,
  "data": {
    "pass": {
      "id": "pass_01j8k9m2n3p4q5r6",
      "externalId": "crm_usr_44910",
      "serialNumber": "PI-GOLD-2026-44910",
      "status": "ACTIVE",
      "walletVoidStatus": "QUEUED"
    },
    "action": "UPDATED"
  },
  "description": "Pass updated successfully",
  "errors": [],
  "statusCode": 200
}

Para altas masivas por CSV o generación por lotes mediante arrays, consulte Creación masiva de pases y Operaciones por lotes.

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