---
title: 'Notas de release'
description: 'Cambios de comportamiento, nuevos endpoints y fixes liberados en la API Guper. Más recientes arriba.'
---

# Notas de release

Cambios de comportamiento, nuevos endpoints y fixes liberados en la
API Guper. Más recientes arriba.

Cada entrada tiene una etiqueta:

- <span class="rn-tag rn-tag--breaking">Breaking change</span> — el contrato de request o response cambió; las integraciones deben adaptarse.
- <span class="rn-tag rn-tag--new">Nuevo endpoint</span> — endpoint añadido.
- <span class="rn-tag rn-tag--improvement">Mejora</span> — cambio retrocompatible.
- <span class="rn-tag rn-tag--fix">Fix</span> — corrige comportamiento erróneo sin cambiar el contrato.
- <span class="rn-tag rn-tag--deprecated">Deprecación</span> — endpoint descontinuado; migrá a la alternativa indicada.

---

## 12 de noviembre de 2026

### <span class="rn-tag rn-tag--improvement">Mejora</span> Saldo vencido en el reporte de cards

[Cashback emitido y canjeado por campaña (agregado)](/docs/{lang}/api-reference/loyalty/report/cards)

`GET /api/loyalty/report/cards` ahora devuelve **`expiredBalance`** en cada fila y en `total`: el saldo que quedó en las tarjetas vencidas — cuánto crédito se perdió por no usarse a tiempo. Mismo corte que `cardsExpired`; en centavos, como los demás valores. También nuevo: **`touchedRedeemed`**, el valor canjeado por las mismas tarjetas contadas en `touchedCards` (en cualquier fecha). `redeemed` sigue cortando por la fecha del canje. Campos nuevos, nada más cambió.

## 11 de noviembre de 2026

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Actualizar clientes en lote

[Actualizar clientes en lote](/docs/{lang}/api-reference/register/customer/update-batch)

`PUT /api/register/customer/batch` actualiza **varios clientes en una llamada** — una lista `items` de `{id, ...campos}`. Poner `entityType=legal` en cientos de clientes, o importar valores por cliente, deja de ser cientos de llamadas.

Cada ítem reutiliza el **mismo camino del update individual** (misma sanitización y validación; solo `id` es obligatorio por ítem). Un ítem malo no tumba el lote: la respuesta trae un `outcome` por ítem (`updated` / `not_found` / `rejected` con el motivo) y un `summary`. Pasa **`dryRun: true`** para validar sin escribir (`would_update`). Hasta **100 ítems** por llamada.

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Cancelar y reactivar cards en lote

[Cancelar cards en lote](/docs/{lang}/api-reference/loyalty/card/cancel-batch) · [Reactivar cards en lote](/docs/{lang}/api-reference/loyalty/card/reactivate-batch)

`POST /api/loyalty/cards/cancel` y `POST /api/loyalty/cards/reactivate` procesan **hasta 100 cards por llamada**: cancelar 3,000 cards deja de ser 3,000 llamadas y pasa a ser 30.

Los `ids` aceptan rangos e items sueltos en la misma sintaxis de las collections: `"1512200:1512299;1512305"` son los cards del 1512200 al 1512299 mas el 1512305. Tambien se acepta un arreglo. El tope de 100 aplica al conjunto expandido, y el rango nunca cruza organizaciones: un id de otra cuenta vuelve `not_found` y queda intacto.

La falla parcial se trata como normal: la respuesta es `200` con el desenlace de **cada** id (`canceled`, `already_canceled`, `has_open_reservation`, `not_found`), y el `400` queda solo para la peticion mal formada. Un card ya cancelado o con reserva abierta no tumba el resto del lote.

Ejecute antes con `dryRun: true`: muestra lo que pasaria item por item y **cuanto saldo saldria de circulacion**, sin escribir nada. La respuesta trae un `batchId` que amarra los cards de una misma operacion.

## 9 de noviembre de 2026

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Cancelar y reactivar card

[Cancelar card](/docs/{lang}/api-reference/loyalty/card/cancel) · [Reactivar card](/docs/{lang}/api-reference/loyalty/card/reactivate)

Cancelar un card ahora tiene endpoint propio: `POST /api/loyalty/cards/{id}/cancel` saca el card de circulación — sale de toda consulta de saldo y se lee como `canceled` — y `POST /api/loyalty/cards/{id}/reactivate` lo deshace. Hasta ahora la cancelación por API existía solo a nivel de transacción (`transaction/cancel`), que revierte lo que generó una compra; el objetivo ahora puede ser el card mismo, sin pedido de por medio: un card de campaña otorgado por error, un card manual, un card que la operación necesita cerrar.

Cancelar un card es un cambio de **estado**, no un movimiento: el saldo no se debita ni se devuelve, y nada entra al ledger de flow del card. Para sacar valor de un card que sigue vivo, siga usando [Ajustar saldo del card](/docs/{lang}/api-reference/loyalty/card/adjust) con `manual_debit`.

Un card con reserva de canje abierta se rechaza con `409` (el valor reservado espera liquidación o devolución), y una segunda cancelación también responde `409`. Los detalles y la comparación con la cancelación de transacción están en la guía [Cancelación en loyalty](/docs/{lang}/guides/loyalty-cancellation).

## 5 de noviembre de 2026

### <span class="rn-tag rn-tag--improvement">Mejora</span> Fecha del pedido en Reward by Order

[Reward by Order](/docs/{lang}/api-reference/loyalty/checkout/reward-by-order)

`rewardByOrder` ahora documenta y valida el campo `creationDate`, la fecha y hora del pedido en ISO 8601 (p. ej. `2026-11-02T10:00:00-06:00`). Envíelo cuando la compra ocurrió antes de la llamada: las campañas consideradas son las que estaban activas **en esa fecha**, la vigencia del card cuenta desde ella y queda como fecha del pedido en la transacción. Sin el campo no cambia nada: se usa la hora de la llamada.

Un valor ilegible, una fecha que no existe (p. ej. `2026-02-31`) o a más de un día en el futuro ahora devuelve `400`. Antes, un valor así se ignoraba en el cálculo y el pedido podía no registrarse en la confirmación.

## 4 de noviembre de 2026

### <span class="rn-tag rn-tag--improvement">Mejora</span> Audiencia por card activo

[Consultar audiencia (QON)](/docs/{lang}/api-reference/register/audience-query/qon-query)

Dos campos nuevos en el motor de audiencia: `hasActiveCard` (tiene al menos un card con saldo, ya vigente y sin vencer) y `activeCardExpiresWithinDays` (tiene un card activo que vence en los próximos N días). Ej.: `[{"col": "activeCardExpiresWithinDays"}, "inNextDays", {"int": 7}]` es la audiencia del "tu cashback vence esta semana". El saldo se lee al momento, así que quien acaba de canjear todo sale de la audiencia de inmediato.

## 26 de octubre de 2026

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Los refIds de una entidad, sin recorrer la interfaz

[Listar refs de una Categoría](/docs/{lang}/api-reference/catalog/category/by-entity/list) · [de una Marca](/docs/{lang}/api-reference/catalog/brand/by-entity/list) · [de un Vendedor](/docs/{lang}/api-reference/catalog/seller/by-entity/list) · [de un Pago](/docs/{lang}/api-reference/register/payment/by-entity/list)

Ya se podía ir de `refId` a la entidad (`GET /api/{service}/{interface}/{resource}/{refId}`); faltaba el camino de vuelta. Ahora `GET /api/catalog/category-external-ref/by-category/{categoryId}` — y los equivalentes de marca, vendedor y pago — devuelve **todos los refIds de esa entidad, uno por interfaz**, sin tener que listar la interfaz completa y filtrar en el cliente.

Devuelve un arreglo vacío cuando no hay mapeo (no da 404). Refleja el `by-person` que ya existía para persona.

