# Beneficios (https://docs.loybox.com.ar/api-reference/beneficios)



Esta sección tiene las dos mitades de la vida de un premio: **el catálogo** que
armó el comercio, y **el canje** de un código que un cliente trae para usar.

<Callout title="Beneficio y beneficio canjeable no son lo mismo">
  El comercio crea **beneficios**, y cada uno tiene un `benefit_id`. Cuando un
  cliente compra uno con sus puntos recibe un **beneficio canjeable** con su propio
  `client_benefit_code`.

  El `benefit_id` sirve sólo para consultar información. El
  `client_benefit_code` sirve para consultar **y para canjear**.
</Callout>

## El flujo del canje [#el-flujo-del-canje]

Así se ve del lado de tu sistema cuando un cliente llega con un código:

<Steps>
  <Step>
    ### El cliente da su código [#el-cliente-da-su-código]

    Lo tiene en su app de Loybox. Es el `client_benefit_code`.
  </Step>

  <Step>
    ### Consultás qué es [#consultás-qué-es]

    [`GET /v1/benefits/preview/{client_benefit_code}`](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo)
    te dice qué premio es y, si corresponde, qué descuento aplicar. Todavía no
    canjea nada.
  </Step>

  <Step>
    ### Aplicás el descuento [#aplicás-el-descuento]

    En tu caja, tu e-commerce o donde corra la venta, con los datos del paso
    anterior.
  </Step>

  <Step>
    ### Lo marcás como usado [#lo-marcás-como-usado]

    [`POST /v1/benefits/redeem`](https://docs.loybox.com.ar/api-reference/beneficios/canjear). A partir de acá
    el código queda quemado y no se puede volver a usar.
  </Step>
</Steps>

<Callout type="warn" title="Canjeá recién cuando la venta se concretó">
  Consultar es inofensivo y se puede repetir; canjear es definitivo. Si canjeás
  antes de cerrar la venta y la venta se cae, el cliente perdió el premio.
</Callout>

## Los endpoints [#los-endpoints]

<Cards>
  <Card title="Listar beneficios" icon="Boxes" description="Todo el catálogo que creó el comercio." href="/api-reference/beneficios/listar" />

  <Card title="Obtener un beneficio" icon="Gift" description="Un beneficio del catálogo por su benefit_id." href="/api-reference/beneficios/obtener" />

  <Card title="Consultar un código" icon="Tag" description="Qué premio es un client_benefit_code, antes de canjearlo." href="/api-reference/beneficios/consultar-codigo" />

  <Card title="Consultar un código (v2)" icon="Sparkles" description="Lo mismo, con el título y el valor del descuento al nivel de arriba." href="/api-reference/beneficios/consultar-codigo-v2" />

  <Card title="Canjear un beneficio" icon="BadgeCheck" description="Marca el código como usado. Es definitivo." href="/api-reference/beneficios/canjear" />
</Cards>

## Credencial [#credencial]

Toda la sección va desde tu servidor, con la
[API key del comercio](https://docs.loybox.com.ar/api-reference/credenciales#api-key-del-comercio):

```
Authorization: Bearer {api-key}
```