Cómo funciona / Desarrolladores

Conecta tu punto de venta

Tu caja identifica al cliente y manda cada venta; SimplePuntos aplica la regla del negocio, le manda el código para canjear y lleva su saldo. Con una llave de prueba lo programas sin tocar a los clientes reales.

Ver la referencia de la API Descargar OpenAPI

POST /api/v1/members/lookup
{ "identifier": "229 123 4567" }

200 OK
{ "id": "0199a1b2-…",
  "name": "María López",
  "balance": "120.50" }

POST /api/v1/members/0199a1b2-…/earnings
{ "amount": "850.00",
  "reference": "caja1-3001" }

201 Created
{ "points": "42.50",
  "balance": "163.00" }

Antes de empezar

Una llave de prueba

En el panel del negocio, en Configuración › Conexiones, crea una llave y marca «De prueba». Empieza con pts_test_, trabaja con una copia de las reglas del negocio, el código de canje siempre es 000000 y no manda WhatsApp ni correos.

JSON y una llave por caja

Todas las rutas cuelgan de https://www.simplepuntos.com/api/v1 y llevan el encabezado Authorization: Bearer con la llave. Usa una por caja para revocar una sin afectar a las demás.

Las reglas las da la API

Al arrancar, la caja lee GET /program: si es monedero o tarjeta de sellos, cuánto regresa y si el canje pide código. Mientras uses la llave de prueba responde "sandbox": true.

La venta, paso a paso

1
Tu punto de venta
Busca al cliente con lo que tecleó o escaneó el cajero. El dato viaja en el cuerpo de la petición, nunca en la dirección. La respuesta trae su id, su nombre y su saldo; si responde 404, ofrécele registrarse con POST /members.
```
curl -X POST https://www.simplepuntos.com/api/v1/members/lookup \
  -H "Authorization: Bearer $LLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "229 123 4567"
  }'
```
2
Tu punto de venta
Cobra y registra la venta con el monto y el folio del ticket. SimplePuntos aplica la regla del negocio y responde los puntos ganados y el saldo para imprimirlo. En una tarjeta de sellos, el premio que gane con esa visita llega en rewards con su código.
```
curl -X POST https://www.simplepuntos.com/api/v1/members/$CLIENTE/earnings \
  -H "Authorization: Bearer $LLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "850.00",
    "reference": "caja1-3001"
  }'
```

Tu cliente

Si quiere usar sus puntos, la caja pide el canje. Cuando el negocio pide código, al cliente le llega uno de 6 dígitos por WhatsApp o correo, se lo dicta al cajero y la caja lo confirma. Con la llave de prueba el código es 000000.

curl -X POST https://www.simplepuntos.com/api/v1/members/$CLIENTE/redemptions \
  -H "Authorization: Bearer $LLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "points": "100.00",
    "reference": "caja1-3002"
  }'

curl -X POST https://www.simplepuntos.com/api/v1/redemptions/$CANJE/confirm \
  -H "Authorization: Bearer $LLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "000000"
  }'

4
Tu punto de venta
Aplica el amount del canje confirmado como descuento en pesos. Si la venta no se completa, cancela el canje y los puntos regresan al cliente.
```
curl -X POST https://www.simplepuntos.com/api/v1/redemptions/$CANJE/cancel \
  -H "Authorization: Bearer $LLAVE"
```

Tu punto de venta

Si devuelven mercancía, revierte el movimiento de esa venta con el monto devuelto. Si la caja no guardó su id, lo encuentra por el folio.

curl https://www.simplepuntos.com/api/v1/entries?reference=caja1-3001 \
  -H "Authorization: Bearer $LLAVE"

curl -X POST https://www.simplepuntos.com/api/v1/entries/$MOVIMIENTO/reverse \
  -H "Authorization: Bearer $LLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "300.00",
    "reference": "caja1-dev-3001"
  }'

Si algo falla

Si la red se cae y no sabes si la venta llegó, repite la misma petición con la misma reference: responde el movimiento original con "replayed": true y no suma dos veces. Todo error trae un code para tu programa y un message en español para el cajero.

404 not_found: El cliente no está registrado. Ofrécele registrarse.
422 invalid_code: El código del canje no es el que le llegó al cliente; details.attempts_left dice cuántos intentos quedan.
422 invalid: Algún dato no pasa, por ejemplo un canje mayor que su saldo; details dice qué campo y por qué.
409 reference_taken: Ese folio ya se usó con otro monto u otro cliente; el mensaje dice cuándo.
429 rate_limited: Más de 300 peticiones por minuto con la misma llave.

Antes de salir a producción

Con la llave de prueba, recorre estos casos una vez y cambia de llave.

Cliente nuevo, venta, la misma venta reintentada, canje con 000000, un código equivocado y una devolución parcial.
Una llave normal por caja, guardada fuera del código, y GET /program respondiendo "sandbox": false.
Cada venta manda su folio en reference, con el prefijo de la sucursal y sin reiniciarse cada día.
La caja espera hasta 10 segundos y, si no hay respuesta, reintenta con la misma reference.
El código del cliente no se guarda ni se imprime, y el mensaje de cada error se le muestra al cajero tal cual.

Todo lo demás está en la referencia

Cada ruta con su ejemplo, para monedero y para tarjeta de sellos. El archivo OpenAPI se importa directo en Postman.

Ver la referencia de la API Descargar OpenAPI