Skip to main content
Esta guía arma la integración más común: que tu POS sume puntos automáticamente cuando un cliente compra. Al final vas a tener el flujo completo, incluida la anulación de ventas.
Todos los ejemplos apuntan a QA, https://apidev.tiendadepuntos.com. Cambiá a https://api.tiendadepuntos.com recién cuando el flujo esté probado: las operaciones de puntos afectan saldos reales.

1. Verificá tu API key

Antes que nada, confirmá que la key funciona y traé los IDs de tus sucursales:
Respuesta:
Guardá el id que corresponda en la configuración de cada caja. Es un dato que no cambia, así que alcanza con traerlo una vez. Si ya lo tenés y solo querés verificar una sucursal, GET /external/branch/{id} devuelve una sola.

2. Sumá puntos en una venta

Esta es la llamada central de la integración:
El amount es el monto de la compra en pesos: acá, una venta de $55.000. Cuántos puntos son depende de la regla de conversión que tengas configurada en el panel, no de la API. Respuesta:
Si en el panel cargaste ítems de puntos, podés mandar sus ids en pointItems en vez del monto. Repetir un id suma una unidad más. Cuando viene pointItems, el amount del body se ignora y el monto de la operación es la suma de los montos de esos ítems.
En esa respuesta, points.selectedRewardType es "items". Un id que no existe en tu comercio, o que fue eliminado, responde 404 con PointsItem with id 12 not found.

Los campos que importan

external_id — la clave de idempotencia

Mandá el número de factura o el id del ticket. Si tu POS reintenta por un timeout de red, la API responde 409 en vez de acreditar los puntos de nuevo.Tratá el 409 como éxito: significa que la operación original se procesó bien. Y guardá este valor, porque es el único identificador con el que después podés cancelar.
Necesitás al menos uno de los dos: email o dni. Si el cliente no existe todavía, se crea automáticamente con los datos que mandes. Mandá también first_name y last_name para que el alta quede prolija.Si preferís que la operación falle en vez de dar de alta clientes desconocidos, agregá "ignoreCreateClient": true.
Array opcional de ids de ítems de puntos del catálogo del comercio. Los ids salen de GET /external/point-items, y también podés crear y editar ítems desde tu sistema: ver la sección Ítems de puntos en Administrar el programa.De 1 a 100 enteros positivos. [12, 12, 37] son dos unidades del ítem 12 y una del 37. Si los ítems no suman puntos, la API responde 400.
Identifica de qué sistema vino la operación, para los reportes del panel. Si integrás un sistema propio, usá external-integration.

Antes de cobrar: simulá la suma

Si querés mostrarle al cliente cuántos puntos va a sumar antes de cerrar la venta, POST /external/tags/add/preview hace el mismo cálculo que la suma real, con bonificaciones de nivel y reglas de puntos incluidas, sin acreditar nada.
Mandá uno solo de estos tres modos: amount, pointItems o initialPointsToGive. Si mandás ninguno o más de uno, la API responde 400. Hay tres diferencias con la suma real:
  • El cliente se identifica por clientId y tiene que existir. Previsualizar no da de alta a nadie. El clientId lo sacás de GET /external/clients/search.
  • pointItems lleva la cantidad explícita: [{ "id": 12, "quantity": 2 }] acá equivale a [12, 12] en POST /external/tags/add.
  • initialPointsToGive (puntos directos, sin conversión) solo existe en la simulación. La suma real no lo acepta.
La simulación no reserva nada. Si entre la simulación y la venta cambian las bonificaciones, el nivel del cliente o el catálogo de ítems, la suma real puede dar otro número. Mandá el mismo branch_id en las dos llamadas: hay bonificaciones que aplican solo a ciertas sucursales.
Un cliente suspendido responde 403, igual que en la suma real. Si el valor enviado no alcanza para otorgar ni un punto, la respuesta es 400.

3. Manejá la anulación de ventas

Si se anula la factura, revertí los puntos con el mismo external_id:
Un 404 acá significa que no hay ninguna operación activa con ese identificador: o nunca se creó, o ya se canceló antes.

4. Consultá el saldo de un cliente

Para mostrar los puntos disponibles en la pantalla de la caja:
El campo score de la respuesta es el saldo de puntos disponible. La búsqueda es por coincidencia exacta de email o de número de documento; si no encuentra a nadie devuelve 404. La respuesta también dice si el cliente ya completó su registro en la plataforma (registered). Si todavía no lo hizo, register_url trae el link para que lo complete, ya armado con el subdominio o el dominio propio de tu comercio. Podés mandárselo por WhatsApp o imprimirlo como QR en el ticket.
register_url funciona como una credencial: quien lo abra puede definir la contraseña de la cuenta del cliente y usar sus puntos. Mandáselo solo al cliente y no lo guardes en tu base ni lo registres en logs. Cuando el cliente completa el registro, el link deja de funcionar y el campo viene en null.

5. Entregá canjes en el mostrador

Cuando un cliente llega con el código de un premio, son dos llamadas: primero consultás qué pidió, después confirmás la entrega.
1

Consultá qué premio es

Mostrale al operador el producto y el nombre del cliente para que confirme.
2

Confirmá la entrega

Un 400 acá significa que el canje ya fue entregado o está vencido.
GET /external/purchase/code/{code} devuelve el canje sin el envelope { success, status, message, data }: los campos vienen en la raíz de la respuesta. POST /external/purchase/redeem/{code} sí usa el envelope.

6. Canjeá premios desde tu sistema

Además de entregar canjes que el cliente generó en la app, podés generarlos vos: mostrás el catálogo en tu POS y canjeás ahí mismo.
1

Traé el catálogo

Cada premio trae un array offers con el precio en puntos según el nivel del cliente:
El nivel del cliente lo sabés por GET /external/clients/search; los niveles del programa, por GET /external/levels.
2

Generá el canje

Descuenta los puntos y devuelve el canje con su code.
3

Entregá el premio

Con ese code, llamá a POST /external/purchase/redeem/{code} como en el paso anterior.
El canje nace en estado pending, no delivered. Si entregás el premio en el mismo momento, tenés que hacer igual la llamada a redeem: son dos pasos siempre.El motivo es que registrar una entrega requiere identificar al operador que la hizo, y una API key representa a un sistema, no a una persona.
Para canjear por dinero en vez de por un premio, POST /external/exchange/money con moneyAmount y clientId. Si el comercio tiene un mínimo configurado y no se alcanza, devuelve 409.
Los listados (/external/products, /external/levels, /external/point-items, /external/clients, /external/operators, /external/purchase) devuelven { data, meta, links } en la raíz, sin el envelope. Los premios están en data, no en items.

Y después

Con esto el POS ya suma puntos y entrega canjes. Si además querés administrar el programa desde tu sistema —dar de alta clientes, mantener el catálogo de premios, configurar los niveles o gestionar el personal— seguí con Administrar el programa.

Antes de pasar a producción

Mandás external_id en todas las sumas de puntos.
Tratás el 409 como éxito, no como error.
La API key está en una variable de entorno del servidor, no en el código del cliente.
Si la API no responde, la venta se cobra igual y la operación queda encolada.
Tenés reintentos con backoff para 429 y 5xx.
Cuando esto esté cubierto, cambiá la URL base a https://api.tiendadepuntos.com y probá con una venta real de monto chico. ¿Trabás en algún punto? Escribinos a hola@tiendadepuntos.com.