PillaMas Guía de integración

Conecta tu caja / TPV con PillaMas

Valida y canjea cupones, aplica ofertas y suma puntos y sellos directamente desde tu sistema de caja, con una sencilla API REST. Sigue estos pasos.

Puesta en marcha en 3 pasos

1

Genera tu clave de API

En tu panel, entra en Ajustes → Conectar tu caja / TPV y pulsa «Generar clave de API». La clave (empieza por pm_live_) se muestra una sola vez — cópiala y guárdala.

Trátala como una contraseña. Si se pierde, puedes regenerarla (la anterior deja de valer) o revocarla desde el mismo sitio.
2

Configúrala en tu TPV

Tu sistema de caja debe enviar la clave en la cabecera Authorization de cada petición. La clave identifica a tu comercio: no hace falta nada más.

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxxxxxxxxxx

Comprueba que funciona con una llamada de prueba:

curl https://pillamas.com/api/tpv/ping \
  -H "Authorization: Bearer pm_live_..."
3

Llama a la API desde la caja

Al leer el QR o código del cliente, primero consulta qué es y luego aplica la acción según el tipo (cupón, cliente o promoción).

curl -X POST https://pillamas.com/api/tpv/consultar \
  -H "Authorization: Bearer pm_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "codigo": "ABC123" }'

Endpoints disponibles

Base: https://pillamas.com/api/tpv

POST
/consultar
Identifica un código (cupón, cliente o promo) sin modificar nada. Devuelve su estado y, si es cliente, su saldo, sellos y promos disponibles.
POST
/cupon/canjear
Canjea un cupón (lo marca como usado e impide reutilizarlo). Responde valido o el motivo (ya_canjeado, caducado, anulado…).
POST
/venta
Registra una venta del cliente: suma puntos y avanza sus tarjetas de sellos. Envía clienteRef (su token/QR o teléfono/email) e importe.
POST
/promo
Aplica una promoción. Acepta clienteRef e importe opcionales según lo que exija la promo.
GET
/cliente?ref=…
Ficha del cliente: puntos, tarjetas de sellos, recompensas y promociones aplicables.
GET
/ping
Comprueba la clave y devuelve la configuración de puntos del comercio.

Ejemplos

Registrar una venta de 18,50 € (suma puntos y sellos):

curl -X POST https://pillamas.com/api/tpv/venta \
  -H "Authorization: Bearer pm_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "clienteRef": "+34600111222", "importe": 18.50 }'

→ { "resultado": "valido", "mensaje": "+18 puntos", "puntosSumados": 18, ... }

Aplicar una promoción a un cliente:

curl -X POST https://pillamas.com/api/tpv/promo \
  -H "Authorization: Bearer pm_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "codigo": "VERANO", "clienteRef": "+34600111222", "importe": 25 }'

Flujo típico en la caja

PasoQué hace la caja
1Lee el QR/código del cliente → POST /consultar
2 · cupónPOST /cupon/canjear y aplica el descuento en el ticket
2 · clienteAl cobrar, POST /venta con el importe (puntos + sellos)
2 · promoPOST /promo
3Muestra en pantalla el mensaje que devuelve la API
Códigos de respuesta. Cada operación devuelve un campo resultado: valido, ya_canjeado, caducado, anulado, no_valido, desconocido, no_aplicable o falta_cliente. Los errores llegan con código HTTP 400/401/404/409/429 y { "error": "mensaje" }.
Reintentos seguros (Idempotency-Key). En /venta y /promo, envía una cabecera Idempotency-Key única por operación (un UUID). Si la caja reintenta la misma petición tras un fallo de red, la operación se procesa una sola vez: no se vuelven a sumar puntos ni sellos. Usa una clave nueva para cada venta real.

Seguridad