### <span class="rn-tag rn-tag--fix">Corrección</span> refId con carácter especial en el path

Los endpoints de external-ref no hacían URL-decode de los segmentos `{interface}` y `{refId}`. Un refId con espacio (como `00 71000000038`, común en cegid) llegaba como `00%2071000000038` y no coincidía en la base. Aplica a catalog (marca, categoría, vendedor) y register (pago, persona).

### <span class="rn-tag rn-tag--improvement">Mejora</span> Reporte de productos desglosado por tienda y por tiempo

[Productos más vendidos](/docs/{lang}/api-reference/order/report/products)

El `groupBy` del reporte de productos ahora acepta una **lista separada por comas**: la dimensión del ítem (`product`/`sku`/`category`/`brand`) **más** `store` y/o un grano de tiempo (`day`/`week`/`month`). Ej.: `groupBy=product,store`, `sku,week`, `product,store,month`.

Con el desglose, el `limit` toma los **top ítems de todo el período** y cada fila es una celda (ítem × tienda × período, con `storeId`/`day`/`week`/`month`). Así "top productos por tienda" o "por semana" vuelve en una sola llamada, en vez de una por tienda. Máximo un grano de tiempo por llamada; una celda sin ventas no se emite. Retrocompatible: sin los tokens extra, nada cambia.

---

## 22 de octubre de 2026

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Valide su payload antes de integrar

[Valide su payload](/docs/{lang}/guides/payload-validation)

`POST https://developers.guper.co/api/validate` recibe el JSON que produce su integración y devuelve, campo por campo, lo que cumple con esta documentación y lo que no: campo que **no pertenece** al endpoint (con sugerencia del nombre correcto cuando se parece), campo **obligatorio que falta**, **tipo** que no corresponde y **valor** fuera de la lista aceptada — incluido el uso equivocado de mayúsculas, como `"Legal"` donde el campo acepta `legal`.

Sin autenticación, sin guardar nada y sin crear ninguna transacción. La comparación se ejecuta contra el mismo archivo que genera la página de referencia, así que nunca queda desfasada respecto a lo que usted lee.

⚠️ La verificación es de **forma**. No conoce su organización: no le dirá si el `storeId` existe, si la `interface` está registrada, ni si el importe está en la escala correcta de centavos. Un payload aprobado aquí todavía puede ser rechazado por la API por esos motivos.

---

## 21 de octubre de 2026

### <span class="rn-tag rn-tag--improvement">Mejora</span> "Diferente de" en la regla Tipo de entidad

[Reglas de campaña: Crear](/docs/{lang}/api-reference/loyalty/campaign/campaign-rules/create)

La regla de campaña **Tipo de entidad** ([`code` 11](/docs/{lang}/api-reference/loyalty/campaign/campaign-rules/create)) ahora respeta el `reverse`, igual que la de nivel del cliente y la de tipo de compra: `false` = **igual a** (lo que ya hacía), `true` = **diferente de**. Antes el campo se aceptaba y se guardaba, pero se ignoraba al evaluar: la regla solo sabía comparar por igualdad.

⚠️ Un pedido **sin `client.entityType` no coincide con ningún valor**: sigue fallando con `reverse: false` y ahora **dispara** con `reverse: true`. Como el `entityType` llega solo en el cuerpo del `rewardByOrder`, "diferente de persona moral" también alcanza al pedido que no informó el tipo.

Una regla creada desde el panel no cambia de comportamiento — el panel siempre guardó `reverse: false`. Si usted creó la regla por la API con `reverse: true`, ese valor se ignoraba y ahora sí invierte la regla.

---

## 12 de octubre de 2026

### <span class="rn-tag rn-tag--improvement">Mejora</span> Listar mensajes por teléfono, con el cuerpo, en una llamada

[Messages: Listar](/docs/{lang}/api-reference/sender/messages/list)

El listado de mensajes ahora acepta **`cellphone`** (match exacto en el teléfono que recibió el mensaje) e **`include`** (lista separada por comas que agrega los campos renderizados a cada dispatcher: `rendered_body`, `rendered_subject`, `rendered_text`, `rendered_meta`).

Juntos eliminan dos round-trips para quien necesita saber qué mensaje inició una conversación a partir de un número: antes había que resolver teléfono→cliente en register, listar los mensajes y abrir el detalle de cada uno solo para leer el cuerpo. Ahora **`?cellphone=...&include=rendered_body`** lo devuelve todo en una llamada.

⚠️ `include` es **opt-in** — sin él la lista se mantiene liviana (el cuerpo renderizado puede ser un HTML entero). `cellphone` coincide con el **snapshot guardado al enviar**, no con el registro vivo del cliente.

### <span class="rn-tag rn-tag--improvement">Mejora</span> Tipo de compra en rewardByOrder

[Recompensa por pedido](/docs/{lang}/api-reference/loyalty/checkout/reward-by-order)

`POST /api/loyalty/rewardByOrder` acepta el campo opcional **`purchaseType`**: el tipo de compra, en texto libre definido por su integración (p. ej.: `delivery`, `recoleccion`). Hasta 100 caracteres; se eliminan los espacios de los extremos y un valor vacío se ignora. Un número, booleano o lista devuelve `400`. El valor se conserva con la transacción hasta `confirmOrder`.

En las campañas de compra, la nueva regla **Tipo de compra** ([`code` 20](/docs/{lang}/api-reference/loyalty/campaign/campaign-rules/create)) se activa cuando el `purchaseType` es **igual** (o **diferente**, con `reverse`) a cualquiera de los valores configurados, sin distinguir mayúsculas. Sirve para separar mayoreo/menudeo, compra de colaborador, empresa/persona física, etc. Retrocompatible: si no lo envía, nada cambia.

---

## 7 de octubre de 2026

### <span class="rn-tag rn-tag--improvement">Mejora</span> El ingreso descompuesto, del precio de lista al neto

[Reporte de ventas](/docs/{lang}/api-reference/order/report/sales)

Todo total de `report/sales` ahora trae **`mix`**: `listRevenue` (precio de lista) − `discount` − `incentive` = **`netRevenue`**, más `averageTicket` (**ASP**, el precio efectivamente cobrado) y `listAverageTicket` (**OSP**, el precio de lista). `comparison.total` trae el mismo bloque, así que el ingreso neto se puede comparar período contra período.

⚠️ **`revenue` ya es neto del descuento comercial** — el `price` del artículo es el unitario después del descuento. El precio de lista es `revenue` **más** `discounts`, no menos; restar el descuento de `revenue` lo cuenta dos veces. Evitar ese recálculo en cada consumidor es justamente por qué estos campos existen ahora.

⚠️ `incentive` y `netRevenue` vuelven en **`null`** sin `withAttribution=1` — el saldo canjeado vive en la atribución, y devolver cero sería mentira.

⚠️ No confundir con `attribution.revenueGross`/`revenueNet`, que son del recorte de las ventas atribuidas; `mix` es del negocio entero.

---

## 3 de octubre de 2026

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Sincronizar vínculos tienda ↔ política

[Sincronizar vínculos tienda ↔ política](/docs/{lang}/api-reference/register/stores/store-wallet-link/sync)

`PUT /api/register/store/walletLink` define de una vez todas las tiendas de una política (`{"wallet": 108, "stores": [...]}`) o todas las políticas de una tienda (`{"store": 22, "wallets": [...]}`), en una sola transacción. La lista es el estado final: lo que no esté en ella se elimina. Reemplaza un `POST`/`DELETE` por vínculo. También se revisaron las páginas de listar, crear y eliminar vínculos; el listado documenta `with=store`.

### <span class="rn-tag rn-tag--improvement">Mejora</span> Las políticas de canje compiten entre sí

