SimplePuntos

Desarrolladores / Referencia

Referencia de la API

Los ejemplos usan un negocio de muestra. Ya conectado, el panel de cada negocio muestra esta misma referencia con sus reglas.

Para empezar

La API habla JSON y todas sus rutas cuelgan de esta dirección. Si es la primera vez que conectas una caja, empieza por la guía paso a paso.

https://simplepuntos.com/api/v1

Cada petición lleva una llave de API en el encabezado Authorization. Las llaves se crean en Configuración › Conexiones; usa una por caja para poder revocar una sin afectar a las demás.

Authorization: Bearer pts_…

Para programar y probar, crea una llave de prueba (empieza con pts_test_). Trabaja con una copia de las reglas de Café Brisa: no ve a sus clientes reales, el código de canje siempre es 000000 y no manda WhatsApp ni correos. Cuando la caja esté lista, cámbiala por una llave normal.

  • Los puntos viajan como texto decimal con 2 decimales ("120.50"); los pesos siempre con dos ("60.25"). Al mandarlos puedes usar texto o número, sin más decimales de esos.
  • Las fechas van en ISO 8601 con zona horaria y los ids son UUID.
  • Hasta 300 peticiones por minuto por llave; arriba de eso responde 429.
  • Manda el cuerpo como JSON con Content-Type: application/json. Los errores siempre responden JSON, también un cuerpo mal formado o una ruta que no existe (mira errores).
  • Los ejemplos usan variables de la terminal: $LLAVE para tu llave y $CLIENTE, $CANJE y $MOVIMIENTO para los ids que te devuelve la API.
  • Si prefieres importarla en Postman o generar tu cliente, la misma API está descrita en OpenAPI.

Leer las reglas del programa

GET/program

Lo que tu caja necesita para calcular y mostrar antes de cobrar, tal como está hoy en la configuración de Café Brisa. Léelo al arrancar la caja en vez de copiar las reglas a mano: si el dueño las cambia, la caja se entera sola. programs dice qué usa Café Brisa (monedero, sellos o los dos); lo que no usa viene en null.

  • stamps_per_card: los sellos de una tarjeta; stamp_rewards: en qué sello se gana cada premio.
  • points_expire_after_months: los meses sin compras tras los que vence el saldo; null si no vence.
  • identifier: con qué se identifica al cliente (phone, email o text) y, si hay, el patrón que debe cumplir.
  • sandbox: true mientras la caja use una llave de prueba; muéstralo en pantalla para que nadie cobre con ella.
curl https://simplepuntos.com/api/v1/program \
  -H "Authorization: Bearer $LLAVE"
{
  "business": "Café Brisa",
  "sandbox": false,
  "programs": [
    "sellos"
  ],
  "points_label": "puntos",
  "points_precision": 2,
  "points_per_100": null,
  "point_value": null,
  "otp": null,
  "points_expire_after_months": null,
  "stamps_per_card": 10,
  "stamp_rewards": [
    {
      "stamps": 5,
      "reward": "Bebida al 50%"
    },
    {
      "stamps": 10,
      "reward": "Bebida gratis"
    }
  ],
  "identifier": {
    "kind": "phone",
    "label": "Celular",
    "pattern": null
  },
  "portal_url": "https://simplepuntos.com/c/tu-negocio"
}

Escanear la tarjeta

En Café Brisa cada cliente se identifica por su celular (teléfono celular). Es único por cliente: con él se busca, se acumula y se canjea.

  1. El lector de código de barras o QR funciona como un teclado: escribe el identificador y manda Enter.
  2. Deja el cursor en un campo de búsqueda; al recibir el Enter, el punto de venta llama POST /members/lookup con lo que leyó.
  3. La respuesta trae el id del cliente: con él van todas las demás rutas (/members/{id}/earnings, /members/{id}/redemptions…).
  4. Si responde 404, el cliente no está registrado: ofrécele registrarse con POST /members.

El celular viaja en el cuerpo de la petición y nunca en la dirección, para que no quede escrito en los registros de servidores y proxies. El teléfono se acepta tal como lo teclea el cajero: 229 123 4567 encuentra a +522291234567.

