API v1

Documentación de la API de Pokit

Integra tu punto de venta o backend con tus tarjetas de lealtad: emite tarjetas que tus clientes agregan a Apple Wallet y Google Wallet, ajusta puntos o sellos y consulta tus plantillas. Todas las respuestas son JSON y las fechas usan formato ISO 8601.

Autenticación

Genera una API key desde el panel en Ajustes → API keys. La key se muestra una sola vez; guárdala en un lugar seguro. Envíala en el header Authorization de cada solicitud. Cada key pertenece a un negocio y solo ve los datos de ese negocio.

Base URL + header de autenticación

curl "https://pokit.app/api/v1/templates" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxx"

Rate limits

Cada API key admite 120 solicitudes por minuto. Al superar el límite recibirás un 429 con rate_limit_exceeded; reintenta con backoff exponencial.

Errores

Los errores devuelven un objeto JSON con un código estable en error y, cuando ayuda, un detail legible.

Formato de error

{
  "error": "validation_error",
  "detail": "customerEmail: Invalid email address"
}

Código	error	Cuándo
401	invalid_api_key	API key faltante, malformada o revocada.
404	not_found	El recurso no existe o no pertenece a tu negocio.
409	card_revoked	La tarjeta está revocada y no acepta ajustes.
422	validation_error	Parámetros o body inválidos; detail explica el problema.
429	rate_limit_exceeded	Superaste las 120 solicitudes por minuto.

Plantillas

GET /templates

Listar plantillas

Devuelve las plantillas de tarjeta de tu negocio con el número de tarjetas emitidas por cada una.

Ejemplo · curl

curl "https://pokit.app/api/v1/templates" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxx"

Respuesta 200 · Lista de plantillas.

[
  {
    "id": "cmtpl1a2b0003pokittmpl1",
    "name": "Café Aroma — Puntos",
    "type": "POINTS",
    "active": true,
    "createdAt": "2026-05-12T10:00:00.000Z",
    "cards": 342
  }
]

Otros códigos

401 API key faltante, malformada o revocada.
429 Límite de 120 solicitudes por minuto excedido.

GET /templates/{id}

Detalle de plantilla

Devuelve una plantilla con su diseño, reglas y ubicaciones.

Parámetros

Nombre	En	Tipo	Descripción
id*	path	string	ID de la plantilla.

Ejemplo · curl

curl "https://pokit.app/api/v1/templates/{id}" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxx"

Respuesta 200 · Plantilla con ubicaciones.

{
  "id": "cmtpl1a2b0003pokittmpl1",
  "name": "Café Aroma — Puntos",
  "type": "POINTS",
  "description": "Acumula puntos por cada compra.",
  "backgroundColor": "#1a1a2e",
  "foregroundColor": "#ffffff",
  "labelColor": "#a0a0c0",
  "logoText": "Café Aroma",
  "stripImageUrl": null,
  "stampsTotal": 10,
  "pointsPerVisit": 10,
  "rewardText": "Café gratis a los 100 puntos",
  "barcodeFormat": "QR",
  "active": true,
  "createdAt": "2026-05-12T10:00:00.000Z",
  "updatedAt": "2026-06-01T08:00:00.000Z",
  "locations": [
    {
      "id": "cmloc7q1w0004pokitloc01",
      "templateId": "cmtpl1a2b0003pokittmpl1",
      "name": "Sucursal Centro",
      "latitude": 19.4326,
      "longitude": -99.1332,
      "relevantText": "¡Estás cerca de Café Aroma! Muestra tu tarjeta."
    }
  ],
  "cards": 342
}

Otros códigos

401 API key faltante, malformada o revocada.
404 El recurso no existe o no pertenece a tu negocio.
429 Límite de 120 solicitudes por minuto excedido.

Tarjetas

GET /cards

Listar tarjetas

Lista paginada de tarjetas del negocio. Filtra por plantilla, email, teléfono o serial. Para identificar a quien escanea su pass en caja, busca por `serial`: es el valor del código.

Parámetros

Nombre	En	Tipo	Descripción
templateId	query	string	Filtra por plantilla.
email	query	string	Filtra por email exacto del cliente.
phone	query	string	Filtra por teléfono exacto del cliente (10 a 15 dígitos).
serial	query	string	Filtra por serial: el valor que contiene el código QR o de barras del pass.
page	query	integer	Página (desde 1).
limit	query	integer	Resultados por página (máx. 100).

Ejemplo · curl

curl "https://pokit.app/api/v1/cards" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxx"

Respuesta 200 · Página de tarjetas.