[Políticas de canje](/docs/{lang}/guides/redemption-policies)

Cuando el cliente tiene saldo en **más de una política de canje** válida para el pedido, las políticas ahora **compiten entre sí**: el pedido usa solo la que da el mayor descuento (en empate, la de vigencia más próxima). Antes, los cards de políticas diferentes en modo Agregar o Mixto se sumaban.

Dentro de una misma política nada cambió: Agregar suma los cards, Único usa el mejor. El modo Mixto pasa a comportarse como Agregar. El contrato de [Recompensa por pedido](/docs/{lang}/api-reference/loyalty/checkout/reward-by-order) es el mismo; lo que cambia es el `redeemable.total` de quien tiene saldo en más de una política en la misma tienda. La nueva guía explica la regla con ejemplos.

---

## 30 de septiembre de 2026

### <span class="rn-tag rn-tag--improvement">Mejora</span> Permisos por api-key

[Conceder scopes al acceso](/docs/{lang}/api-reference/connect/api/grant-access-scope)

Cada api-key ahora tiene una lista de **permisos** con el formato `servicio.permiso`, y cada ruta exige el suyo. Hoy cada servicio expone un permiso único `all` — `register.all`, `loyalty.all`, `order.all`, `sender.all`, `catalog.all`, `organization.all`, `journey.all`, `media-manager.all`, `auditObserver.all`, `pipeline.all`, `gapp-be.all` — y `connect` expone seis más finos: `connect.user`, `connect.access`, `connect.scope`, `connect.session`, `connect.auth` y `connect.mcp`.

**Nada cambia para quien ya integra:** todas las llaves existentes recibieron todos los permisos. Una llamada cuya llave no tiene el permiso de la ruta se rechaza con **`403`**, y la respuesta nombra lo que falta en `requiredScope`. Las llamadas firmadas entre servicios Guper no pasan por esa verificación.

Los permisos de cada llave también se editan en el panel, en **Configuración › API Keys › Permisos**.

## 29 de septiembre de 2026

### <span class="rn-tag rn-tag--improvement">Mejora</span> Campañas en borrador

[Listar campañas](/docs/{lang}/api-reference/loyalty/campaign/list)

Una campaña ahora puede guardarse como **borrador** (`isDraft: true`) en `POST`/`PUT /api/loyalty/campaign`: queda editable y **nunca se ejecuta** — mientras sea borrador, `isActive` se fuerza a `0` en el servidor. Publica enviando `isDraft: false`; una vez publicada solo alterna entre activa y pausada y no vuelve a borrador (`400`).

En el listado, el `status` derivado gana el valor **`draft`**, que prevalece sobre los demás; también funciona en `?status=draft`, `statusCounts` y `sortByStatus` (activas, borradores, pausadas, terminadas). Retrocompatible: las campañas existentes están publicadas (`isDraft: false`).

---

## 28 de septiembre de 2026

### <span class="rn-tag rn-tag--improvement">Mejora</span> Status de la campaña en el listado

[Listar campañas](/docs/{lang}/api-reference/loyalty/campaign/list)

`GET /api/loyalty/campaign` ahora devuelve en cada fila un **`status` derivado**: `active`, `paused` o `finished`. Retrocompatible — nada de lo que ya venía cambió.

`finished` no es columna: en una campaña de audiencia es el envío terminado; en los demás disparadores es la vigencia (`finishAt`) vencida. ⚠️ `finished` **prevalece sobre `isActive`**: una campaña con la vigencia vencida y aún encendida aparece como terminada, no como activa. Es solo lectura — `isActive` no cambia.

Tres parámetros nuevos, todos opcionales: `status` filtra por ese status; `statusCounts=1` devuelve el conteo de cada uno con los mismos filtros `q[...]`; `sortByStatus=1` trae primero las activas, luego las pausadas y las terminadas.

---

## 24 de septiembre de 2026

### <span class="rn-tag rn-tag--breaking">Breaking change</span> Un token vencido ya no se acepta

[Obtener token](/docs/{lang}/api-reference/connect/api/get-token)

El `x-guper-authorization` presentado **después** de su `expiresIn` se aceptaba; ahora se rechaza con **`401`** y `Code: E0002`.

Ningún plazo se acortó — los vencimientos son los mismos de siempre y el endpoint de emisión no cambió. Si usted renueva el token cuando expira, no notará diferencia; si guardaba un token antiguo, llame de nuevo a [Obtener token](/docs/{lang}/api-reference/connect/api/get-token).

⚠️ Pedir un token nuevo **antes** de que expire el actual siempre estuvo permitido y no revoca el anterior.

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Audiencia dirigida por período

[Audiencia por período](/docs/{lang}/api-reference/loyalty/report/audience)

`GET /api/loyalty/report/audience/{start}/{end}`: a quién se dirigieron las campañas — el denominador de "de las personas a las que apuntamos, cuántas recibieron". El reporte de cards ya decía cuántas recompensas nacieron; faltaba el objetivo.

El trabajo está en unir **tres tablas con tres unidades distintas**. ⚠️ Última oportunidad encola por **card × campaña**, no por persona: contar filas ahí más que duplica la audiencia. Aquí ya viene deduplicado.

⚠️ Dos números, y solo uno es denominador: **`targeted`** (personas distintas por campaña, sumadas — empareja con recompensa otorgada) y **`clients`** (gente distinta, que nunca debe ser denominador). En una organización el mes pasado dos campañas de última oportunidad se dirigieron casi a las mismas personas: 77,429 direccionamientos para ~38.7 mil personas.

⚠️ Para cualquier tasa, pasa `type=monetary`: una campaña de notificación **puede** usar lista de audiencia — se dirige a gente y nunca genera recompensa, por diseño. Y un disparador sin objetivo (formularios, eventos externos) no aparece en la respuesta.

---

## 24 de septiembre de 2026

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Entrega y apertura por período

[Entrega por período](/docs/{lang}/api-reference/sender/report/delivery)

`GET /api/sender/report/delivery/{start}/{end}`: la misma lectura del reporte por campaña, pero en una ventana de fechas — de toda la organización o de una lista de campañas (`?sequence=`). Con `?groupBy=sequence` viene el desglose por campaña, ordenado por volumen. `?tz=` lee la frontera del día en la zona horaria de la organización (`insertedAt` se guarda en UTC).

Responde "cómo nos fue en septiembre" sin recorrer campaña por campaña.

### <span class="rn-tag rn-tag--improvement">Mejora</span> Un proveedor que no confirma entrega ya no tumba la tasa

[Entrega por campaña](/docs/{lang}/api-reference/sender/report/sequence-delivery)

Un proveedor sin webhook de entrega (hoy, push) se detiene en `sent` y nunca vuelve a hablar. Eso no es "no entregado", es entrega sin confirmación — pero contaba como una falla implícita. Ahora va al campo nuevo `unconfirmed`, **fuera de `attempted` y de ambas tasas**. En una organización con push en la mezcla, la tasa de entrega se movía sin que nada hubiera pasado; ahora mide solo lo que se puede medir.

`attempted` sigue siendo el denominador de las tasas; el total general que salió de la cola es el campo nuevo `sent` (= `attempted + unconfirmed`).

---

## 23 de septiembre de 2026

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Embudo de las campañas de notificación

[Embudo de notificación](/docs/{lang}/api-reference/loyalty/report/notifications)

`GET /api/loyalty/report/notifications/{start}/{end}` con `groupBy=campaign,day`: cuántas personas alcanzó el mensaje y cuántas de ellas compraron. Es el **denominador** que faltaba — el reporte de ventas dice cuánto generó el mensaje, no a qué costo de alcance.

