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: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: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:
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.
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
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.client — email o documento
client — email o documento
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.pointItems — sumar por ítems del catálogo
pointItems — sumar por ítems del catálogo
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.origin — trazabilidad
origin — trazabilidad
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.
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
clientIdy tiene que existir. Previsualizar no da de alta a nadie. ElclientIdlo sacás deGET /external/clients/search. pointItemslleva la cantidad explícita:[{ "id": 12, "quantity": 2 }]acá equivale a[12, 12]enPOST /external/tags/add.initialPointsToGive(puntos directos, sin conversión) solo existe en la simulación. La suma real no lo acepta.
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 mismoexternal_id:
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: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.
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
2
Confirmá la entrega
400 acá significa que el canje ya fue entregado o está vencido.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
offers con el precio en puntos según el nivel del cliente:GET /external/clients/search; los niveles del programa, por GET /external/levels.2
Generá el canje
code.3
Entregá el premio
Con ese
code, llamá a POST /external/purchase/redeem/{code} como en el paso anterior.POST /external/exchange/money con moneyAmount y clientId. Si el comercio tiene un mínimo configurado y no se alcanza, devuelve 409.
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.https://api.tiendadepuntos.com y probá con una venta real de monto chico.
¿Trabás en algún punto? Escribinos a hola@tiendadepuntos.com.
