Usar la API de Passtastic | Passtastic Help
Passtastic
Explore
Product
Loyalty app
Pricing
Use Cases
Customer Stories
Help
No account yet? Sign up free

Usar la API de Passtastic

Qué te permite hacer la API

La API de Passtastic conecta tus propios sistemas — un POS personalizado, un CRM, una app interna — directamente con tu programa de fidelidad. Con ella puedes:

  • Inscribir clientes y emitir tarjetas de wallet desde tu propio flujo de registro
  • Añadir sellos o puntos, y consultar el saldo de un cliente, desde tu propia caja o back office
  • Recibir notificaciones en tiempo real con webhooks — en lugar de consultar constantemente, Passtastic envía un evento a tu sistema en el momento en que ocurre algo (un cliente se inscribe, se canjea una recompensa, y más)
  • Reutilizar los clientes que ya tienes — si alguien que tu sistema inscribe ya se registró a través de tu página de registro, Passtastic lo reconoce por correo electrónico o teléfono y añade tu referencia a la tarjeta que ya tiene, en lugar de emitir una segunda

Esto es para negocios que crean una integración personalizada. Si solo quieres una conexión ya lista, consulta Conecta Square POS o Sistemas POS e integraciones — sin necesidad de código.

El acceso a la API forma parte del pack Conecta tu punto de venta. El pack está activado durante tus 14 días de prueba gratis y se cobra por ubicación; mira Precios. Sin el pack, API y webhooks en Ajustes te dice cómo añadirlo.

Crea una clave de API

1. Abre Ajustes, luego API y webhooks (en Negocio).

2. En la pestaña Claves de API, haz clic en Crear clave de prueba para probarla sin riesgo, o en Crear clave en vivo cuando quieras conectar clientes reales.

3. Ponle un nombre a la clave para saber luego para qué es (p. ej. "CRM de producción").

4. Tu nueva clave se muestra una sola vez, en la ventana Tu nueva clave de API (para una clave de prueba: Tu nueva clave de prueba). Cópiala ahora — no podrás volver a verla. Haz clic en Copiar, o en Mostrar para revelarla primero.

Trata esta clave como una contraseña. Cualquiera que la tenga puede actuar en tu cuenta a través de la API.

5. Guarda la clave de forma segura en tu propio sistema (una variable de entorno, un gestor de secretos) y envíala como encabezado de autenticación en cada solicitud — el formato exacto está en la referencia técnica más abajo.

Solo los administradores pueden crear o revocar claves de API.

Pruébala primero con una clave de prueba

Las claves de prueba funcionan en cualquier plan, incluida tu prueba gratuita — sin necesidad de mejorar de plan. Los clientes de prueba reciben una tarjeta de wallet real, marcada como TEST, y se eliminan automáticamente a los 30 días — no tienes que borrar nada a mano.

Sigue el Quickstart de la documentación técnica con tu clave de prueba: te guía paso a paso para inscribir un cliente de prueba y añadir una tarjeta a tu propio teléfono, antes de que participe ningún cliente real.

Cuando tu integración funcione de principio a fin, vuelve a API y webhooks y haz clic en Crear clave en vivo para pasar a clientes reales. Las claves en vivo forman parte del pack Conecta tu punto de venta.

¿Perdiste una clave o crees que se filtró?

Las claves no se vuelven a mostrar después de crearlas. Si perdiste una, o crees que se ha expuesto, abre Claves de API y haz clic en Revocar — esto la detiene de inmediato — y luego crea una nueva y actualiza tu integración.

Configura un webhook

Los webhooks hacen que tu sistema reaccione en el momento en que algo pasa en Passtastic, sin que tengas que estar consultando la API todo el tiempo.

1. En la pestaña Webhooks, haz clic en Añadir endpoint.

2. Introduce la URL del endpoint — la dirección de tu propio sistema que recibirá el evento (p. ej. `https://tu-sistema.com/hook`).

3. En Eventos, elige cuáles quieres recibir:

  • Cliente inscrito
  • Saldo actualizado
  • Nivel cambiado
  • Recompensa canjeada
  • Tarjeta vencida
  • Tarjeta renovada

4. Guarda. Tu secreto de firma se muestra una sola vez, en la ventana Secreto de firma — cópialo ahora. Úsalo para comprobar que una solicitud de webhook realmente viene de Passtastic (la referencia técnica explica cómo verificar la firma).

Solo los administradores pueden crear o editar webhooks.