{
  "data": [
    {
      "id": "cmcrd8f2k0001pokitcard1",
      "serial": "cmsrl4x9m0002pokitserl1",
      "templateId": "cmtpl1a2b0003pokittmpl1",
      "customerName": "María González",
      "customerEmail": "maria@ejemplo.com",
      "customerPhone": "5512345678",
      "data": {
        "tu_cumpleanos": "1990-05-14"
      },
      "points": 120,
      "stamps": 0,
      "status": "ACTIVE",
      "createdAt": "2026-07-01T15:30:00.000Z",
      "updatedAt": "2026-07-18T09:12:00.000Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 342
}

Otros códigos

401 API key faltante, malformada o revocada.
422 Parámetros o body inválidos.
429 Límite de 120 solicitudes por minuto excedido.

POST /cards

Emitir tarjeta

Crea una tarjeta para un cliente a partir de una plantilla de tu negocio. La respuesta incluye las URLs para compartir la tarjeta y agregarla a Apple Wallet o Google Wallet.

Ejemplo · curl

curl -X POST "https://pokit.app/api/v1/cards" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "templateId": "cmtpl1a2b0003pokittmpl1",
  "customerName": "María González",
  "customerEmail": "maria@ejemplo.com"
}'

Request body

{
  "templateId": "cmtpl1a2b0003pokittmpl1",
  "customerName": "María González",
  "customerEmail": "maria@ejemplo.com"
}

Respuesta 201 · Tarjeta creada.

{
  "id": "cmcrd8f2k0001pokitcard1",
  "serial": "cmsrl4x9m0002pokitserl1",
  "templateId": "cmtpl1a2b0003pokittmpl1",
  "customerName": "María González",
  "customerEmail": "maria@ejemplo.com",
  "customerPhone": "5512345678",
  "data": {
    "tu_cumpleanos": "1990-05-14"
  },
  "points": 0,
  "stamps": 0,
  "status": "ACTIVE",
  "createdAt": "2026-07-01T15:30:00.000Z",
  "updatedAt": "2026-07-18T09:12:00.000Z",
  "urls": {
    "public": "https://pokit.app/c/cmcrd8f2k0001pokitcard1",
    "appleWallet": "https://pokit.app/api/wallet/apple/cmcrd8f2k0001pokitcard1",
    "googleWallet": "https://pokit.app/api/wallet/google/cmcrd8f2k0001pokitcard1"
  }
}

Otros códigos

401 API key faltante, malformada o revocada.
404 La plantilla no existe o no pertenece a tu negocio.
422 Parámetros o body inválidos.
429 Límite de 120 solicitudes por minuto excedido.

GET /cards/{id}

Detalle de tarjeta

Devuelve una tarjeta con sus URLs públicas y de wallet.

Parámetros

Nombre	En	Tipo	Descripción
id*	path	string	ID de la tarjeta.

Ejemplo · curl

curl "https://pokit.app/api/v1/cards/{id}" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxx"

Respuesta 200 · Tarjeta.

{
  "id": "cmcrd8f2k0001pokitcard1",
  "serial": "cmsrl4x9m0002pokitserl1",
  "templateId": "cmtpl1a2b0003pokittmpl1",
  "customerName": "María González",
  "customerEmail": "maria@ejemplo.com",
  "customerPhone": "5512345678",
  "data": {
    "tu_cumpleanos": "1990-05-14"
  },
  "points": 120,
  "stamps": 0,
  "status": "ACTIVE",
  "createdAt": "2026-07-01T15:30:00.000Z",
  "updatedAt": "2026-07-18T09:12:00.000Z",
  "urls": {
    "public": "https://pokit.app/c/cmcrd8f2k0001pokitcard1",
    "appleWallet": "https://pokit.app/api/wallet/apple/cmcrd8f2k0001pokitcard1",
    "googleWallet": "https://pokit.app/api/wallet/google/cmcrd8f2k0001pokitcard1"
  }
}

Otros códigos

401 API key faltante, malformada o revocada.
404 El recurso no existe o no pertenece a tu negocio.
429 Límite de 120 solicitudes por minuto excedido.

DELETE /cards/{id}

Revocar tarjeta

Revoca una tarjeta (status `REVOKED`). Una tarjeta revocada ya no acepta ajustes de puntos o sellos.

Parámetros

Nombre	En	Tipo	Descripción
id*	path	string	ID de la tarjeta.

Ejemplo · curl

curl -X DELETE "https://pokit.app/api/v1/cards/{id}" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxx"

Respuesta 200 · Tarjeta revocada.

{
  "id": "cmcrd8f2k0001pokitcard1",
  "status": "REVOKED"
}

Otros códigos

401 API key faltante, malformada o revocada.
404 El recurso no existe o no pertenece a tu negocio.
429 Límite de 120 solicitudes por minuto excedido.

POST /cards/{id}/points

Ajustar puntos o sellos

Suma o resta puntos (o sellos) a una tarjeta. `delta` puede ser negativo; el saldo nunca baja de 0 y los sellos nunca pasan del total de la plantilla. Manda `reason` y `metadata` para dejar trazabilidad: quedan en el historial de la tarjeta. El pass del cliente se actualiza solo en su wallet, con una notificación del saldo nuevo.

Parámetros

Nombre	En	Tipo	Descripción
id*	path	string	ID de la tarjeta.

Ejemplo · curl

curl -X POST "https://pokit.app/api/v1/cards/{id}/points" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "delta": 10,
  "field": "points",
  "reason": "Compra en sucursal Centro",
  "metadata": {
    "ticket": "A-10482",
    "total": 349.5,
    "cajero": "Ana"
  }
}'

Request body