Solo campaña `type=notification`: una campaña monetaria se atribuye por el **canje** del saldo, y su mensaje es un aviso de cashback. ⚠️ **Dos fechas, separadas en la respuesta**: `total` es la COHORTE (mensajes enviados en la ventana, seguidos donde sea que conviertan) y `total.result` es lo que PASÓ en la ventana — este último es el que conversa con la facturación influenciada del reporte de ventas.

⚠️ `notificationCard.attributionAt` **no** es la fecha de la atribución: se graba al nacer el card y está deprecada. Contar conversión por ella daría 100% siempre.

### <span class="rn-tag rn-tag--improvement">Mejora</span> El ranking por campaña y por origen devuelve el neto

[Reporte de ventas](/docs/{lang}/api-reference/order/report/sales)

`byCampaign` y `byOrigin` ahora traen `redeemed` y `revenueNet` junto al bruto. Quien exhibe reporta el neto, así que cada consumidor decidía solo — y una campaña que no emite saldo aparecía con facturación cero.

---

## 22 de septiembre de 2026

### <span class="rn-tag rn-tag--improvement">Mejora</span> Reporte de ventas: desglose y filtro por nivel, lista de tiendas y la alerta de descuento

[Reporte de ventas](/docs/{lang}/api-reference/order/report/sales)

`groupBy=tier` y `tier=Diamond|none` recortan por el **nivel del cliente al momento de la compra** (snapshot del pedido). ⚠️ `none` es el pedido sin snapshot — anónimo o no identificado —, que en una organización grande pasa de un tercio de la facturación: los niveles solos nunca cuadran con el total. El filtro vale también para la atribución y para el ranking de productos.

`store` ahora acepta **lista** (`store[]=207&store[]=208` o `207,208`, hasta 500), para filtrar por canal: canal es grupo de tienda, el grupo vive en register y quien llama resuelve el grupo en ids.

Cada línea de `byDay`, `byStore` e `byInterface` gana el `split` (atribuida x influenciada, en neto) que antes solo existía en el total.

Campo nuevo **`ordersDiscountOverRevenue`**: pedidos cuyo descuento es mayor que la propia venta, lo que es imposible para "precio de lista menos precio de venta". Revíselo antes de publicar cualquier razón hecha sobre `discounts` — en una organización son 27% de los pedidos, y con ellos adentro la razón da 67%.

---

## 21 de septiembre de 2026

### <span class="rn-tag rn-tag--breaking">Breaking change</span> `PUT /api/connect/user` exige `login`

[Actualizar usuario](/docs/{lang}/api-reference/connect/user/update-user)

La actualización de usuario ahora exige **`login`** junto con `personId`, y ambos deben pertenecer al mismo usuario: el `login` localiza el registro, el `personId` lo confirma.

Un par incorrecto no cambia nada y responde `404` (login inexistente) o `409` (el login es de otra persona); si falta uno de los dos campos, responde `400`. Solo `password`, `type` y `active` pueden cambiarse — el campo que omita se queda como está.

### <span class="rn-tag rn-tag--improvement">Mejora</span> Bloqueo por intentos en el acceso y en la emisión de token

[Autenticar](/docs/{lang}/api-reference/connect/user/auth) · [Obtener token](/docs/{lang}/api-reference/connect/api/get-token)

Después de **8 intentos fallidos en 15 minutos**, `POST /api/connect/auth`, `GET /api/connect/token` y la pantalla de consentimiento OAuth responden **`429`** y dejan de verificar la credencial durante los 15 minutos siguientes. Un acierto reinicia el contador.

La llave del bloqueo es distinta en cada caso: en el acceso es organización + `login`; en la emisión de token es la api-key + la IP de origen — por eso el bloqueo de un integrador **no afecta a los demás llamadores de la misma organización**.

La respuesta ante una credencial incorrecta también es ahora **siempre la misma** (`401`), para no revelar si el login existe.

## 18 de septiembre de 2026

### <span class="rn-tag rn-tag--improvement">Mejora</span> Venta atribuida, influenciada e impactada en el reporte de ventas

[Reporte de ventas](/docs/{lang}/api-reference/order/report/sales)

Con `withAttribution=true`, el bloque `attribution` agrega `split`, que separa los dos caminos por los que el programa llega a la venta, en pedidos distintos: `attributed` (el pedido canjeó saldo), `influenced` (el cliente solo recibió el mensaje de la campaña y compró, sin canjear) e `impacted` (la suma, que es el total del propio bloque). El pedido cae de un solo lado — recibir el mensaje **y** canjear cuenta como atribuido —, así que los dos lados suman exacto. Cada lado trae las mismas derivadas del total (`revenueNet`, `avgDiscount`, tickets).

El mismo bloque acepta ahora `attributionBy=store,interface`, que devuelve `byStore` / `byInterface` — la atribución desglosada por tienda y por canal, cada línea con las derivadas listas.

El filtro `campaign=` ahora acepta **500 ids** (antes 200).

---

## 17 de septiembre de 2026

### <span class="rn-tag rn-tag--improvement">Mejora</span> Política de canje: mínimo de compra dinámico (`minOrderRate`)

[Política de canje](/docs/{lang}/api-reference/loyalty/wallet/read) · [Acumulación por pedido](/docs/{lang}/api-reference/loyalty/checkout/reward-by-order)

La cartera gana `minOrderRate`: el pedido tiene que valer N veces el **saldo del cliente** para que el saldo pueda usarse (`3` con saldo de $30.00 exige una compra de $90.00). Es todo o nada y aplica por cartera, solo para cartera monetaria; `null` = sin regla, el comportamiento de siempre.

Cuando la regla bloquea el carrito, `redeemable.total` regresa `0` y el nuevo `redeemable.blocked` dice por qué, con `required` (cuánto tendría que valer el pedido) y `missing` (lo que falta) en centavos — permite mostrar "faltan $15.00 para usar tu saldo" en el POS. La clave solo aparece cuando hay bloqueo. `Actualizar transacción` vuelve a aplicar la regla: si el carrito baja del mínimo después de la cotización, el canje reservado se cae — cobre siempre por el `redeemable.total` de la última respuesta.

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Tiempo hasta el canje del cashback

[Tiempo hasta el canje](/docs/{lang}/api-reference/loyalty/report/redemption-latency)

`GET /api/loyalty/report/redemption-latency/{dateStart}/{dateEnd}` devuelve la distribución de días (`buckets=day`) o semanas (`buckets=week`) entre la liberación de la tarjeta (`basis=available`, por defecto) o su emisión (`basis=issued`) y el canje liquidado, con mediana y p90. Acepta los mismos filtros que el reporte de canjes.

---

## 16 de septiembre de 2026

### <span class="rn-tag rn-tag--improvement">Mejora</span> Reportes de cashback y de ventas: filtro por varias campañas

`loyalty.report.cards` y `loyalty.report.redemptions` ahora aceptan una lista en `campaign` (`campaign=191,171` o `campaign[]=191&campaign[]=171`); un solo id sigue funcionando. `order.report.sales` recibe el mismo `campaign`, junto con `withAttribution=true`: recorta solo el bloque de atribución (cada pedido cuenta una vez), y el total de ventas no cambia.

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Canjes de cashback con pedido y tiendas

[Canjes de cashback](/docs/{lang}/api-reference/loyalty/report/redemptions)

`GET /api/loyalty/report/redemptions/{dateStart}/{dateEnd}` lista los canjes liquidados, una fila por (canje, tarjeta), con el pedido, la tienda que emitió la tarjeta y la tienda del canje. Con `groupBy` (`day`, `month`, `campaign`, `originStore`, `redeemStore`) devuelve agregados — `groupBy=originStore,redeemStore` muestra la circulación del saldo entre tiendas. Acepta `cohort=redemption|issuance` y filtros por campaña, tiendas y cliente. Las filas están a nivel de tarjeta: no traen el valor del pedido, para que no se sume dos veces.

