> ## Documentation Index
> Fetch the complete documentation index at: https://developers.tiendadepuntos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introducción a la API

> Conectá tu POS, ERP o e-commerce con el programa de puntos de tu comercio.

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](/integraciones), esta es la vía para conectarlo.

## URL base

<CodeGroup>
  ```bash Producción theme={null}
  https://api.tiendadepuntos.com
  ```

  ```bash Desarrollo theme={null}
  https://apidev.tiendadepuntos.com
  ```
</CodeGroup>

Todos los endpoints públicos cuelgan de `/external`.

## Qué podés hacer

<CardGroup cols={2}>
  <Card title="Sumar puntos" icon="plus" href="/api-reference/endpoints/puntos/sumar-puntos-a-un-cliente-por-una-compra">
    Acreditar puntos por el monto de una compra, con el cliente identificado por email o documento.
  </Card>

  <Card title="Administrar clientes" icon="users" href="/api-reference/endpoints/clientes/listar-clientes">
    Listar, dar de alta, editar y dar de baja clientes, con su saldo de puntos y su nivel.
  </Card>

  <Card title="Mantener el catálogo" icon="package" href="/api-reference/endpoints/premios/listar-premios">
    Crear y editar premios con su precio en puntos por nivel, y controlar su stock.
  </Card>

  <Card title="Configurar niveles" icon="layers" href="/api-reference/endpoints/niveles/listar-niveles">
    Armar la escalera de niveles del programa y sus multiplicadores de puntos.
  </Card>

  <Card title="Canjear premios" icon="shopping-bag" href="/api-reference/endpoints/canjes/canjear-un-premio">
    Descontar puntos y generar el canje, por un premio del catálogo o por un monto en pesos.
  </Card>

  <Card title="Entregar canjes" icon="gift" href="/api-reference/endpoints/canjes/entregar-un-canje">
    Consultar qué premio pidió el cliente y marcarlo como entregado.
  </Card>

  <Card title="Gestionar operadores" icon="id-card" href="/api-reference/endpoints/operadores/listar-operadores">
    Dar de alta el personal del comercio y asignarle sucursales y permisos.
  </Card>
</CardGroup>

## El flujo típico

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Sumás puntos en cada venta">
    `POST /external/tags/add` con el monto, el cliente y el número de factura como `external_id`.
  </Step>

  <Step title="Cancelás si se anula la venta">
    `PUT /external/tags/cancel/{externalId}` con ese mismo número de factura.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

## El flujo de canje

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

<Steps>
  <Step title="Generás el canje">
    `POST /external/exchange/product` con el `productOfferId` del catálogo y el `clientId`. Descuenta los puntos y devuelve un `code`.
  </Step>

  <Step title="Entregás el premio">
    `POST /external/purchase/redeem/{code}` con ese código, cuando el cliente lo retira.
  </Step>
</Steps>

<Note>
  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.
</Note>

## Formato de las respuestas

La mayoría de los endpoints envuelve el resultado en una estructura común:

```json theme={null}
{
  "success": true,
  "status": 200,
  "message": "Request was successful",
  "data": { }
}
```

<Warning>
  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.
</Warning>

## 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.

```json theme={null}
{
  "data": [],
  "meta": {
    "totalItems": 128,
    "itemCount": 10,
    "itemsPerPage": 10,
    "totalPages": 13,
    "currentPage": 1
  },
  "links": { "next": "external/clients?page=2&limit=10" }
}
```

<Tip>
  Para recorrer un padrón completo conviene pedir `limit=200` e iterar con `page` hasta que `currentPage` llegue a `totalPages`.
</Tip>

## Escrituras: reemplazo total vs. incremental

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

| Endpoint                       | Comportamiento                                                             |
| ------------------------------ | -------------------------------------------------------------------------- |
| `PUT /external/levels/{id}`    | Reemplazo total: mandá el nivel completo                                   |
| `PUT /external/products/{id}`  | Reemplazo total: las ofertas y categorías que no vengan se eliminan        |
| `PUT /external/clients/{id}`   | Incremental: lo que no mandás queda como está                              |
| `PUT /external/operators/{id}` | Incremental en los datos personales; `branches` reemplaza las asignaciones |

## Antes de empezar

<Steps>
  <Step title="Conseguí tu API key">
    Se genera desde el panel, en **Configuración → Integraciones**. Ver [Autenticación](/api-reference/autenticacion).
  </Step>

  <Step title="Probá contra desarrollo">
    Usá `https://apidev.tiendadepuntos.com` hasta que el flujo esté cerrado. Las operaciones de puntos afectan saldos reales de clientes.
  </Step>

  <Step title="Revisá el manejo de errores">
    Sobre todo los 409 por `external_id` repetido y los 429 por rate limit. Ver [Errores](/api-reference/errores).
  </Step>
</Steps>

¿Dudas con la integración? Escribinos a [hola@tiendadepuntos.com](mailto:hola@tiendadepuntos.com).