Entrar
.md

Notas de release

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

Cada entrada tiene una etiqueta:

  • Breaking change — el contrato de request o response cambió; las integraciones deben adaptarse.
  • Nuevo endpoint — endpoint añadido.
  • Mejora — cambio retrocompatible.
  • Fix — corrige comportamiento erróneo sin cambiar el contrato.
  • Deprecación — endpoint descontinuado; migrá a la alternativa indicada.

12 de noviembre de 2026

Mejora Saldo vencido en el reporte de cards

Cashback emitido y canjeado por campaña (agregado)

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

Nuevo endpoint Actualizar clientes en lote

Actualizar clientes en lote

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.

Nuevo endpoint Cancelar y reactivar cards en lote

Cancelar cards en lote · Reactivar cards en lote

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

Nuevo endpoint Cancelar y reactivar card

Cancelar card · Reactivar card

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

5 de noviembre de 2026

Mejora Fecha del pedido en Reward by Order

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

Mejora Audiencia por card activo

Consultar audiencia (QON)

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

Nuevo endpoint Los refIds de una entidad, sin recorrer la interfaz

Listar refs de una Categoría · de una Marca · de un Vendedor · de un Pago

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.

Corrección 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).

Mejora Reporte de productos desglosado por tienda y por tiempo

Productos más vendidos

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

Nuevo endpoint Valide su payload antes de integrar

Valide su payload

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

Mejora "Diferente de" en la regla Tipo de entidad

Reglas de campaña: Crear

La regla de campaña Tipo de entidad (code 11) 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

Mejora Listar mensajes por teléfono, con el cuerpo, en una llamada

Messages: Listar

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.

Mejora Tipo de compra en rewardByOrder

Recompensa por pedido

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) 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

Mejora El ingreso descompuesto, del precio de lista al neto

Reporte de ventas

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

Nuevo endpoint Sincronizar vínculos tienda ↔ política

Sincronizar vínculos tienda ↔ política

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.

Mejora Las políticas de canje compiten entre sí

Políticas de canje

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

Mejora Permisos por api-key

Conceder scopes al acceso

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

Mejora Campañas en borrador

Listar campañas

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

Mejora Status de la campaña en el listado

Listar campañas

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

Breaking change Un token vencido ya no se acepta

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

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

Nuevo endpoint Audiencia dirigida por período

Audiencia por período

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

Nuevo endpoint Entrega y apertura por período

Entrega por período

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.

Mejora Un proveedor que no confirma entrega ya no tumba la tasa

Entrega por campaña

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

Nuevo endpoint Embudo de las campañas de notificación

Embudo de notificación

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.

Mejora El ranking por campaña y por origen devuelve el neto

Reporte de ventas

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

Mejora Reporte de ventas: desglose y filtro por nivel, lista de tiendas y la alerta de descuento

Reporte de ventas

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

Breaking change PUT /api/connect/user exige login

Actualizar usuario

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

Mejora Bloqueo por intentos en el acceso y en la emisión de token

Autenticar · Obtener 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

Mejora Venta atribuida, influenciada e impactada en el reporte de ventas

Reporte de ventas

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

Mejora Política de canje: mínimo de compra dinámico (minOrderRate)

Política de canje · Acumulación por pedido

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.

Nuevo endpoint Tiempo hasta el canje del cashback

Tiempo hasta el canje

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

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

Nuevo endpoint Canjes de cashback con pedido y tiendas

Canjes de cashback

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.

Fix Tarjetas de cashback: el canje cuenta solo cuando la venta se liquida

Tarjetas de cashback

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.

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

Mejora 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ó.

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

{ "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

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

Nuevo endpoint Reporte de asociados / miembros del programa

Asociados del programa

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.

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

Nuevo endpoint Productos más vendidos

Productos más vendidos

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

Nuevo endpoint RFM por cohorte de adquisición

RFM por cohorte

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

Nuevo endpoint Reporte de tarjetas de cashback (emitidas y canjeadas)

Tarjetas de cashback

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

Mejora Reporte de ventas: canal, descuento y cohorte

El reporte de ventas 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

Mejora Regla de campana: el cliente es colaborador

Crear regla de campana

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.

{ "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.

Mejora Lista de tarjetas ligera por defecto

Listar tarjetas 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

Nuevo endpoint Listado de pedidos con el pedido completo

Listar pedidos (completo)

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.

Nuevo endpoint NPS / CSAT por tienda (consolidado)

NPS por tienda

"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

Mejora Reporte de ventas: comparación de períodos

El reporte de ventas 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

Nuevo endpoint Entrega y tasa de apertura por campaña

Entrega y apertura

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

Nuevo endpoint Reporte de ventas agregado

Reporte de ventas

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.

Deprecación financeSumary

financeSumary sumaba pedidos cancelados, perdía el último día del período y agrupaba en UTC. Usa el reporte de ventas en su lugar (groupBy=month cubre su caso).

2 de septiembre de 2026

Nuevo endpoint Opt-out: registrar quién no quiere ser contactado

Registrar · Consultar · Revocar · Listar · Contar · Historial

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

Breaking change El status del canje ahora es redeemed, no rescued

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.

Nuevo endpoint POST /redeem/settle/{hash} liquida una reserva de canje

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.

Deprecación GET /redeem/rescue/{hash}

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

Nuevo endpoint Guper por IA: inicio de sesión por persona con OAuth 2.1

Guper por IA (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

Fix confirmOrder ya no anuncia acumulación en venta anónima

Confirmar pedido por token

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.

Breaking change GET /api/loyalty/redeem/cancel/{hash} fue eliminado

Use 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

Mejora 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

Nuevo endpoint 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

Depreciación /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

Nuevo endpoint 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)

Nuevo endpoint 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).

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

Deprecación 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

Deprecación GET /api/loyalty/reward (Reward Directo: Saldo) fue deprecado

Para el saldo por cliente, usá Report · Saldo por persona.

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

Breaking change GET /api/loyalty/transaction/byOrder/{idOrder} ahora devuelve una lista de transacciones

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

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

Después

{
    "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.