### <span class="rn-tag rn-tag--fix">Fix</span> Tarjetas de cashback: el canje cuenta solo cuando la venta se liquida

[Tarjetas de cashback](/docs/{lang}/api-reference/loyalty/report/cards)

`loyalty.report.cards` ahora cuenta como canjeado solo el saldo de ventas **liquidadas**. Las reservas abiertas en el checkout y las reservas canceladas aparecían en `redeemed`; ahora quedan fuera. Los períodos cerrados cambian muy poco.

### <span class="rn-tag rn-tag--improvement">Mejora</span> Tarjetas de cashback: tasa de conversión, uso parcial/total, `groupBy=day` y `cohort`

`loyalty.report.cards` ahora devuelve, en cada fila y en el total:

- `touchedCards` — tarjetas emitidas en el período con algún canje liquidado (parcial o total);
- `cardsRedeemedPartial` / `cardsRedeemedFull`, `partialShare` / `fullShare`;
- `usageRate` — la **tasa de conversión** (`touchedCards / (cards − cardsCanceled)`, en %);
- `cardsActive`, que cierra los grupos de estado contra `cards`.

Parámetros nuevos: `groupBy=day` (serie diaria, combinable con `store` o `campaign`) y `cohort=issuance`, que ubica `redeemed` por la emisión de la tarjeta ("qué pasó con lo que emití") en vez de la fecha del canje (`cohort=redemption`, por defecto). `cardsRedeemed` sigue siendo la tarjeta con saldo en cero y no debe usarse como conversión: una reversión también la deja en cero.

### <span class="rn-tag rn-tag--improvement">Mejora</span> Reportes de ventas y de campaña: descuento promedio y tickets bruto/neto

`order.report.sales?withAttribution=true` (en el bloque `attribution` y en cada fila de `byDay`) y `order.campaign.report` (en `total`) ahora devuelven `avgDiscount` (`redeemed / revenueGross`, razón), `averageTicketGross` (`revenueGross / orders`) y `averageTicketNet` (`revenueNet / orders`). Todos se calculan sobre **pedidos distintos**; la diferencia entre los dos tickets es el saldo promedio aplicado por pedido. Solo campos nuevos, nada se eliminó.

### <span class="rn-tag rn-tag--improvement">Mejora</span> Tier: elegir qué campañas suman puntos

En el origen `rewardCampaign` del `tier_config`, la nueva lista `sources.rewardCampaign.campaigns` define qué campañas suman puntos al tier. Sin la lista, todas las campañas siguen sumando (comportamiento anterior); con `[]`, ninguna suma. No es retroactivo: los puntos ya acreditados se mantienen.

```json
{ "sources": { "rewardCampaign": { "multiplier": 1, "expiresInDays": 365, "campaigns": [12, 40] } } }
```

También se corrigió la documentación de `sources`: es un objeto indexado por el nombre del origen, no una lista.

---

## 15 de septiembre de 2026

### <span class="rn-tag rn-tag--improvement">Mejora</span> Reporte de ventas: filtro `membership=member` (facturación de asociados)

`order.report.sales?membership=member` restringe a pedidos de miembros del programa (vía el snapshot `order_personMembership`), en el total y la atribución. Es la **facturación de asociados en el período**, companion de `register.report.members` (la base org-wide). Solo pedidos con snapshot (desde ~28/05/2026); no-miembro = `total − member`.

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Reporte de asociados / miembros del programa

[Asociados del programa](/docs/{lang}/api-reference/register/report/members)

En una llamada, quiénes son los asociados de un programa de lealtad: base activa,
composición por tier y origen, cuántos ya compraron (conversión lifetime) y valor
lifetime. Genérico por `tierConfig` (cualquier org):

```
GET /api/register/report/members?tierConfig=1
```

⚠️ El lente es **lifetime**, no un período: `conversionLifetime` = miembros que ya
compraron; `lifetimeValue` = gasto de vida. Facturación de asociados en un período es
`order.report.sales`. `meta.membershipStartedAt` dice desde cuándo hay miembros.

### <span class="rn-tag rn-tag--improvement">Mejora</span> Reporte de ventas: venta generada (neta) en la atribución

`order.report.sales?withAttribution` ahora devuelve **`revenueNet`** (= `revenueGross − redeemed`), la **venta generada** sobre la que Guper factura, en el total y la serie diaria, más `participationNet`. Antes solo estaba el bruto (`revenueGross`); reportarlo como "generado" daba por encima de la factura. Usa `revenueNet`.

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Productos más vendidos

[Productos más vendidos](/docs/{lang}/api-reference/order/report/products)

Para saber "qué se vendió más" ya no hace falta paginar los ítems y sumarlos de tu
lado. Una llamada ordena los ítems por producto, SKU, categoría o marca:

```
GET /api/order/report/products/2025-08-01/2025-08-31?groupBy=product
```

Devuelve unidades, ingreso de línea, pedidos y líneas — top N por ingreso, con `total`
cubriendo todo el período. `product`/`sku` funcionan hoy; `category`/`brand` ya quedan
listos y se llenan conforme la ingesta mejore (la respuesta trae la cobertura en
`meta`). Atención: `revenue` aquí es ingreso de **línea** (suma de price×quantity), no
el total del pedido — para facturación usa el reporte de ventas.

## 14 de septiembre de 2026

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> RFM por cohorte de adquisición

[RFM por cohorte](/docs/{lang}/api-reference/register/report/rfm-cohort)

Para analizar clientes por cohorte ya no hace falta traer cientos de miles de filas
de RFM y agruparlas de tu lado. Una llamada devuelve el RFM agregado por cohorte de
adquisición — por mes de la 1ª compra y/o tienda de adquisición:

```
GET /api/register/report/rfm-cohort/2025-01-01/2025-06-30?groupBy=month
```

Por cohorte: número de clientes, valor lifetime y promedio, promedio de compras,
cadencia de recompra y recencia. Valores en centavos; `total` reconcilia con la suma
de las filas. Atención: la tienda es la de **adquisición** y el valor es el gasto
lifetime **org-wide** del cliente (no ventas de la tienda — para eso usa el reporte
de ventas).

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Reporte de tarjetas de cashback (emitidas y canjeadas)

[Tarjetas de cashback](/docs/{lang}/api-reference/loyalty/report/cards)

Ver "todas las campañas" ya no requiere llamar el reporte por-campaña una por
una. Una llamada devuelve emisión y canje agrupados por mes, campaña, trigger o
tienda:

```
GET /api/loyalty/report/cards/2026-08-01/2026-08-31?groupBy=campaign
```

Devuelve tarjetas, crédito distribuido, canjeado, saldo y expiradas. Reconcilia
con el reporte de una campaña (misma cuenta). Valores en centavos; `rewardType`
separado (monetary por defecto).

### <span class="rn-tag rn-tag--improvement">Mejora</span> Reporte de ventas: canal, descuento y cohorte

El [reporte de ventas](/docs/{lang}/api-reference/order/report/sales) sumó
`groupBy=interface` (participación por canal), la métrica `discounts` y el filtro
`client` (una lista de clientes — cohorte/experimento).

## 10 de septiembre de 2026

### <span class="rn-tag rn-tag--improvement">Mejora</span> Regla de campana: el cliente es colaborador

[Crear regla de campana](/docs/{lang}/api-reference/loyalty/campaign/campaign-rules/create)

Nuevo `code` **19** (`collaborator`, alcance `campaign`): la campana ya puede
filtrar por el hecho de que el comprador sea colaborador de la organizacion. El
caso comun es el inverso — **el colaborador no acumula cashback** — que se
escribe con `reverse: true`.

```json
{ "campaign": 812, "code": 19, "params": [], "reverse": true }
```

La regla **no lleva `params`**: el sentido viene del `reverse`. `false` = solo
pasa el colaborador; `true` = el colaborador queda excluido.

