# Tienda de Puntos

> Guías y recursos para conectar Tienda de Puntos con tu negocio.

## Docs

- [Documentación](https://developers.tiendadepuntos.com/index.md): Todo lo que necesitás para conectar Tienda de Puntos con tu negocio.
- [Documentación](https://developers.tiendadepuntos.com/documentacion.md): Referencias y recursos de Tienda de Puntos.
- [Primeros pasos](https://developers.tiendadepuntos.com/primeros-pasos.md): Guía simple para poner en marcha Tienda de Puntos desde los objetivos iniciales del onboarding.
- [Pantallas principales](https://developers.tiendadepuntos.com/pantallas-principales.md): Para qué sirve cada pantalla del panel y cómo usarla en la operación diaria del comercio.
- [Introducción a la API](https://developers.tiendadepuntos.com/api-reference/introduccion.md): Conectá tu POS, ERP o e-commerce con el programa de puntos de tu comercio.
- [Autenticación](https://developers.tiendadepuntos.com/api-reference/autenticacion.md): Cómo autenticar tus llamadas con la API key del comercio.
- [Integrar tu punto de venta](https://developers.tiendadepuntos.com/api-reference/quickstart.md): De cero a sumar puntos en una venta real, paso a paso.
- [Administrar el programa](https://developers.tiendadepuntos.com/api-reference/administracion.md): Crear y mantener niveles, premios, clientes y operadores desde tu sistema.
- [Errores y límites](https://developers.tiendadepuntos.com/api-reference/errores.md): Formato de los errores, códigos que devuelve la API, idempotencia y rate limits.
- [Listar operadores](https://developers.tiendadepuntos.com/api-reference/endpoints/operadores/listar-operadores.md): Devuelve los operadores del comercio, paginados. Por defecto vienen los administradores primero.
- [Crear un operador](https://developers.tiendadepuntos.com/api-reference/endpoints/operadores/crear-un-operador.md): Crea un operador del comercio con rol `operator`.
- [Obtener un operador](https://developers.tiendadepuntos.com/api-reference/endpoints/operadores/obtener-un-operador.md): Devuelve un operador del comercio por su `id`, con las sucursales y grupos de permisos que tiene asignados. Si el operador no existe, o pertenece a otro comercio, responde 404.
- [Actualizar un operador](https://developers.tiendadepuntos.com/api-reference/endpoints/operadores/actualizar-un-operador.md): Actualiza los datos personales del operador y, si mandás `branches`, reemplaza sus asignaciones de sucursal y permisos por las que envíes.
- [Eliminar un operador](https://developers.tiendadepuntos.com/api-reference/endpoints/operadores/eliminar-un-operador.md): Elimina un operador del comercio y su usuario de acceso al panel. Las operaciones que registró (sumas de puntos, canjes) no se tocan.
- [Listar clientes](https://developers.tiendadepuntos.com/api-reference/endpoints/clientes/listar-clientes.md): Devuelve los clientes del comercio, paginados y ordenados por puntos disponibles descendente.
- [Crear un cliente](https://developers.tiendadepuntos.com/api-reference/endpoints/clientes/crear-un-cliente.md): Da de alta un cliente en el programa de fidelidad del comercio.
- [Buscar un cliente por email o documento](https://developers.tiendadepuntos.com/api-reference/endpoints/clientes/buscar-un-cliente-por-email-o-documento.md): Busca un único cliente del comercio por email exacto o por número de documento exacto. No hace búsqueda parcial. Si no encuentra al cliente devuelve 404 con el mensaje `Client not found`.
- [Actualizar un cliente](https://developers.tiendadepuntos.com/api-reference/endpoints/clientes/actualizar-un-cliente.md): Actualiza los datos de un cliente. Es incremental: los campos que no mandes quedan como están.
- [Eliminar un cliente](https://developers.tiendadepuntos.com/api-reference/endpoints/clientes/eliminar-un-cliente.md): Programa la baja definitiva del cliente. Igual que en el panel, el cliente entra en un período de gracia de 30 días: durante ese tiempo deja de aparecer en la operación y, al cumplirse, sus datos personales se anonimizan de forma irreversible.
- [Cambiar el estado de un cliente](https://developers.tiendadepuntos.com/api-reference/endpoints/clientes/cambiar-el-estado-de-un-cliente.md): Activa o suspende a un cliente del programa de fidelidad. Un cliente suspendido no acumula ni canjea puntos. Al suspender (`SUSPEND`) el campo `reason` es obligatorio.
- [Listar sucursales](https://developers.tiendadepuntos.com/api-reference/endpoints/sucursales/listar-sucursales.md): Devuelve todas las sucursales del comercio dueño de la API key. El `id` de cada sucursal es el que se usa después en el header `x-branch-id` y en el campo `branch_id` al sumar puntos.
- [Obtener una sucursal](https://developers.tiendadepuntos.com/api-reference/endpoints/sucursales/obtener-una-sucursal.md): Devuelve una sucursal del comercio por su `id`. Si la sucursal no existe, o pertenece a otro comercio, responde 404 con `Sucursal no encontrada`.
- [Listar premios](https://developers.tiendadepuntos.com/api-reference/endpoints/premios/listar-premios.md): Devuelve el catálogo de premios del comercio, paginado.
- [Crear un premio](https://developers.tiendadepuntos.com/api-reference/endpoints/premios/crear-un-premio.md): Crea un premio en el catálogo del comercio.
- [Obtener un premio](https://developers.tiendadepuntos.com/api-reference/endpoints/premios/obtener-un-premio.md): Devuelve un premio del comercio por su `id`, con sus ofertas por nivel y sus categorías. Si el premio no existe, o pertenece a otro comercio, responde 404.
- [Actualizar un premio](https://developers.tiendadepuntos.com/api-reference/endpoints/premios/actualizar-un-premio.md): Reemplaza los datos de un premio. **No es un patch**: mandá siempre el premio completo.
- [Eliminar un premio](https://developers.tiendadepuntos.com/api-reference/endpoints/premios/eliminar-un-premio.md): Elimina un premio del catálogo junto con sus ofertas. Los canjes ya realizados no se tocan.
- [Listar niveles](https://developers.tiendadepuntos.com/api-reference/endpoints/niveles/listar-niveles.md): Devuelve los niveles del programa de fidelidad del comercio, paginados y ordenados por puntos mínimos ascendente.
- [Crear un nivel](https://developers.tiendadepuntos.com/api-reference/endpoints/niveles/crear-un-nivel.md): Crea un nivel en el programa de fidelidad del comercio.
- [Obtener un nivel](https://developers.tiendadepuntos.com/api-reference/endpoints/niveles/obtener-un-nivel.md): Devuelve un nivel del comercio por su `id`. Si el nivel no existe, o pertenece a otro comercio, responde 404 con `Level not found`.
- [Actualizar un nivel](https://developers.tiendadepuntos.com/api-reference/endpoints/niveles/actualizar-un-nivel.md): Reemplaza los datos de un nivel. **No es un patch**: los campos que no envíes se sobrescriben, así que mandá siempre el nivel completo.
- [Eliminar un nivel](https://developers.tiendadepuntos.com/api-reference/endpoints/niveles/eliminar-un-nivel.md): Elimina un nivel del comercio y las ofertas de premios asociadas a ese nivel.
- [Crear una oferta de puntos (QR o email)](https://developers.tiendadepuntos.com/api-reference/endpoints/puntos/crear-una-oferta-de-puntos-qr-o-email.md): Genera una oferta de puntos que el cliente reclama después. Según el `type`:
- [Actualizar el monto de una oferta QR](https://developers.tiendadepuntos.com/api-reference/endpoints/puntos/actualizar-el-monto-de-una-oferta-qr.md): Cambia el monto en pesos de una oferta QR ya creada y la deja en estado activo. Se usa típicamente en QR variables de caja, donde el mismo QR se reutiliza y se le actualiza el importe en cada venta.
- [Sumar puntos a un cliente por una compra](https://developers.tiendadepuntos.com/api-reference/endpoints/puntos/sumar-puntos-a-un-cliente-por-una-compra.md): Acredita puntos de forma inmediata a partir del monto de una compra. Es el endpoint principal para integrar un POS o ERP.
- [Cancelar una suma de puntos](https://developers.tiendadepuntos.com/api-reference/endpoints/puntos/cancelar-una-suma-de-puntos.md): Revierte una operación de puntos identificada por el `external_id` con el que se creó. Se usa cuando se anula la venta en el sistema de origen. Descuenta los puntos que se habían acreditado.
- [Listar QRs con código de validación](https://developers.tiendadepuntos.com/api-reference/endpoints/codigos-de-validacion/listar-qrs-con-codigo-de-validacion.md): Devuelve los QR activos del comercio que tienen habilitado el código de validación rotativo. El `validationWindowSeconds` de cada QR indica cada cuántos segundos rota su código, y sirve para decidir la frecuencia de polling.
- [Obtener el código vigente de un QR](https://developers.tiendadepuntos.com/api-reference/endpoints/codigos-de-validacion/obtener-el-codigo-vigente-de-un-qr.md): Devuelve el código de 4 dígitos que está vigente en este momento para el QR, junto con los segundos que le quedan de vida. Se usa para mostrarlo en la pantalla de la caja y que el cliente lo compare con el que ve en su celular.
- [Validar el código ingresado por el cliente](https://developers.tiendadepuntos.com/api-reference/endpoints/codigos-de-validacion/validar-el-codigo-ingresado-por-el-cliente.md): Verifica el código de 4 dígitos que el cliente dice tener en pantalla. Acepta el código de la ventana actual y, durante los primeros 5 segundos de una ventana nueva, también el de la anterior, para no penalizar a quien tipea justo en el cambio.
- [Listar canjes](https://developers.tiendadepuntos.com/api-reference/endpoints/canjes/listar-canjes.md): Devuelve los canjes del comercio, paginados y ordenados por fecha. Si no se envían `startDate` y `endDate`, toma el último mes.
- [Entregar un canje](https://developers.tiendadepuntos.com/api-reference/endpoints/canjes/entregar-un-canje.md): Marca el canje como entregado. Es el paso que se ejecuta en el mostrador cuando el cliente presenta su código y se le da el producto.
- [Consultar un canje por código](https://developers.tiendadepuntos.com/api-reference/endpoints/canjes/consultar-un-canje-por-codigo.md): Devuelve el detalle del canje —producto y cliente— sin entregarlo. Sirve para que el operador confirme qué tiene que dar antes de llamar a `POST /external/purchase/redeem/{code}`.
- [Canjear un premio](https://developers.tiendadepuntos.com/api-reference/endpoints/canjes/canjear-un-premio.md): Descuenta los puntos al cliente y genera un canje pendiente de entrega, con su código.
- [Canjear puntos por dinero](https://developers.tiendadepuntos.com/api-reference/endpoints/canjes/canjear-puntos-por-dinero.md): Descuenta los puntos equivalentes al monto indicado y genera un canje pendiente con su código, para aplicarlo como descuento en la venta.
- [Integraciones](https://developers.tiendadepuntos.com/integraciones.md): Qué hace cada integración, cómo funciona y qué necesitás para configurarla.

## OpenAPI Specs

- [openapi](https://developers.tiendadepuntos.com/api-reference/openapi.json)

## Optional

- [Blog](https://www.tiendadepuntos.com/blog)