Skip to main content
La API pública te permite operar el programa de fidelidad desde tus propios sistemas: sumar puntos cuando alguien compra, administrar tu padrón de clientes, mantener el catálogo de premios y los niveles, y entregar canjes en el mostrador. Es la misma API que usan nuestras integraciones con Dragonfish, Fudo, Centum, Contabilium y Dux. Si tu sistema no está en la lista de integraciones, esta es la vía para conectarlo.

​
URL base

Todos los endpoints públicos cuelgan de /external.

​
Qué podés hacer

Sumar puntos

Acreditar puntos por el monto de una compra, con el cliente identificado por email o documento.

Administrar clientes

Listar, dar de alta, editar y dar de baja clientes, con su saldo de puntos y su nivel.

Mantener el catálogo

Crear y editar premios con su precio en puntos por nivel, y controlar su stock.

Configurar niveles

Armar la escalera de niveles del programa y sus multiplicadores de puntos.

Canjear premios

Descontar puntos y generar el canje, por un premio del catálogo o por un monto en pesos.

Entregar canjes

Consultar qué premio pidió el cliente y marcarlo como entregado.

Gestionar operadores

Dar de alta el personal del comercio y asignarle sucursales y permisos.

​
El flujo típico

La integración más común es la de un punto de venta, y son tres llamadas:
1

Traés las sucursales, una sola vez

GET /external/branch te devuelve los IDs de tus sucursales. Guardalos en la configuración de cada caja.
2

Sumás puntos en cada venta

POST /external/tags/add con el monto, el cliente y el número de factura como external_id.
3

Cancelás si se anula la venta

PUT /external/tags/cancel/{externalId} con ese mismo número de factura.
Mandá siempre el external_id. Es lo que evita que un reintento de red duplique los puntos de una compra, y es la única forma de cancelar la operación después.

​
El flujo de canje

Si además querés que el cliente canjee premios desde tu sistema, son dos pasos:
1

Generás el canje

POST /external/exchange/product con el productOfferId del catálogo y el clientId. Descuenta los puntos y devuelve un code.
2

Entregás el premio

POST /external/purchase/redeem/{code} con ese código, cuando el cliente lo retira.
Los canjes creados por la API nacen en estado pending, no delivered. No se pueden crear ya entregados en un solo paso: registrar una entrega requiere un operador identificado, y una API key representa a un sistema, no a una persona.

​
Formato de las respuestas

La mayoría de los endpoints envuelve el resultado en una estructura común:
Los listados paginados no usan este envelope: devuelven { data, meta, links } en la raíz. Son GET /external/clients, /external/levels, /external/products, /external/operators y /external/purchase. GET /external/purchase/code/{code} también devuelve el objeto directamente. Está aclarado en la ficha de cada uno.Además, el campo status de adentro del envelope no siempre coincide con el código HTTP de la respuesta. Guiate por el código HTTP, no por ese campo.

​
Listados paginados

Los listados aceptan siempre los mismos parámetros: page (arranca en 1), limit (hasta 200), query para búsqueda parcial, y order + direction (asc / desc) para el orden. Los campos válidos de order cambian según el recurso y están en la ficha de cada endpoint.
Para recorrer un padrón completo conviene pedir limit=200 e iterar con page hasta que currentPage llegue a totalPages.

​
Escrituras: reemplazo total vs. incremental

No todos los PUT se comportan igual, y la diferencia importa:

​
Antes de empezar

1

Conseguí tu API key

Se genera desde el panel, en Configuración → Integraciones. Ver Autenticación.
2

Probá contra desarrollo

Usá https://apidev.tiendadepuntos.com hasta que el flujo esté cerrado. Las operaciones de puntos afectan saldos reales de clientes.
3

Revisá el manejo de errores

Sobre todo los 409 por external_id repetido y los 429 por rate limit. Ver Errores.
¿Dudas con la integración? Escribinos a hola@tiendadepuntos.com.