Clientes

Buscar un cliente

POST/members/lookup

Devuelve sus datos y su metadata, los sellos que lleva en su tarjeta (stamps).

curl -X POST https://simplepuntos.com/api/v1/members/lookup \
  -H "Authorization: Bearer $LLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "229 123 4567"
  }'
{
  "id": "0199a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
  "identifier": "+522291234567",
  "name": "María López",
  "email": "[email protected]",
  "phone": "+522291234567",
  "metadata": {
    "mascota": "Firulais",
    "sucursal": "Centro"
  },
  "balance": "0.00",
  "balance_amount": null,
  "stamps": 4,
  "created_at": "2026-09-14T11:32:08.120-06:00",
  "updated_at": "2026-10-01T18:05:44.310-06:00"
}

Registrar un cliente

POST/members

Responde 201 con el cliente nuevo. Si el identificador ya existía, actualiza el nombre, fusiona la metadata y responde 200; su teléfono y su correo se quedan como estaban. En la metadata guarda lo que te ayude a reconocerlo: su mascota, su sucursal, su número de cliente.

curl -X POST https://simplepuntos.com/api/v1/members \
  -H "Authorization: Bearer $LLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "+522291234567",
    "name": "María López",
    "email": "[email protected]",
    "metadata": {
      "mascota": "Firulais",
      "sucursal": "Centro"
    }
  }'

Consultar un cliente

GET/members/{id}

Lo mismo que la búsqueda, con el id que ya tienes; sirve para refrescar el saldo antes de cobrar.

curl https://simplepuntos.com/api/v1/members/$CLIENTE \
  -H "Authorization: Bearer $LLAVE"

Actualizar un cliente

PATCH/members/{id}

Cambia el nombre y la metadata, que se fusiona con la que ya tenía; una llave con null se borra. El identifier, el teléfono y el correo deciden a quién le llega el código de cada canje, así que solo los cambia una llave creada con «Puede cambiar el celular y el correo»; con otra, uno distinto responde 422 contact_locked y no guarda nada. Cada cambio queda marcado en la bitácora.

curl -X PATCH https://simplepuntos.com/api/v1/members/$CLIENTE \
  -H "Authorization: Bearer $LLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "María López Ruiz",
    "metadata": {
      "sucursal": null,
      "especie": "Perro"
    }
  }'

Fusionar dos clientes

POST/members/{id}/merge

Para cuando la misma persona quedó registrada dos veces. El de member_id le pasa a este su saldo, sus sellos y sus premios sin usar; su registro se cierra y su identificador queda libre. Con su id viejo la API sigue respondiendo con el que se quedó. Como decide de quién son los puntos, solo fusiona una llave creada con «Puede cambiar el celular y el correo».

curl -X POST https://simplepuntos.com/api/v1/members/$CLIENTE/merge \
  -H "Authorization: Bearer $LLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "member_id": "$OTRO_CLIENTE"
  }'

Movimientos de un cliente

GET/members/{id}/entries

Del más nuevo al más viejo. limit da el tamaño de página (25 por omisión, máximo 100); para la siguiente, manda en before el next_before de la respuesta. Cuando next_before viene vacío ya no hay más.

curl https://simplepuntos.com/api/v1/members/$CLIENTE/entries?limit=10 \
  -H "Authorization: Bearer $LLAVE"

Sellar visitas

Sellar una visita

POST/members/{id}/stamps

Suma un sello a la tarjeta del cliente, sin importar el monto. reference, description y metadata funcionan igual que al acumular. Si con ese sello gana un premio, llega en rewards para imprimirlo en el ticket. Si con él llena la tarjeta, card_completed viene en true: balance_after dice el sello que la llenó y balance los sellos que quedaron, 0, porque empieza una tarjeta nueva. Imprime balance. Por compatibilidad, /earnings también sella una visita en Café Brisa.