Cada endpoint de webhook muestra sus entregas recientes, para que puedas comprobar si una llamada tuvo éxito o falló, y reintentar una entrega fallida en cuanto tu sistema vuelva a estar disponible, sin esperar al siguiente evento.

Editar o desactivar un webhook

Abre el endpoint y haz clic en Editar para cambiar su URL o eventos, o pon su estado en Desactivado para pausar las entregas sin eliminarlo. Haz clic en Eliminar para quitarlo definitivamente.

Dónde encontrar la referencia técnica completa

Esta guía cubre la parte del panel — crear claves y webhooks. Para endpoints, formatos de solicitud/respuesta, encabezados de autenticación, códigos de error y ejemplos de código, consulta la documentación de la API completa, o ve directamente a la referencia de la API para el esquema de solicitud/respuesta de cada endpoint. También puedes acceder a ambas en cualquier momento desde los enlaces Leer la documentación de la API y Referencia de la API en la parte superior de la página API y webhooks — la referencia de la API se abre en una pestaña nueva.

Preguntas frecuentes

¿Necesito un POS para usar la API?
No. La API sirve para conectar tus propios sistemas — un POS personalizado, un CRM o una app. Si prefieres una conexión ya lista, consulta Conecta Square POS o Sistemas POS e integraciones.
¿Mi integración creará clientes duplicados?
No. Cuando tu sistema inscribe a alguien, Passtastic primero comprueba si ese cliente ya existe en tu cuenta — por la referencia que envía tu sistema, luego por correo electrónico, luego por teléfono. Si existe, vincula tu referencia a su tarjeta existente en lugar de emitir una segunda, así que sus sellos y puntos se quedan donde están. Si dos clientes comparten el mismo correo electrónico o teléfono, Passtastic no adivina entre ellos — devuelve un error que nombra a ambos, para que tu desarrollador pueda elegir el correcto.
¿Puede mi sistema saber cuándo vence la tarjeta de un cliente?
Sí. Si tu tarjeta tiene un periodo de validez (Validez de la tarjeta en Detalles de la tarjeta, en la pestaña Configuración del programa), marca Tarjeta vencida y Tarjeta renovada en tu webhook: tu sistema sabrá cuándo vence una tarjeta y cuándo se renueva, también cuando la renuevas en Passtastic. Tu desarrollador también puede consultar la fecha de fin de cada cliente y renovar una tarjeta desde tu sistema. Para probarlo antes de que venza una tarjeta real, una clave de prueba puede vencer al momento la tarjeta de un cliente de prueba. Los detalles están en la documentación de la API.
¿El acceso a la API está incluido en mi plan?
Sí, con el pack Conecta tu punto de venta: la API, los webhooks y las claves en vivo forman parte de él. El pack está activado durante tus 14 días de prueba gratis y se cobra por ubicación; mira Precios. Sin el pack, API y webhooks muestra API para desarrolladores con un botón Añadir por. Si quitas el pack, la API y los webhooks se pausan y no se borra nada. ¿Sigues en un plan anterior? Tu plan mantiene lo que incluía; mira Planes, límites y cómo mejorar tu suscripción. Las claves de prueba funcionan en todos los planes.
¿Dónde encuentro el ID de una tarjeta?
Abre la pestaña Compartir del programa. En Compartir en redes sociales o sitio web verás su enlace: la parte que va después de `/get-pass/` es el ID de la tarjeta. No copies el ID de la dirección de la página del programa, porque puede ser otro distinto. Tu desarrollador también puede listar todas tus tarjetas y sus ID a través de la API (`GET /api/v1/cards`).
Mi desarrollador recibe "Missing scope(s): cards:read". ¿Qué hago?
La clave se creó antes de que la API pudiera listar tarjetas. Crea una clave nueva (Claves de API → Crear clave), dásela a tu desarrollador y luego usa Revocar en la antigua.
¿Quién puede gestionar claves de API y webhooks?
Solo los administradores. Los editores y visualizadores no verán la opción de crear, editar o revocar una clave o webhook.
¿Puedo tener más de una clave de API?
Sí — crea una clave distinta por sistema o entorno (p. ej. una para tu CRM, otra para un entorno de pruebas) para poder revocar una sin afectar a las demás.
Un webhook dejó de recibir eventos, ¿qué pasó?
Abre el endpoint y revisa sus entregas recientes para ver el motivo del fallo (p. ej. tu servidor devolvió un error o hubo un tiempo de espera agotado). Corrige el problema en tu sistema y luego haz clic en Reintentar en la entrega fallida para reenviarla.