La bandera que lee es `client.isCollaborator` del propio pedido — el mismo campo
que `rewardByOrder` acepta desde junio para marcar al comprador como
colaborador. **Un pedido que no trae la bandera cuenta como NO colaborador**, asi
que la regla con `reverse: true` no cambia nada para quien no lo envia.

La regla aplica en **campanas de compra**. En los demas triggers
(form-submission, last-chance, reactivate-reward) el cliente se arma desde el
registro, que no trae la bandera — ahi no tiene efecto.

### <span class="rn-tag rn-tag--improvement">Mejora</span> Lista de tarjetas ligera por defecto

[Listar tarjetas](/docs/{lang}/api-reference/loyalty/card/list) ya no embebe el
`flow` (historial de crédito/débito) en cada fila — eran ~1 KB por tarjeta, lo
que hacía inviable la extracción en lote. La lista sale ligera; para el ledger
usa el endpoint de flow o pasa `withFlow=true` (solo conviene para una tarjeta o
una página chica). El `status` de cada tarjeta sigue en la lista.

## 9 de septiembre de 2026

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Listado de pedidos con el pedido completo

[Listar pedidos (completo)](/docs/{lang}/api-reference/order/order/list-full)

El listado de pedidos devuelve filas resumidas; para ver articulos, pagos,
campanas, historial, tienda y cliente hacia falta un `GET` por pedido. Ahora
puede pedir la pagina ya detallada:

```
GET /api/order/data/full?q[status][E]=paid&e=20
```

Mismos filtros, orden y paginacion que el listado normal, y cada fila trae el
**mismo payload** que `GET /api/order/data/{idOrder}`. Tambien existe la variante
por interface: `GET /api/order/{interface}/data/full`, ya traducida a los refIds.

Limite de 50 filas por pagina - cada fila carga sus propios articulos y pagos,
asi que `e=0` significaria todo el historial en una sola respuesta.

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> NPS / CSAT por tienda (consolidado)

[NPS por tienda](/docs/{lang}/api-reference/register/report/feedback-nps)

"NPS por tienda" ya no requiere paginar las evaluaciones y sumar tienda por
tienda. Una llamada devuelve el NPS general y el desglose por tienda:

```
GET /api/register/report/feedbackNps?days=90
```

Cada fila trae los componentes crudos (promotores/neutros/detractores), el `nps`,
el `avgRating` y cuántas llegaron sin vendedor. Filtra por `type` (nps/csat),
`store` y período (`days` o `dateStart`/`dateEnd`).

## 8 de septiembre de 2026

### <span class="rn-tag rn-tag--improvement">Mejora</span> Reporte de ventas: comparación de períodos

El [reporte de ventas](/docs/{lang}/api-reference/order/report/sales) sumó el
parámetro `compareWith`:

```
GET /api/order/report/sales/2026-08-01/2026-08-31?groupBy=month&compareWith=previous
```

`previous` (ventana del mismo tamaño justo antes), `previousYear` (las mismas
fechas un año atrás) o un rango `YYYY-MM-DD..YYYY-MM-DD`. La respuesta agrega un
bloque `comparison` con el total del período base y el `delta` (absoluto y %) en
pedidos, facturación y ticket — suficiente para responder *"vendió X, +12% vs el
mes pasado"*.

## 6 de septiembre de 2026

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Entrega y tasa de apertura por campaña

[Entrega y apertura](/docs/{lang}/api-reference/sender/report/sequence-delivery)

Saber la tasa de apertura de una campaña ya no requiere recorrer el log mensaje
por mensaje (que expiraba). Este endpoint agrega por canal y en total,
referenciado por el `messageSequence` que lleva la campaña:

```
GET /api/sender/report/sequence-delivery/e4dc1e58-lojas-expirados-whats
```

Devuelve `opened`, `delivered`, `failed`, `attempted` y las tasas de entrega y
apertura. `opened` = email abierto (Mailgun) o WhatsApp leído. El conteo es **por
secuencia**: dos campañas que comparten el mismo `messageSequence` se suman aquí.

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Reporte de ventas agregado

[Reporte de ventas](/docs/{lang}/api-reference/order/report/sales)

Para saber "cuánto vendí ayer por tienda" o "facturación por día en el mes" ya no
hace falta paginar `/order/data` y sumar del lado del cliente — ahora hay un
endpoint que devuelve el número.

```
GET /api/order/report/sales/2026-08-01/2026-08-31?groupBy=day,store
```

Agrega por `day`, `month`, `store` o combinaciones, filtra por tienda y por
estado. Tres decisiones importan: los **ingresos son netos de cancelación** por
defecto (pero el bloque `byStatus` siempre reporta todos los estados, incluido el
cancelado, para que lo excluido siga siendo auditable); el **día se corta de
`order_date` convertido a la zona horaria de la organización** (la venta cae en el
día en que ocurrió, no en el del sync); y `updatedThrough` reporta el mayor
`createAt` que entró en el cálculo — como el pedido llega después de la venta,
"ayer" es un número mutable.

Valores en centavos.

### <span class="rn-tag rn-tag--deprecated">Deprecación</span> financeSumary

`financeSumary` sumaba pedidos cancelados, perdía el último día del período y
agrupaba en UTC. Usa el [reporte de ventas](/docs/{lang}/api-reference/order/report/sales)
en su lugar (`groupBy=month` cubre su caso).

## 2 de septiembre de 2026

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Opt-out: registrar quién no quiere ser contactado

[Registrar](/docs/{lang}/api-reference/sender/opt-preference/create) ·
[Consultar](/docs/{lang}/api-reference/sender/opt-preference/lookup) ·
[Revocar](/docs/{lang}/api-reference/sender/opt-preference/delete) ·
[Listar](/docs/{lang}/api-reference/sender/opt-preference/list) ·
[Contar](/docs/{lang}/api-reference/sender/opt-preference/count) ·
[Historial](/docs/{lang}/api-reference/sender/opt-preference/history)

No había dónde registrar al cliente que pide dejar de recibir mensajes. Ahora sí.

Registre **todos los identificadores que tenga** — persona, correo y teléfono:

```
POST /api/sender/opt-preference
{ "person": 184532, "email": "cliente@exemplo.com",
  "cellphone": "5512345678", "countryCallingCode": "52" }
```

Se guarda una fila por identificador y el envío se bloquea cuando **cualquiera** de ellos
coincide. Ese es el punto: si el cliente se registra otra vez y obtiene un person id nuevo, el
correo y el teléfono siguen coincidiendo, así que el opt-out sobrevive al registro nuevo. Si en
cambio cambia de correo dentro del mismo registro, el objetivo de persona sigue coincidiendo.

**El opt-out es por organización.** El mismo correo puede estar bloqueado en una organización
y seguir recibiendo en otra — nunca cruza organizaciones.

**Todo se bloquea, excepto el PIN de inicio de sesión.** Esa es la única excepción — bloquearlo
dejaría al cliente fuera de su propia cuenta.

`countryCallingCode` es **obligatorio siempre que se envíe `cellphone`**. La clave guardada es
código de país + dígitos; sin él la clave sería distinta de la que consulta el envío y el
opt-out no haría nada, en silencio.

El bloqueo aplica a todas las organizaciones desde el inicio. La lista comienza vacía, así que
nada se bloquea hasta que un cliente realmente lo pida — cada bloqueo corresponde a una
solicitud explícita.

## 27 de agosto de 2026

### <span class="rn-tag rn-tag--breaking">Breaking change</span> El status del canje ahora es `redeemed`, no `rescued`

[Redeem: Settle](/docs/{lang}/api-reference/loyalty/redeem/settle)

La palabra `rescued` sugeria rescate en el sentido de salvamento, no de canjear
un saldo. El estado liquidado pasa a llamarse `redeemed` en todos lados.