curl -X POST https://simplepuntos.com/api/v1/members/$CLIENTE/stamps \
  -H "Authorization: Bearer $LLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "barra-3001",
    "description": "Visita"
  }'
{
  "id": "0199a1b5-77e0-7c21-b0f4-5d6e7f8a9b0c",
  "member_id": "0199a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
  "member_identifier": "+522291234567",
  "program": "sellos",
  "kind": "earn",
  "points": "1",
  "balance_after": "5",
  "source": "api",
  "reference": "barra-3001",
  "description": "Visita",
  "metadata": {},
  "reversed_entry_id": null,
  "redemption_id": null,
  "created_at": "2026-10-02T13:41:09.502-06:00",
  "replayed": false,
  "rewards": [
    {
      "id": "0199a1d2-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "code": "K7QM3XPA",
      "title": "Bebida al 50%",
      "source": "stamps",
      "status": "available",
      "member_id": "0199a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
      "member_identifier": "+522291234567",
      "expires_on": null,
      "used_at": null,
      "used_by": null,
      "reference": null,
      "created_at": "2026-10-02T13:41:09.502-06:00"
    }
  ],
  "balance": "5",
  "card_completed": false
}

Los sellos no se ajustan: /adjustments responde 422 not_adjustable. Una visita sellada por error se corrige revirtiendo su movimiento (mira corregir una visita).

Consultar un movimiento

GET/entries/{id}

curl https://simplepuntos.com/api/v1/entries/$MOVIMIENTO \
  -H "Authorization: Bearer $LLAVE"

Corregir una visita

Si una visita se selló por error (otro cliente, dos sellos por una visita), revierte su movimiento: el cliente pierde ese sello. Si con él había ganado un premio que todavía no usa, el premio se cancela y llega en voided_rewards para que la caja lo anule; si ya lo usó, responde 422 not_reversible con su código y no revierte nada.

La visita que llenó la tarjeta se revierte mientras la tarjeta nueva siga vacía: vuelve a quedar a un sello de llenarse y su premio se cancela. Si la nueva ya lleva sellos, revierte primero esas visitas.

Buscar movimientos por referencia

GET/entries?reference={folio}

Si tu caja no guardó el id del movimiento, búscalo por el folio con el que lo mandó. Responde la lista como los movimientos de un cliente, con next_before para paginar; vacía si nadie usó esa referencia.

curl https://simplepuntos.com/api/v1/entries?reference=centro-3001 \
  -H "Authorization: Bearer $LLAVE"
{
  "entries": [
    {
      "id": "0199a1b5-77e0-7c21-b0f4-5d6e7f8a9b0c",
      "member_id": "0199a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
      "member_identifier": "+522291234567",
      "program": "sellos",
      "kind": "earn",
      "points": "1",
      "balance_after": "5",
      "source": "api",
      "reference": "centro-3001",
      "description": "Venta 3001",
      "metadata": {},
      "reversed_entry_id": null,
      "redemption_id": null,
      "created_at": "2026-10-02T13:41:09.502-06:00"
    }
  ],
  "next_before": null
}

Revertir un movimiento

POST/entries/{id}/reverse

curl -X POST https://simplepuntos.com/api/v1/entries/$MOVIMIENTO/reverse \
  -H "Authorization: Bearer $LLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "barra-dev-3001",
    "description": "Se selló al cliente equivocado"
  }'
{
  "id": "0199a1e4-2c3d-7e4f-8a5b-6c7d8e9f0a1b",
  "member_id": "0199a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
  "member_identifier": "+522291234567",
  "program": "sellos",
  "kind": "reversal",
  "points": "-1",
  "balance_after": "4",
  "source": "api",
  "reference": "barra-dev-3001",
  "description": "Se selló al cliente equivocado",
  "metadata": {},
  "reversed_entry_id": "0199a1b5-77e0-7c21-b0f4-5d6e7f8a9b0c",
  "redemption_id": null,
  "created_at": "2026-10-02T14:02:51.330-06:00",
  "replayed": false,
  "requested_points": "1",
  "reversed_points": "1",
  "voided_rewards": [
    {
      "id": "0199a1d2-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "code": "K7QM3XPA",
      "title": "Bebida al 50%",
      "source": "stamps",
      "status": "cancelled",
      "member_id": "0199a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
      "member_identifier": "+522291234567",
      "expires_on": null,
      "used_at": null,
      "used_by": null,
      "reference": null,
      "created_at": "2026-10-02T13:41:09.502-06:00"
    }
  ]
}

