Administrar el programa

Más allá de sumar puntos y entregar canjes, la API te deja administrar la configuración del programa: los niveles, el catálogo de premios, el padrón de clientes y el personal del comercio. Es lo mismo que hacés en el panel, con las mismas reglas de negocio.

Todos los ejemplos apuntan a https://apidev.tiendadepuntos.com. Estas llamadas escriben configuración real del comercio: probá contra desarrollo antes de pasar a producción.

El orden importa

Los recursos se referencian entre sí, así que si vas a armar un programa desde cero conviene este orden:

Niveles

Definen la escalera del programa. Sus id son los que después usás en las ofertas de cada premio.

Premios

Cada premio necesita al menos una oferta (precio en puntos), y las ofertas se atan a un nivel.

Sucursales y operadores

Las sucursales se crean desde el panel; los operadores se asignan a esas sucursales.

Clientes

Se pueden dar de alta en cualquier momento; el nivel se les asigna solo, según sus puntos.

Niveles

Un nivel se identifica por sus minPoints: son los puntos acumulados que un cliente necesita para alcanzarlo, y no pueden repetirse entre niveles del mismo comercio.

curl -X POST https://apidev.tiendadepuntos.com/external/levels \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nivel 2",
    "description": "Beneficios para clientes frecuentes",
    "minPoints": 5000,
    "pointsMultiplier": 1.5,
    "colors": { "primary": "#55FFFF", "secondary": "#ABFFFF", "border": "#000000" }
  }'

El pointsMultiplier es la bonificación de puntos de ese nivel: 1.5 significa que las compras de esos clientes acreditan un 50% más. 1 es sin bonificación.

Crear o eliminar un nivel reubica a los clientes según sus puntos acumulados y sincroniza las ofertas de todos los premios. Eso pasa de forma asincrónica: puede tardar unos segundos en reflejarse. Si justo después consultás un cliente, puede venir con el nivel viejo.

PUT /external/levels/{id} es un reemplazo total: mandá el nivel completo, porque los campos que omitas se sobrescriben. Un 409 significa que otro nivel ya tiene esos minPoints.

Premios

Un premio se compone de sus datos (nombre, descripciones, imagen) más el array offers, que es el precio en puntos por nivel:

curl -X POST https://apidev.tiendadepuntos.com/external/products \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Café gratis",
    "shortDescription": "Café a elección",
    "description": "Un café de especialidad a elección.",
    "image": "https://mi-cdn.com/premios/cafe.png",
    "offers": [
      { "levelId": 3, "points": 500 },
      { "levelId": 4, "points": 400 }
    ],
    "stock": { "controlled": true, "available": 12 },
    "maxPurchases": 1
  }'

offers — el precio por nivel

Necesitás al menos una. Los levelId salen de GET /external/levels; una oferta sin levelId es el precio para los clientes que todavía no tienen nivel.La respuesta devuelve cada oferta con su productOfferId: ese es el valor que consume POST /external/exchange/product para canjear.

stock — control de unidades

Con controlled: false el premio no lleva control de stock y se puede canjear sin límite de unidades. Con controlled: true, al llegar available a 0 Tienda de Puntos deshabilita el premio automáticamente.

image — solo la URL

Tienda de Puntos no descarga la imagen: guarda la URL que le mandes. Tiene que ser pública y estable. Si la omitís, el premio queda sin imagen.

maxPurchases — tope por cliente

Máximo de canjes que puede hacer un mismo cliente de ese premio. Omitilo para no poner tope.

Al actualizar un premio

PUT /external/products/{id} también es un reemplazo total, con dos detalles que conviene tener claros:

Las ofertas se reconcilian por nivel: la que ya cubría un levelId conserva su productOfferId, así que los códigos que tengas guardados siguen sirviendo. Las ofertas de niveles que no vengan en offers se eliminan.
Lo mismo con categoryIds: las categorías que no mandes se desasocian del premio.

Las opciones que la API pública no expone —mensaje post canje, restricción temporal, tope mensual de canjes, cupones de integración con Tiendanube o WooCommerce— se conservan como estaban. No hace falta mandarlas para no perderlas.Si el premio usa cupones personalizados (los que se cargan uno por uno desde el panel), no mandes stock: ese stock lo derivan los cupones y la API responde 400.

Clientes

El alta por API dispara los mismos automatismos que el panel: puntos de bienvenida si el comercio los tiene configurados, asignación de nivel inicial y email de bienvenida.