**La clave de la respuesta cambia.** El status es la *clave* dentro de `redeem`,
no un valor — asi que esto es un cambio de forma, no de string:

```
antes    {"organization": "acme", "person": 184532, "redeem": {"rescued": 1500},  "dateTime": "..."}
despues  {"organization": "acme", "person": 184532, "redeem": {"redeemed": 1500}, "dateTime": "..."}
```

Quien lea `response.redeem.rescued` recibira `undefined`. Usa
`response.redeem.redeemed` — o, para sobrevivir a ambos, toma la unica clave del
objeto `redeem` en vez de fijar el nombre.

**`redeemedStatus` tambien cambia.** El listado de movimientos de la tarjeta
devuelve el valor almacenado directamente, asi que pasa de `"rescued"` a
`"redeemed"`.

El historico se migro en la misma ventana, por lo que no hay periodo en que los
dos terminos convivan en el dato almacenado. `reserved` y `canceled` no cambian.

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> `POST /redeem/settle/{hash}` liquida una reserva de canje

[Redeem: Settle](/docs/{lang}/api-reference/loyalty/redeem/settle)

Liquidar una reserva de canje ahora tiene una ruta cuyo nombre dice lo que
hace:

```
POST /api/loyalty/redeem/settle/{hash}
```

Convierte un hold `reserved` en un débito final, igual que antes — mismo
handler, misma respuesta. El `{hash}` es el id de la transacción, no el de una
tarjeta: una llamada liquida todas las tarjetas retenidas por esa reserva.

Es `POST` porque la llamada **cambia estado** — graba el status, escribe el log
y dispara la atribución de campaña. La ruta anterior era `GET`, lo que no se
sostiene con prefetch, crawlers ni reintentos automáticos.

### <span class="rn-tag rn-tag--deprecated">Deprecación</span> `GET /redeem/rescue/{hash}`

[Redeem: Settle](/docs/{lang}/api-reference/loyalty/redeem/settle)

Reemplazada por `POST /api/loyalty/redeem/settle/{hash}`. La ruta anterior
**sigue funcionando** y no tiene remoción agendada, pero salió de la
documentación.

`rescue` sugería rescate en el sentido de salvamento, no de canjear un saldo —
al punto de que las traducciones del panel habían invertido el significado. El
término del ciclo es `reserved → redeemed`, con `settle` como acción.

La migración es la URL y el verbo. Request y response no cambian: la respuesta
sigue trayendo `"status": "rescued"`, ya que el valor almacenado no cambió en
esta versión.

---

## 26 de agosto de 2026

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Guper por IA: inicio de sesión por persona con OAuth 2.1

[Guper por IA (MCP)](/docs/{lang}/guides/mcp)

Cada organización pasa a tener una dirección que los asistentes de IA
compatibles con MCP entienden — `https://{organization}.myguper.com/mcp`. La
persona pega la dirección en el asistente, entra con **el mismo inicio de sesión
del panel**, y el asistente opera Guper con **exactamente los permisos que ya
tiene**.

Viene acompañado de un authorization server OAuth 2.1 con PKCE en `connect`:

- `GET /.well-known/oauth-authorization-server/api/connect` — discovery
- `POST /api/connect/oauth/register` — registro dinámico de cliente
- `GET` y `POST /api/connect/oauth/authorize` — autorización
- `POST /api/connect/oauth/token` — canje del code y renovación
- `POST /api/connect/oauth/revoke` — revocación
- `GET /api/connect/oauth/jwks` — llave pública

El token es un JWT cuyo `aud` es la URI canónica del recurso de la organización,
y cuyo `scope` trae los permisos del perfil de la persona en el panel. Un token
emitido para una organización no vale en otra.

**Nada cambia para quien ya integra.** `apiKey`/`apiSecret` → token → llamadas
siguen idénticos, y ningún endpoint existente fue alterado. El camino nuevo
queda al lado, para cuando el acceso sea de una persona y deba respetar su
perfil.

---

## 19 de agosto de 2026

### <span class="rn-tag rn-tag--fix">Fix</span> `confirmOrder` ya no anuncia acumulación en venta anónima

[Confirmar pedido por token](/docs/{lang}/api-reference/loyalty/checkout/confirm-order-by-confirmtoken)

Cuando el pedido se confirma sin cliente identificado no hay a quién acreditar
— no se crea ningún reward card. Aun así, `cashback.accumulatedOrder` venía con
el valor **previsto**, no con lo que se acreditó. Quien leía ese campo le
mostraba al consumidor una acumulación que nunca existió.

Ahora, en la venta anónima, `redeemedOrder` y `accumulatedOrder` regresan `0`.
La clave `cashback` sigue presente y con los mismos tipos — nada cambia para
quien ya lee el campo, salvo que el número ahora corresponde a la realidad.

La venta con cliente identificado no cambia. Tampoco la campaña con
beneficiario propio (referido, colaborador): ahí el crédito sí ocurre aunque no
haya comprador identificado, y el valor se preserva.

En el mismo paso se corrigió la página de referencia — todavía mostraba una
respuesta sin `customerId` y sin `redeemedOrder`, campos que el servicio ya
devolvía. Ahora documenta ambos casos, identificado y anónimo.

### <span class="rn-tag rn-tag--breaking">Breaking change</span> `GET /api/loyalty/redeem/cancel/{hash}` fue eliminado

Use [Transaction · Cancel](/docs/{lang}/api-reference/loyalty/transaction/cancel) en su lugar.

El endpoint dejó de existir — la llamada ahora responde `404`.

Era redundante: `POST /api/loyalty/transaction/cancel/{TID}` pasa por el
mismo proceso interno de devolución de la reserva, y cubre también el
caso que atendía el `redeem/cancel` — liberar un canje reservado en el
checkout que nunca se convirtió en pedido (carrito abandonado, falla de
pago). Como en ese escenario todavía no hubo acumulación, no hay nada
que debitar: solo la reserva vuelve al saldo del cliente.

No se espera que ninguna integración se vea afectada — la ruta no
recibió una sola llamada en producción desde el 15 de mayo de 2025. Si
aun así tiene código llamando a ese path, la migración es cambiar la URL
por `transaction/cancel`, usando el mismo identificador de transacción.

**Antes**

```
GET /api/loyalty/redeem/cancel/{hash}
```

**Ahora**

```
POST /api/loyalty/transaction/cancel/{TID}
```

---

## 25 de junio de 2026

### <span class="rn-tag rn-tag--improvement">Mejora</span> Nuevo prefijo `/mdw/vtex/*` en el middleware (alinea con otros `mdw_*`)

El servicio `middleware` ahora acepta un nuevo prefijo de path —
`/mdw/vtex/*` — equivalente al legado `/api/middleware/*`. Ambos
atienden el mismo backend con request/response idénticos. Use el nuevo
para integraciones nuevas; el legado sigue funcionando.

Ejemplos:

- `GET /api/middleware/interface/by/slug/ecommerce` (legado)
- `GET /mdw/vtex/interface/by/slug/ecommerce` (preferido)

Motivación: alinear con los otros adaptadores de integración
(`/mdw/clip`, `/mdw/shopify/front`) y abrir camino para depreciar el
prefijo `/api/middleware` en el futuro — sin ventana de coordinación
forzada (cada consumer migra a su ritmo).

---

## 24 de junio de 2026

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Nuevo servicio `integration` — gestión de las integraciones activadas por org

La identidad de las integraciones fue movida del middleware a un
servicio propio. Reemplaza `/api/middleware/interface/*` y
`/api/middleware/source` (que se quedaron como facade signed al nuevo
servicio — retrocompatible, pero los nuevos consumidores deben usar
`/api/integration/*` directamente).