Premios y cupones

En Café Brisa cada visita sellada suma a una tarjeta de 10 sellos: en el sello 5 el cliente gana «Bebida al 50%» y en el sello 10 el cliente gana «Bebida gratis»; al llenarla empieza otra. Lo que gana con una visita llega en rewards de esa misma respuesta, para imprimirlo en el ticket. Cada premio de la tarjeta de sellos y cada cupón de una campaña trae un código de 8 caracteres, único en el negocio, que el cliente muestra o dicta en caja.

  1. Al escanear la tarjeta, GET /members/{id}/rewards da los premios y cupones que puede usar.
  2. Para usar uno, manda su código a POST /rewards/{código}/use y aplica el premio en la venta.

Premios y cupones disponibles

GET/members/{id}/rewards

Solo los que todavía se pueden usar, del más nuevo al más viejo.

curl https://simplepuntos.com/api/v1/members/$CLIENTE/rewards \
  -H "Authorization: Bearer $LLAVE"
{
  "member_id": "0199a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
  "member_identifier": "+522291234567",
  "rewards": [
    {
      "id": "0199a1d2-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "code": "K7QM3XPA",
      "title": "Bebida al 50%",
      "source": "stamps",
      "status": "available",
      "member_id": "0199a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
      "member_identifier": "+522291234567",
      "expires_on": null,
      "used_at": null,
      "used_by": null,
      "reference": null,
      "created_at": "2026-10-02T13:41:09.502-06:00"
    }
  ]
}

Usar un premio o cupón

POST/rewards/{código}/use

El código se acepta con o sin guion y en minúsculas: k7qm-3xpa encuentra a K7QM3XPA. Cada uno se usa una sola vez. Repetir con la misma reference responde 200 con replayed: true; si ya se había usado de otra forma responde 409 already_used, y si venció, 422 expired.

curl -X POST https://simplepuntos.com/api/v1/rewards/K7QM3XPA/use \
  -H "Authorization: Bearer $LLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "centro-3002"
  }'
{
  "id": "0199a1d2-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "code": "K7QM3XPA",
  "title": "Bebida al 50%",
  "source": "stamps",
  "status": "used",
  "member_id": "0199a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
  "member_identifier": "+522291234567",
  "expires_on": null,
  "used_at": "2026-10-02T13:52:40.118-06:00",
  "used_by": "Llave «Caja Centro»",
  "reference": "centro-3002",
  "created_at": "2026-10-02T13:41:09.502-06:00",
  "replayed": false
}
CódigoHTTPCuándo
not_found 404 No hay ningún premio o cupón con ese código en tu negocio.
already_used 409 El premio o cupón ya se usó, con otra referencia o sin ella, o se canceló al revertir la visita que lo dio.
expired 422 Pasó su fecha de vencimiento.

Reintentos seguros

Las redes fallan. Si una petición se cortó y no sabes si llegó, repítela igual, con la misma reference: si ya existía, la API responde lo mismo que la primera vez con replayed: true (200, o 202 si es un canje que sigue pendiente), sin acumular dos veces. Vale para sellos y reversos; manda siempre reference.

La referencia es única por programa y tipo de movimiento. Usa el folio con un prefijo por sucursal (centro-3001, norte-3001) y no lo reinicies: si tu caja reinicia folios por día o por terminal, agrégale la fecha o la caja (centro-20261002-3001). Si repites una referencia con otro movimiento u otro cliente, responde 409 reference_taken con cuándo y con cuánto se usó, y no mueve nada. Como cada visita suma un sello, un folio repetido para el mismo cliente siempre se toma como reintento.

Mensajes al cliente

Por omisión la API no le manda nada al cliente, salvo el código de un canje. Si quieres que reciba su comprobante, agrega notify: true al acumular, sellar o canjear (o al confirmar el canje) y, si quieres, notify_channel (whatsapp o email). Le llega algo como «Sumaste 42.50 puntos en Café Brisa. Tu saldo: …».