{
  "delta": 10,
  "field": "points",
  "reason": "Compra en sucursal Centro",
  "metadata": {
    "ticket": "A-10482",
    "total": 349.5,
    "cajero": "Ana"
  }
}

Respuesta 200 · Tarjeta con el saldo actualizado.

{
  "id": "cmcrd8f2k0001pokitcard1",
  "serial": "cmsrl4x9m0002pokitserl1",
  "templateId": "cmtpl1a2b0003pokittmpl1",
  "customerName": "María González",
  "customerEmail": "maria@ejemplo.com",
  "customerPhone": "5512345678",
  "data": {
    "tu_cumpleanos": "1990-05-14"
  },
  "points": 130,
  "stamps": 0,
  "status": "ACTIVE",
  "createdAt": "2026-07-01T15:30:00.000Z",
  "updatedAt": "2026-07-18T09:12:00.000Z"
}

Otros códigos

401 API key faltante, malformada o revocada.
404 El recurso no existe o no pertenece a tu negocio.
409 La tarjeta está revocada (`card_revoked`) o la tarjeta de sellos ya está completa (`stamps_full`).
422 Parámetros o body inválidos.
429 Límite de 120 solicitudes por minuto excedido.

POST /cards/{id}/redeem

Canjear recompensa

Canjea la recompensa de una tarjeta. En tarjetas de sellos consume la tarjeta completa y exige que esté llena; en tarjetas de puntos consume `amount`. El canje cuenta como visita para el vencimiento por inactividad.

Parámetros

Nombre	En	Tipo	Descripción
id*	path	string	ID de la tarjeta.

Ejemplo · curl

curl -X POST "https://pokit.app/api/v1/cards/{id}/redeem" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 500,
  "reason": "Canje: $100 de descuento",
  "metadata": {
    "ticket": "A-10511"
  }
}'

Request body

{
  "amount": 500,
  "reason": "Canje: $100 de descuento",
  "metadata": {
    "ticket": "A-10511"
  }
}

Respuesta 200 · Tarjeta con el saldo tras el canje.

{
  "id": "cmcrd8f2k0001pokitcard1",
  "serial": "cmsrl4x9m0002pokitserl1",
  "templateId": "cmtpl1a2b0003pokittmpl1",
  "customerName": "María González",
  "customerEmail": "maria@ejemplo.com",
  "customerPhone": "5512345678",
  "data": {
    "tu_cumpleanos": "1990-05-14"
  },
  "points": 20,
  "stamps": 0,
  "status": "ACTIVE",
  "createdAt": "2026-07-01T15:30:00.000Z",
  "updatedAt": "2026-07-18T09:12:00.000Z"
}

Otros códigos

401 API key faltante, malformada o revocada.
404 El recurso no existe o no pertenece a tu negocio.
409 El saldo no alcanza (`insufficient_balance`), la tarjeta está revocada (`card_revoked`) o es de membresía (`nothing_to_redeem`).
422 Parámetros o body inválidos.
429 Límite de 120 solicitudes por minuto excedido.

GET /cards/{id}/events

Historial de movimientos

Cada suma, canje, corrección o vencimiento de la tarjeta, del más reciente al más antiguo, con su motivo y metadata.

Parámetros

Nombre	En	Tipo	Descripción
id*	path	string	ID de la tarjeta.
limit	query	integer	Máximo de movimientos (1 a 200).

Ejemplo · curl

curl "https://pokit.app/api/v1/cards/{id}/events" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxx"

Respuesta 200 · Movimientos de la tarjeta.

{
  "data": [
    {
      "id": "cmevt7h3q0009pokitevt1",
      "field": "points",
      "kind": "earn",
      "delta": 10,
      "balanceAfter": 130,
      "reason": "Compra en sucursal Centro",
      "metadata": {
        "ticket": "A-10482"
      },
      "source": "api",
      "createdAt": "2026-07-18T09:12:00.000Z"
    }
  ]
}

Otros códigos

401 API key faltante, malformada o revocada.
404 El recurso no existe o no pertenece a tu negocio.
429 Límite de 120 solicitudes por minuto excedido.

Ubicaciones

GET /locations

Listar ubicaciones

Devuelve las ubicaciones geográficas de una plantilla (usadas para mostrar el pass en la pantalla de bloqueo cuando el cliente está cerca).

Parámetros

Nombre	En	Tipo	Descripción
templateId*	query	string	ID de la plantilla.

Ejemplo · curl

curl "https://pokit.app/api/v1/locations?templateId={templateId}" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxx"

Respuesta 200 · Ubicaciones de la plantilla.

[
  {
    "id": "cmloc7q1w0004pokitloc01",
    "templateId": "cmtpl1a2b0003pokittmpl1",
    "name": "Sucursal Centro",
    "latitude": 19.4326,
    "longitude": -99.1332,
    "relevantText": "¡Estás cerca de Café Aroma! Muestra tu tarjeta."
  }
]

Otros códigos

401 API key faltante, malformada o revocada.
404 El recurso no existe o no pertenece a tu negocio.
422 Parámetros o body inválidos.
429 Límite de 120 solicitudes por minuto excedido.