**`source`** — catálogo global de tipos de integración (vtex, shopify, cegid, polishop, ...). Lectura abierta; escritura restringida a servicios Guper internos.

- `GET /api/integration/source`
- `GET /api/integration/source/{id}`

**`interface`** — instancias activadas por la org (ej. la org tiene VTEX `ecommerce` + Linx `loja-fisica`). La org viene implícita del header signature.

- `GET    /api/integration/interface` — lista interfaces de la org
- `GET    /api/integration/interface/{id}` — lectura por id
- `GET    /api/integration/interface/by/slug/{slug}` — lectura por slug (hot path)
- `GET    /api/integration/interface/by/source/{source}` — lista interfaces de un tipo (ej. todas las VTEX de la org)
- `POST   /api/integration/interface` — crea interface
- `PUT    /api/integration/interface/{id}` — actualiza (`activated` acepta boolean: `true` activa, `false` desactiva)
- `DELETE /api/integration/interface/{id}` — elimina interface

### <span class="rn-tag rn-tag--deprecated">Depreciación</span> `/api/middleware/interface/*` y `/api/middleware/source`

Permanecen funcionando como facade transparente (proxy signed al
`integration`) — no hay quiebre inmediato. Migre consumidores a
`/api/integration/*` directamente; la remoción del facade se anunciará
con antelación.

---

## 23 de junio de 2026

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Endpoints external_ref en `catalog` (brand, category, seller)

Patrón `/api/catalog/{interface}/{resource}/...` para mapear refIds
externos (`vtex`, `shopify`, `cegid`, ...) a brands, categories y
sellers. Reemplaza el mapeo legado vía middleware (ver entrada de
Deprecación abajo).

Por resource (`brand`, `category`, `seller`):

- `GET    /api/catalog/{interface}/{resource}` — lista los refs de la org para la interface
- `GET    /api/catalog/{interface}/{resource}/{refId}` — lectura por refId externo
- `POST   /api/catalog/{interface}/{resource}` — find-or-create (crea entidad + ref)
- `PUT    /api/catalog/{interface}/{resource}/{refId}` — enlaza a entidad existente
- `DELETE /api/catalog/{interface}/{resource}/{refId}` — elimina sólo el ref (la entidad queda)
- `POST   /api/catalog/{interface}/{resource}/_resolve` — bulk lookup (hasta 500 refIds, devuelve mapa `refId → id|null`)

### <span class="rn-tag rn-tag--new">Nuevo endpoint</span> Endpoints external_ref en `register` (payment, person con role)

Patrón `/api/register/{interface}/{resource}/...` para mapear refIds
externos a payments y persons. Reemplaza el mapeo legado vía middleware
(ver entrada de Deprecación abajo).

**payment** sigue la misma forma de catalog:

- `GET    /api/register/{interface}/payment`
- `POST   /api/register/{interface}/payment` — find-or-create
- `GET    /api/register/{interface}/payment/{refId}`
- `PUT    /api/register/{interface}/payment/{refId}` — link
- `DELETE /api/register/{interface}/payment/{refId}`
- `POST   /api/register/{interface}/payment/_resolve`

**person tiene `role` en el path** (`cashier`, `salesperson`, `manager`, `client`):

- `GET    /api/register/{interface}/person/{role}` — lista
- `GET    /api/register/{interface}/person/{role}/{refId}` — lectura
- `PUT    /api/register/{interface}/person/{role}/{refId}` — enlaza a persona existente
- `DELETE /api/register/{interface}/person/{role}/{refId}`
- `POST   /api/register/{interface}/person/{role}/_resolve`

`role` en la PK permite que el mismo `refId` mapee personas distintas en
contextos distintos (ej.: `refId=99` como `cashier` apunta a una persona
y como `salesperson` a otra).

### <span class="rn-tag rn-tag--improvement">Mejora</span> `seller` movido de `register` a `catalog`

Conceptualmente, seller es una dimensión de catálogo (dueño de
inventario y productos, igual que brand y category), no de cadastro. La
entidad fue movida a catalog y el endpoint canónico ahora es
`/api/catalog/seller/*`.

`/api/register/seller/*` permanece como **alias retrocompatible** — los
endpoints siguen respondiendo igual pero internamente hacen proxy a
catalog. Los consumidores existentes (storeManager, smartPOS, admin) no
necesitan cambiar nada ahora.

El código nuevo debe usar `/api/catalog/seller/*` directamente.

### <span class="rn-tag rn-tag--deprecated">Deprecación</span> Endpoints `/api/middleware/{interface}/{resource}` Reference

Los endpoints CRUD de mapeo de refIds externos en el middleware fueron
deprecados:

- `/api/middleware/{interface}/brand`
- `/api/middleware/{interface}/category`
- `/api/middleware/{interface}/seller`
- `/api/middleware/{interface}/payment`
- `/api/middleware/{interface}/cashier`
- `/api/middleware/{interface}/salesperson`
- `/api/middleware/{interface}/manager`
- `/api/middleware/{interface}/client`

Usá los equivalentes en `catalog` (brand/category/seller) o `register`
(payment/person/{role}) — ver entradas arriba. Los endpoints legados
siguen funcionando durante la migración; el middleware hace dual-write,
manteniendo ambos caminos sincronizados. Serán eliminados en una release
futura, con aviso anticipado.

---

## 16 de junio de 2026

### <span class="rn-tag rn-tag--deprecated">Deprecación</span> `GET /api/loyalty/reward` (Reward Directo: Saldo) fue deprecado

Para el saldo por cliente, usá [Report · Saldo por persona](/docs/{lang}/api-reference/loyalty/report/reward-balances-by-person).

El endpoint `GET /api/loyalty/reward` leía sus parámetros de un **body
JSON** en un GET (comportamiento poco confiable en varios clientes y
proxies) y dependía de una interface de middleware configurada por
organización. No tenía consumidores activos y ya estaba marcado como
no funcional en el código.

Su página de referencia fue removida. Para obtener el saldo de reward
cards de un cliente, usá `GET /api/loyalty/report/rewardBalances/person/{person}`
— recibe el id de persona en la URL, no requiere body y devuelve el
detalle `available / expired / canceled / used` por wallet.

---

## 12 de mayo de 2026

### <span class="rn-tag rn-tag--breaking">Breaking change</span> `GET /api/loyalty/transaction/byOrder/{idOrder}` ahora devuelve una lista de transacciones

[Transaction · By Order](/docs/{lang}/api-reference/loyalty/transaction/by-order)

Un pedido puede legítimamente cargar más de una transacción de loyalty
— acumulación y canje emitidos por flujos separados, cancelaciones
parciales, retries en el mismo checkout. El endpoint devolvía una
única transacción en el nivel raíz, ocultando el caso de múltiples.

La respuesta ahora lleva la lista completa bajo `transactions: [...]`,
ordenada de la más antigua a la más reciente.

**Antes**

```json
{
    "TID":        "dcf33b44…",
    "order":      2467383,
    "person":     570971,
    "canceledAt": null,
    "createdAt":  "2026-01-15T16:21:44-03:00"
}
```

**Después**

```json
{
    "order":     2467383,
    "refId":     "GUP-847",
    "interface": "vtex",
    "transactions": [
        {
            "TID":        "dcf33b44…",
            "person":     570971,
            "canceledAt": null,
            "createdAt":  "2026-01-15T16:21:44-03:00"
        },
        {
            "TID":        "8c91a2b3…",
            "person":     570971,
            "canceledAt": "2026-01-20T09:14:00-03:00",
            "createdAt":  "2026-01-15T17:02:11-03:00"
        }
    ]
}
```

Si tu integración leía `body.TID` en el nivel raíz, itera ahora por
`body.transactions[]` y elige el TID que necesites (típicamente el
más reciente no cancelado).

Disponible a partir de `loyalty v0.48.81`.