Cada mensaje cuenta contra los WhatsApp o correos de tu plan. Si no hay cupo, el cliente no tiene ese medio, es una llave de prueba o estás en Gratis, no sale y la respuesta lo dice en notification; el movimiento se registra igual. Un reintento con la misma reference no avisa dos veces.

Avisos a tu sistema

Si tu sistema también guarda a los clientes, registra su dirección en Configuración › Conexiones y te avisamos al momento de lo que pasa aquí, con el mismo JSON que responde la API: member.created, member.updated, member.merged (data trae el member que se quedó y el merged_member_id que se cerró), entry.created, redemption.confirmed, redemption.cancelled y reward.created.

{
  "id": "0199a1d4-…",
  "type": "entry.created",
  "created_at": "2026-10-05T12:30:00.000-06:00",
  "test": false,
  "data": {
    "id": "0199a1d3-…",
    "member_id": "0199a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
    "kind": "earn",
    "points": "42.50"
  }
}

Cada aviso es un POST con el encabezado X-Puntos-Signature: t=…,v1=…: v1 es el HMAC-SHA256 en hexadecimal de "{t}.{cuerpo}" con el secreto que te dimos al registrar la dirección. Compáralo con tiempo constante, rechaza si t tiene más de 5 minutos y responde 2xx rápido. Si falla, reintentamos durante unas horas; un aviso puede llegar dos veces, así que usa su id (también en X-Puntos-Delivery) para no procesarlo dos veces. Si a ti mismo te llega un cambio que hiciste por la API, ignóralo cuando los datos ya coinciden.

timestamp, firma = request.headers["X-Puntos-Signature"].scan(/t=(\d+),v1=(\h+)/).first
esperada = OpenSSL::HMAC.hexdigest("SHA256", SECRETO, "#{timestamp}.#{request.raw_post}")
valida = ActiveSupport::SecurityUtils.secure_compare(esperada, firma.to_s) && (Time.now.to_i - timestamp.to_i).abs < 300

Errores

Todo error responde JSON con la misma forma, también un cuerpo que no es JSON válido o una ruta que la API no tiene: un code estable para tu programa y un message en español para mostrarle al cajero.

{
  "error": {
    "code": "reference_taken",
    "message": "La referencia «centro-3001» ya se usó el 02/10/2026 a las 13:41 con 42.50 puntos"
  }
}
CódigoHTTPCuándo
bad_request 400 Falta un parámetro obligatorio, el cuerpo no es JSON válido, mandaste amount y points juntos o un reverso trae una llave que no conoce.
unauthorized 401 Falta la llave o fue revocada.
inactive 403 La cuenta del negocio está suspendida por la plataforma. Las llaves de prueba siguen funcionando.
pro_required 403 El negocio está en el plan Gratis y la API es del plan Pro, también con la llave de prueba.
not_found 404 El cliente, movimiento o canje no existe en tu negocio, la ruta no existe en la API o el cursor before no está en la lista.
reference_taken 409 La referencia ya se usó en ese tipo de movimiento con otros puntos u otro cliente; el mensaje dice cuándo y con cuánto.
invalid 422 Los datos tienen errores; details trae los mensajes por campo.
contact_locked 422 Intentaste cambiar el identificador, el teléfono o el correo con una llave que no tiene permiso; hazlo en el panel o con una llave que sí.
merge_not_allowed 403 Pediste una fusión con una llave que no puede cambiar el contacto.
not_mergeable 422 La fusión no procede: es el mismo cliente, el otro ya se fusionó con alguien más o tiene un canje pendiente.
not_adjustable 422 Sin monedero no hay ajustes; una visita se corrige revirtiéndola.
program_off 422 Pediste un programa que Café Brisa no tiene prendido: sellar sin tarjeta de sellos o acumular puntos sin monedero.
not_reversible 422 La visita ya se revirtió, su premio ya se usó o llenó una tarjeta que ya lleva sellos.
rate_limited 429 Más de 300 peticiones por minuto con la misma llave.
¿Dudas? Escríbenos