curl -X POST https://apidev.tiendadepuntos.com/external/clients \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-branch-id: 1972" \
  -d '{
    "firstName": "Juan Manuel",
    "lastName": "Pérez",
    "email": "juanma@mailinator.com",
    "documentNumber": "40100800",
    "phone": "+541164593678"
  }'

Hace falta al menos email o documentNumber: son las claves con las que Tienda de Puntos identifica a un cliente dentro del comercio. El x-branch-id (o el campo branchId) deja registrada la sucursal de alta, que después sirve para los reportes por sucursal.

Si estás sumando puntos de una venta y el cliente puede no existir, no hace falta darlo de alta antes: POST /external/tags/add lo crea solo con los datos que mandes en client.

A diferencia de niveles y premios, PUT /external/clients/{id} es incremental: lo que no mandás queda como está.

curl -X PUT https://apidev.tiendadepuntos.com/external/clients/84213 \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+541164593679" }'

El email no se puede cambiar si el cliente ya ingresó al menos una vez a la plataforma: es su credencial de acceso. Cambiar el email o el documento por uno que ya usa otro cliente del comercio devuelve 409.

Dar de baja un cliente

DELETE /external/clients/{id} programa la baja, no la ejecuta en el momento. El cliente entra en un período de gracia de 30 días: deja de aparecer en la operación y, al cumplirse el plazo, sus datos personales se anonimizan de forma irreversible.

curl -X DELETE https://apidev.tiendadepuntos.com/external/clients/84213 \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reasons": ["REQUESTED_BY_CLIENT"] }'

Los motivos son obligatorios y quedan en el registro de auditoría de la baja. Valores posibles: REQUESTED_BY_CLIENT, DUPLICATE_CLIENT, INCORRECT_EMAIL, OTHER.

Para revertir una baja dentro del período de gracia hay que restaurar al cliente desde el panel. La API no expone la restauración.Si lo que querés es que el cliente deje de acumular sin borrarlo, usá PUT /external/clients/{id}/status con SUSPEND.

Operadores

Los operadores son las personas del comercio que usan el panel y la app de caja.

curl -X POST https://apidev.tiendadepuntos.com/external/operators \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Ana",
    "lastName": "Gómez",
    "email": "ana@micomercio.com",
    "branches": [
      { "branchId": 1972, "permissionGroupId": 12 }
    ]
  }'

Si mandás password, el operador ya puede ingresar; si la omitís, recibe un email para definirla él mismo.

Los grupos de permisos se crean desde el panel y la API no los expone como recurso propio. Para saber qué permissionGroupId usar, mirá el campo branches de un operador ya configurado con GET /external/operators/{id}.Si omitís permissionGroupId, el operador queda creado pero sin permisos hasta que se le asigne un grupo desde el panel.

En el PUT los datos personales son incrementales, pero si mandás branches se reemplazan todas las asignaciones del operador por las que envíes. El email, la contraseña y el documento no se editan por esta vía.

El plan del comercio puede tener un tope de operadores. Si está alcanzado, el alta responde 400 con el motivo.

Qué no se puede hacer por API

Crear o editar sucursales

Las sucursales se administran desde el panel: el alta genera el QR de registro y valida el tope del plan. La API solo las lee (GET /external/branch y GET /external/branch/{id}).

Crear grupos de permisos

Se definen en el panel, permiso por permiso. La API los referencia por id pero no los crea.

Marcar un canje como entregado en un solo paso

Registrar una entrega requiere identificar al operador que la hizo, y una API key representa a un sistema, no a una persona. Siempre son dos pasos: generar el canje y después redeem.

Restaurar un cliente dado de baja

La restauración dentro del período de gracia se hace desde el panel.

¿Necesitás algo que no está acá? Escribinos a hola@tiendadepuntos.com.

Guías del panel

API · Empezar

API · Endpoints

El orden importa

Niveles

Premios

Al actualizar un premio

Clientes

Dar de baja un cliente

Operadores

Qué no se puede hacer por API

​El orden importa

​Niveles

​Premios

​Al actualizar un premio

​Clientes

​Dar de baja un cliente

​Operadores

​Qué no se puede hacer por API

El orden importa

Niveles

Premios

Al actualizar un premio

Clientes

Dar de baja un cliente

Operadores

Qué no se puede hacer por API