---
title: 'Notas de release'
description: 'Mudanças de comportamento, novos endpoints e fixes entregues na API Guper. Mais recentes em cima.'
---

# Notas de release

Mudanças de comportamento, novos endpoints e fixes entregues na API
Guper. Mais recentes em cima.

Cada entrada tem uma tag:

- <span class="rn-tag rn-tag--breaking">Breaking change</span> — contrato de request ou response mudou; integrações precisam adaptar.
- <span class="rn-tag rn-tag--new">Novo endpoint</span> — endpoint adicionado.
- <span class="rn-tag rn-tag--improvement">Melhoria</span> — mudança retrocompatível.
- <span class="rn-tag rn-tag--fix">Correção</span> — corrige comportamento errado sem mudar o contrato.
- <span class="rn-tag rn-tag--deprecated">Depreciação</span> — endpoint descontinuado; migre para a alternativa indicada.

---

## 12 de novembro de 2026

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Saldo vencido no relatório de cards

[Cashback emitido e resgatado por campanha (agregado)](/docs/{lang}/api-reference/loyalty/report/cards)

`GET /api/loyalty/report/cards` agora devolve **`expiredBalance`** em cada linha e no `total`: o saldo que sobrou nos cards vencidos — quanto crédito se perdeu por não ser usado a tempo. Mesmo corte do `cardsExpired`; em centavos, como os outros valores. Também novo: **`touchedRedeemed`**, o valor resgatado pelos mesmos cards contados em `touchedCards` (em qualquer data). O `redeemed` segue cortando pela data do resgate. Campos novos, nada mais mudou.

## 11 de novembro de 2026

### <span class="rn-tag rn-tag--new">Novo endpoint</span> Atualizar clientes em lote

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

`PUT /api/register/customer/batch` atualiza **vários clientes numa chamada** — uma lista `items` de `{id, ...campos}`. Setar `entityType=legal` em centenas de clientes, ou importar valores por cliente, deixa de ser centenas de chamadas.

Cada item reusa o **mesmo caminho do update único** (mesma sanitização e validação; só `id` é obrigatório por item). Um item ruim não derruba o lote: a resposta traz um `outcome` por item (`updated` / `not_found` / `rejected` com o motivo) e um `summary`. Passe **`dryRun: true`** para validar sem gravar (`would_update`). Até **100 itens** por chamada.

### <span class="rn-tag rn-tag--new">Novo endpoint</span> Cancelar e reativar cards em lote

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

`POST /api/loyalty/cards/cancel` e `POST /api/loyalty/cards/reactivate` processam **até 100 cards por chamada** — cancelar 3.000 cards deixa de ser 3.000 chamadas e passa a ser 30.

Os `ids` aceitam faixa e itens avulsos na mesma sintaxe das collections: `"1512200:1512299;1512305"` são os cards de 1512200 a 1512299 mais o 1512305. Um array também é aceito. O teto de 100 vale para o conjunto expandido, e a faixa nunca atravessa organizações — id de outra conta volta `not_found` e fica intocado.

Falha parcial é tratada como normal: a resposta é `200` com o desfecho de **cada** id (`canceled`, `already_canceled`, `has_open_reservation`, `not_found`), e o `400` fica só para pedido malformado. Um card já cancelado ou com reserva aberta não derruba o resto do lote.

Rode antes com `dryRun: true`: ele mostra o que aconteceria item a item e **quanto saldo sairia de circulação**, sem escrever nada. A resposta traz um `batchId`, que amarra os cards de uma mesma operação.

## 9 de novembro de 2026

### <span class="rn-tag rn-tag--new">Novo endpoint</span> Cancelar e reativar card

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

Cancelar um card agora tem endpoint próprio: `POST /api/loyalty/cards/{id}/cancel` tira o card de circulação — ele sai de toda consulta de saldo e passa a ser lido como `canceled` —, e `POST /api/loyalty/cards/{id}/reactivate` desfaz. Até aqui o cancelamento por API só existia no nível da transação (`transaction/cancel`), que reverte o que uma compra gerou; o alvo agora pode ser o card, sem relação com pedido: card de campanha concedido por engano, card manual, card que a operação precisa encerrar.

Cancelar card é mudança de **estado**, não movimento: o saldo não é debitado nem devolvido e nada entra no ledger de flow do card. Para tirar valor de um card que continua vivo, siga usando [Ajustar saldo do card](/docs/{lang}/api-reference/loyalty/card/adjust) com `manual_debit`.

Card com reserva de resgate aberta é recusado com `409` (o valor reservado espera liquidação ou devolução), e um segundo cancelamento também responde `409`. Detalhes e a comparação com o cancelamento de transação estão no guia [Cancelamento no loyalty](/docs/{lang}/guides/loyalty-cancellation).

## 5 de novembro de 2026

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Data do pedido no Reward by Order

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

O `rewardByOrder` passa a documentar e validar o campo `creationDate`, a data e hora do pedido em ISO 8601 (ex.: `2026-11-02T10:00:00-06:00`). Envie quando a compra aconteceu antes da chamada: as campanhas consideradas são as que estavam ativas **naquela data**, a validade do card conta a partir dela e é ela que fica como data do pedido na transação. Sem o campo, nada muda: vale o horário da chamada.

Valor ilegível, data inexistente (ex.: `2026-02-31`) ou mais de um dia no futuro agora retorna `400`. Antes, um valor assim era ignorado no cálculo e o pedido podia não ser registrado na confirmação.

## 4 de novembro de 2026

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Audiência por card ativo

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

Dois campos novos no motor de audiência: `hasActiveCard` (tem pelo menos um card com saldo, já valendo e dentro da validade) e `activeCardExpiresWithinDays` (tem card ativo que vence nos próximos N dias). Ex.: `[{"col": "activeCardExpiresWithinDays"}, "inNextDays", {"int": 7}]` é a audiência do "seu cashback vence esta semana". O saldo é lido na hora, então quem acabou de resgatar tudo já sai da audiência.

## 26 de outubro de 2026

### <span class="rn-tag rn-tag--new">Novo endpoint</span> Os refIds de uma entidade, sem varrer a interface

[Listar refs de uma Categoria](/docs/{lang}/api-reference/catalog/category/by-entity/list) · [de uma Marca](/docs/{lang}/api-reference/catalog/brand/by-entity/list) · [de um Vendedor](/docs/{lang}/api-reference/catalog/seller/by-entity/list) · [de um Pagamento](/docs/{lang}/api-reference/register/payment/by-entity/list)

Já dava para ir de `refId` para a entidade (`GET /api/{service}/{interface}/{resource}/{refId}`); faltava o caminho de volta. Agora `GET /api/catalog/category-external-ref/by-category/{categoryId}` — e os equivalentes de marca, vendedor e pagamento — devolve **todos os refIds daquela entidade, um por interface**, sem precisar listar a interface inteira e filtrar no cliente.

Devolve array vazio quando não há mapeamento (não dá 404). Espelha o `by-person` que já existia para pessoa.

### <span class="rn-tag rn-tag--fix">Correção</span> refId com caractere especial no path

Os endpoints de external-ref não faziam URL-decode dos segmentos `{interface}` e `{refId}`. Um refId com espaço (como `00 71000000038`, comum na cegid) chegava como `00%2071000000038` e não casava no banco. Vale para catalog (marca, categoria, vendedor) e register (pagamento, pessoa).

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Relatório de produtos quebrado por loja e por tempo

[Produtos mais vendidos](/docs/{lang}/api-reference/order/report/products)

O `groupBy` do relatório de produtos passa a aceitar uma **lista por vírgula**: a dimensão do item (`product`/`sku`/`category`/`brand`) **mais** `store` e/ou um grão de tempo (`day`/`week`/`month`). Ex.: `groupBy=product,store`, `sku,week`, `product,store,month`.

Com a quebra, o `limit` seleciona os **top itens do período inteiro** e cada linha vira uma célula (item × loja × período, com `storeId`/`day`/`week`/`month`). Assim o "top produtos por loja" ou "por semana" sai numa chamada, em vez de uma chamada por loja. No máximo um grão de tempo por chamada; célula sem venda não vira linha. Retrocompatível: sem os tokens extras, nada muda.

---

## 22 de outubro de 2026

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

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

`POST https://developers.guper.co/api/validate` recebe o JSON que a sua integração produz e devolve, campo a campo, o que está de acordo com esta documentação e o que não está: campo que **não pertence** ao endpoint (com sugestão do nome certo quando é parecido), campo **obrigatório que faltou**, **tipo** que não bate e **valor** fora da lista aceita — inclusive caixa errada, como `"Legal"` onde o campo aceita `legal`.

Sem autenticação, sem gravar nada e sem criar transação. A comparação roda contra o mesmo arquivo que gera a página de referência, então ela nunca fica defasada em relação ao que você lê.

⚠️ A verificação é de **forma**. Ela não conhece a sua organização: não diz se o `storeId` existe, se a `interface` está cadastrada, nem se o valor está na escala certa de centavos. Payload aprovado aqui ainda pode ser recusado pela API por esses motivos.

---

## 21 de outubro de 2026

### <span class="rn-tag rn-tag--improvement">Melhoria</span> "Diferente de" na regra Tipo de entidade

[Regras de campanha: Criar](/docs/{lang}/api-reference/loyalty/campaign/campaign-rules/create)

A regra de campanha **Tipo de entidade** ([`code` 11](/docs/{lang}/api-reference/loyalty/campaign/campaign-rules/create)) passa a respeitar o `reverse`, como a de nível do cliente e a de tipo da compra: `false` = **igual a** (o que já valia), `true` = **diferente de**. Antes o campo era aceito e gravado, mas ignorado na avaliação — a regra só sabia comparar por igualdade.

⚠️ Pedido **sem `client.entityType` não bate com nenhum valor**: continua reprovando com `reverse: false` e passa a **disparar** com `reverse: true`. Como o `entityType` vem apenas do corpo do `rewardByOrder`, "diferente de pessoa jurídica" também alcança o pedido que não informou o tipo.

Regra criada pelo painel não muda de comportamento — o painel sempre gravou `reverse: false`. Se você criou a regra pela API com `reverse: true`, o valor era ignorado e agora inverte de fato.

---

## 12 de outubro de 2026

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Listar mensagens por telefone, com o corpo, numa chamada

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

A listagem de mensagens passa a aceitar **`cellphone`** (match exato no telefone que recebeu a mensagem) e **`include`** (lista separada por vírgula que anexa os campos renderizados a cada dispatcher: `rendered_body`, `rendered_subject`, `rendered_text`, `rendered_meta`).

Juntos eliminam dois round-trips de quem precisa descobrir qual mensagem iniciou uma conversa a partir de um número: antes era resolver telefone→cliente no register, listar as mensagens e abrir o detalhe de cada uma só para ler o corpo. Agora **`?cellphone=...&include=rendered_body`** devolve tudo numa chamada.

⚠️ `include` é **opt-in** — sem ele a lista continua enxuta (o corpo renderizado pode ser um HTML inteiro). `cellphone` casa com o **snapshot gravado no envio**, não com o cadastro vivo do cliente.

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Tipo da compra no rewardByOrder

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

O `POST /api/loyalty/rewardByOrder` aceita o campo opcional **`purchaseType`**: o tipo da compra, em texto livre definido pela sua integração (ex.: `delivery`, `retirada`). Até 100 caracteres; espaços nas pontas são removidos e valor vazio é ignorado. Número, booleano ou lista retornam `400`. O valor fica guardado com a transação até o `confirmOrder`.

Na campanha de compra, a nova regra **Tipo da compra** ([`code` 20](/docs/{lang}/api-reference/loyalty/campaign/campaign-rules/create)) dispara quando o `purchaseType` for **igual** (ou **diferente**, com `reverse`) a qualquer um dos valores configurados, sem diferenciar maiúsculas. Assim dá para separar atacado/varejo, compra de colaborador, empresa/pessoa física etc. Retrocompatível: quem não envia o campo não muda nada.

---

## 7 de outubro de 2026

### <span class="rn-tag rn-tag--improvement">Melhoria</span> A receita decomposta, do preço de tabela ao líquido

[Relatório de vendas](/docs/{lang}/api-reference/order/report/sales)

Todo total do `report/sales` passa a trazer **`mix`**: `listRevenue` (preço de tabela) − `discount` − `incentive` = **`netRevenue`**, mais `averageTicket` (**ASP**, preço médio cobrado) e `listAverageTicket` (**OSP**, preço de tabela). O `comparison.total` traz o mesmo bloco, então dá para comparar a receita líquida período a período.

⚠️ **`revenue` já é líquido do desconto comercial** — o `price` do item é o unitário depois do desconto. O preço de tabela é `revenue` **mais** `discounts`, não menos; subtrair o desconto de `revenue` conta duas vezes. Era justamente para evitar essa conta refeita em cada tela que os campos passaram a existir.

⚠️ `incentive` e `netRevenue` vêm **`null`** sem `withAttribution=1` — o saldo resgatado vive na atribuição, e devolver zero seria mentira.

⚠️ Não confundir com `attribution.revenueGross`/`revenueNet`, que são do recorte das vendas atribuídas; `mix` é do negócio inteiro.

---

## 3 de outubro de 2026

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

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

`PUT /api/register/store/walletLink` define de uma vez todas as lojas de uma política (`{"wallet": 108, "stores": [...]}`) ou todas as políticas de uma loja (`{"store": 22, "wallets": [...]}`), numa única transação. A lista é o estado final: o que não estiver nela é removido. Substitui um `POST`/`DELETE` por vínculo. As páginas de listar, criar e excluir vínculo também foram revisadas; a listagem documenta o `with=store`.

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Políticas de resgate disputam entre si

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

Quando o cliente tem saldo em **mais de uma política de resgate** válida para o pedido, as políticas agora **disputam entre si**: o pedido usa só a que dá o maior desconto (no empate, a de vencimento mais próximo). Antes, cards de políticas diferentes em modo Agregar ou Misto eram somados.

Dentro de uma mesma política nada mudou: Agregar soma os cards, Único usa o melhor. O modo Misto passa a se comportar como Agregar. O contrato do [Resgate por pedido](/docs/{lang}/api-reference/loyalty/checkout/reward-by-order) é o mesmo; o que muda é o `redeemable.total` de quem tem saldo em mais de uma política na mesma loja. O novo guia explica a regra com exemplos.

---

## 30 de setembro de 2026

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Permissões por api-key

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

Cada api-key passa a ter uma lista de **permissões** no formato `serviço.permissão`, e cada rota exige a sua. Hoje cada serviço expõe uma permissão única `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` — e o `connect` expõe seis mais finas: `connect.user`, `connect.access`, `connect.scope`, `connect.session`, `connect.auth` e `connect.mcp`.

**Nada muda para quem já integra:** todas as chaves existentes receberam todas as permissões. Chamada cuja chave não tem a permissão da rota é recusada com **`403`**, e a resposta nomeia o que falta em `requiredScope`. Chamada assinada entre serviços Guper não passa por essa verificação.

As permissões de cada chave também são editáveis no painel, em **Configurações › API Keys › Permissões**.

## 29 de setembro de 2026

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Campanha em rascunho

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

Campanha agora pode ser salva como **rascunho** (`isDraft: true`) no `POST`/`PUT /api/loyalty/campaign`: fica editável e **nunca executa** — enquanto for rascunho, o `isActive` é forçado a `0` no servidor. Publique enviando `isDraft: false`; depois de publicada ela só alterna entre ativa e pausada e não volta a rascunho (`400`).

Na listagem, o `status` derivado ganhou o valor **`draft`**, que prevalece sobre os demais; vale também em `?status=draft`, no `statusCounts` e no `sortByStatus` (ativas, rascunhos, pausadas, encerradas). Retrocompatível: campanhas existentes são publicadas (`isDraft: false`).

---

## 28 de setembro de 2026

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Status da campanha na listagem

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

`GET /api/loyalty/campaign` agora devolve em cada linha um **`status` derivado**: `active`, `paused` ou `finished`. Retrocompatível — nada mudou no que já vinha.

`finished` não é coluna: em campanha de audiência é o envio encerrado; nos outros gatilhos é a vigência (`finishAt`) vencida. ⚠️ `finished` **prevalece sobre o `isActive`**: campanha com a vigência vencida e ainda ligada aparece como encerrada, não como ativa. É só leitura — o `isActive` não muda.

Três parâmetros novos, todos opcionais: `status` filtra por esse status; `statusCounts=1` devolve as contagens de cada um com os mesmos filtros `q[...]`; `sortByStatus=1` traz as ativas primeiro, depois as pausadas e as encerradas.

---

## 24 de setembro de 2026

### <span class="rn-tag rn-tag--breaking">Breaking change</span> Token vencido deixa de ser aceito

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

O `x-guper-authorization` apresentado **depois** do `expiresIn` era aceito; agora é recusado com **`401`** e `Code: E0002`.

Nenhum prazo foi encurtado — os vencimentos são os mesmos de sempre e o endpoint de emissão continua igual. Quem renova o token quando ele expira não sente diferença; quem guardava um token antigo precisa chamar [Obter token](/docs/{lang}/api-reference/connect/api/get-token) outra vez.

⚠️ Pedir token novo **antes** do atual expirar sempre foi permitido e não revoga o anterior.

### <span class="rn-tag rn-tag--new">Novo endpoint</span> Audiência endereçada por período

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

`GET /api/loyalty/report/audience/{start}/{end}`: a quem as campanhas foram endereçadas — o denominador de "de quem a gente mirou, quantos receberam". O relatório de cards já dizia quantas recompensas nasceram; faltava o alvo.

O trabalho está em juntar **três tabelas com três unidades diferentes**. ⚠️ A última chance enfileira por **card × campanha**, não por pessoa: contar linha ali infla a audiência em mais que o dobro. Aqui já vem deduplicado.

⚠️ Dois números, e só um é denominador: **`targeted`** (pessoas distintas por campanha, somadas — casa com recompensa concedida) e **`clients`** (gente distinta, que nunca deve virar denominador). Na cloe em agosto as duas campanhas de última chance endereçaram quase as mesmas pessoas: 77.429 endereçamentos para ~38,7 mil gente.

⚠️ Para qualquer taxa, passe `type=monetary`: campanha de notificação **pode** usar lista de audiência — ela endereça gente e nunca gera recompensa, por desenho. E gatilho sem alvo (formulário, evento externo) não aparece na resposta.

---

## 24 de setembro de 2026

### <span class="rn-tag rn-tag--new">Novo endpoint</span> Entrega e abertura por período

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

`GET /api/sender/report/delivery/{start}/{end}`: a mesma leitura do relatório por campanha, mas numa janela de data — da organização inteira ou de uma lista de campanhas (`?sequence=`). Com `?groupBy=sequence` vem a quebra por campanha, ordenada por volume. `?tz=` lê a fronteira do dia no fuso da organização (`insertedAt` é gravado em UTC).

Responde "como foi o nosso disparo em setembro" sem precisar varrer campanha por campanha.

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Provedor que não confirma entrega não derruba mais a taxa

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

Provedor sem webhook de entrega (hoje, push) para em `sent` e nunca mais fala. Isso não é "não entregue", é entrega sem confirmação — mas entrava na conta como falha implícita. Agora vai para o campo novo `unconfirmed`, **fora de `attempted` e das duas taxas**. Numa organização com push no mix, a taxa de entrega subia ou descia sem nada ter acontecido; agora ela mede só o que dá para medir.

`attempted` continua sendo o denominador das taxas; o total geral que saiu da fila é o campo novo `sent` (= `attempted + unconfirmed`).

---

## 23 de setembro de 2026

### <span class="rn-tag rn-tag--new">Novo endpoint</span> Funil das campanhas de notificação

[Funil de notificação](/docs/{lang}/api-reference/loyalty/report/notifications)

`GET /api/loyalty/report/notifications/{start}/{end}` com `groupBy=campaign,day`: quantas pessoas a mensagem alcançou e quantas delas compraram. É o **denominador** que faltava — o relatório de vendas diz quanto a mensagem gerou, não a que custo de alcance.

Só campanha `type=notification`: campanha monetária é atribuída pelo **resgate** do saldo, e a mensagem dela é um aviso de cashback. ⚠️ **Duas datas, separadas na resposta**: `total` é a SAFRA (mensagens enviadas na janela, seguidas onde quer que convertam) e `total.result` é o que ACONTECEU na janela — este último é o que conversa com a receita influenciada do relatório de vendas.

⚠️ `notificationCard.attributionAt` **não** é a data da atribuição: é gravada no nascimento do card e está deprecada. Contar conversão por ela daria 100% sempre.

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Ranking por campanha e por origem devolve o líquido

[Relatório de vendas](/docs/{lang}/api-reference/order/report/sales)

`byCampaign` e `byOrigin` passam a trazer `redeemed` e `revenueNet` junto do bruto. Quem exibe reporta o líquido, então cada consumidor decidia sozinho — e campanha que não emite saldo aparecia com receita zero.

---

## 22 de setembro de 2026

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Relatório de vendas: quebra e filtro por nível, lista de lojas e o alerta de desconto

[Relatório de vendas](/docs/{lang}/api-reference/order/report/sales)

`groupBy=tier` e `tier=Diamond|none` recortam pelo **nível do cliente no momento da compra** (snapshot do pedido). ⚠️ `none` é o pedido sem snapshot — anônimo ou não identificado —, que numa organização grande passa de um terço do faturamento: os níveis sozinhos nunca fecham com o total. O filtro vale também para a atribuição e para o ranking de produtos.

`store` passa a aceitar **lista** (`store[]=207&store[]=208` ou `207,208`, até 500), para filtrar por canal: canal é grupo de loja, o grupo mora no register e quem chama resolve o grupo em ids.

Cada linha de `byDay`, `byStore` e `byInterface` ganha o `split` (atribuída x influenciada, em líquido) que antes só existia no total.

Campo novo **`ordersDiscountOverRevenue`**: pedidos cujo desconto é maior que a própria venda, o que é impossível para "preço de tabela menos preço de venda". Confira antes de publicar qualquer razão feita sobre `discounts` — numa organização são 27% dos pedidos, e com eles dentro a razão dá 67%.

---

## 21 de setembro de 2026

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

[Atualizar usuário](/docs/{lang}/api-reference/connect/user/update-user)

A atualização de usuário passa a exigir **`login`** junto do `personId`, e os dois têm que pertencer ao mesmo usuário: o `login` localiza o registro, o `personId` confirma.

Par errado não muda nada e responde `404` (login inexistente) ou `409` (login de outra pessoa); a falta de um dos dois campos responde `400`. Somente `password`, `type` e `active` podem ser alterados — campo omitido fica como está.

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Trava de tentativas no login e na emissão de token

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

Depois de **8 tentativas falhas em 15 minutos**, `POST /api/connect/auth`, `GET /api/connect/token` e o consentimento OAuth respondem **`429`** e param de conferir a credencial pelos 15 minutos seguintes. Um acerto zera o contador.

A chave da trava é diferente em cada caso: no login é o par organização + `login`; na emissão de token é a api-key + o IP de origem — então o bloqueio de um integrador **não atinge os outros chamadores da mesma organização**.

A resposta de credencial errada também passou a ser **sempre a mesma** (`401`), para não revelar se o login existe.

## 18 de setembro de 2026

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Venda atribuída, influenciada e impactada no relatório de vendas

[Relatório de vendas](/docs/{lang}/api-reference/order/report/sales)

Com `withAttribution=true`, o bloco `attribution` ganha `split`, separando os dois caminhos pelos quais o programa chega na venda, em pedidos distintos: `attributed` (o pedido resgatou saldo), `influenced` (o cliente só recebeu a mensagem da campanha e comprou, sem resgatar) e `impacted` (a soma, que é o total do próprio bloco). O pedido cai num lado só — receber a mensagem **e** resgatar conta como atribuído —, então os dois lados fecham na soma. Cada lado traz as mesmas derivadas do total (`revenueNet`, `avgDiscount`, tickets).

O mesmo bloco aceita agora `attributionBy=store,interface`, que devolve `byStore` / `byInterface` — a atribuição quebrada por loja e por canal, cada linha com as derivadas prontas.

O filtro `campaign=` passou a aceitar **500 ids** (era 200).

---

## 17 de setembro de 2026

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

[Política de resgate](/docs/{lang}/api-reference/loyalty/wallet/read) · [Acúmulo por pedido](/docs/{lang}/api-reference/loyalty/checkout/reward-by-order)

A carteira ganha `minOrderRate`: o pedido precisa valer N vezes o **saldo do cliente** para o saldo poder ser usado (`3` com saldo de R$ 30,00 exige compra de R$ 90,00). É tudo-ou-nada e vale por carteira, só para carteira monetária; `null` = sem regra, comportamento de sempre.

Quando a regra barra o carrinho, `redeemable.total` volta `0` e o novo `redeemable.blocked` diz o porquê, com `required` (quanto o pedido precisaria valer) e `missing` (o que falta) em centavos — dá para mostrar "faltam R$ 15,00 para usar seu saldo" no PDV. A chave só aparece quando há bloqueio. `Atualizar transação` reaplica a regra: se o carrinho encolher abaixo do mínimo depois da cotação, o resgate reservado cai — cobre sempre pelo `redeemable.total` da última resposta.

### <span class="rn-tag rn-tag--new">Novo endpoint</span> Tempo até o resgate do cashback

[Tempo até o resgate](/docs/{lang}/api-reference/loyalty/report/redemption-latency)

`GET /api/loyalty/report/redemption-latency/{dateStart}/{dateEnd}` devolve a distribuição de dias (`buckets=day`) ou semanas (`buckets=week`) entre a liberação do card (`basis=available`, padrão) ou a emissão (`basis=issued`) e o resgate liquidado, com mediana e p90. Aceita os mesmos filtros do relatório de resgates.

---

## 16 de setembro de 2026

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Relatórios de cashback e de vendas: filtro por várias campanhas

`loyalty.report.cards` e `loyalty.report.redemptions` passam a aceitar uma lista em `campaign` (`campaign=191,171` ou `campaign[]=191&campaign[]=171`); um id sozinho continua funcionando. `order.report.sales` ganha o mesmo `campaign`, junto com `withAttribution=true`: ele recorta só o bloco de atribuição (cada pedido conta uma vez), e o total de vendas não muda.

### <span class="rn-tag rn-tag--new">Novo endpoint</span> Resgates de cashback com pedido e lojas

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

`GET /api/loyalty/report/redemptions/{dateStart}/{dateEnd}` lista os resgates liquidados, uma linha por (resgate, card), com o pedido, a loja que emitiu o card e a loja do resgate. Com `groupBy` (`day`, `month`, `campaign`, `originStore`, `redeemStore`) devolve agregados — `groupBy=originStore,redeemStore` mostra a circulação de saldo entre lojas. Aceita `cohort=redemption|issuance` e filtros por campanha, lojas e cliente. A linha é da granularidade do card: não traz valor do pedido, para não ser somado em dobro.

### <span class="rn-tag rn-tag--fix">Correção</span> Cards de cashback: resgate conta só quando a venda liquida

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

`loyalty.report.cards` passa a contar como resgatado apenas o saldo de vendas **liquidadas**. Reserva aberta no checkout e reserva cancelada saíam no `redeemed`; agora ficam fora. O valor muda pouco nos períodos fechados.

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Cards de cashback: taxa de conversão, uso parcial/total, `groupBy=day` e `cohort`

`loyalty.report.cards` ganha, em cada linha e no total:

- `touchedCards` — cards emitidos no período com algum resgate liquidado (parcial ou total);
- `cardsRedeemedPartial` / `cardsRedeemedFull`, `partialShare` / `fullShare`;
- `usageRate` — a **taxa de conversão** (`touchedCards / (cards − cardsCanceled)`, em %);
- `cardsActive`, que fecha os buckets de status com `cards`.

Novos parâmetros: `groupBy=day` (série diária, também combinável com `store` ou `campaign`) e `cohort=issuance`, que janela o `redeemed` pela emissão do card ("o que aconteceu com o que emiti") em vez da data do resgate (`cohort=redemption`, padrão). `cardsRedeemed` continua sendo o card com saldo zerado e não deve ser usado como conversão: estorno também zera card.

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Relatórios de vendas e de campanha: desconto médio e tickets bruto/líquido

`order.report.sales?withAttribution=true` (no bloco `attribution` e em cada linha de `byDay`) e `order.campaign.report` (no `total`) passam a devolver `avgDiscount` (`redeemed / revenueGross`, razão), `averageTicketGross` (`revenueGross / orders`) e `averageTicketNet` (`revenueNet / orders`). Todos são calculados sobre **pedidos distintos**; a diferença entre os dois tickets é o saldo médio aplicado por pedido. Campos novos, nada foi removido.

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Tier: escolher quais campanhas pontuam

Na origem `rewardCampaign` do `tier_config`, a nova lista `sources.rewardCampaign.campaigns` define quais campanhas somam pontos no tier. Sem a lista, todas as campanhas continuam pontuando (comportamento anterior); com `[]`, nenhuma pontua. Não é retroativo: pontos já creditados permanecem.

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

A documentação de `sources` também foi corrigida: é um objeto indexado pelo nome da origem, e não uma lista.

---

## 15 de setembro de 2026

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Relatório de vendas: filtro `membership=member` (faturamento de associados)

`order.report.sales?membership=member` restringe aos pedidos de associado (via o snapshot `order_personMembership`), no total e na atribuição. É o **faturamento de associados por período**, companion do `register.report.members` (que dá a base org-wide). Só cobre pedidos com snapshot (~desde 28/05/2026); não-membro = `total − member`.

### <span class="rn-tag rn-tag--new">Novo endpoint</span> Relatório de associados / membros do programa

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

Numa chamada, quem são os associados de um programa de fidelidade: base ativa,
composição por tier e origem, quantos já compraram (conversão lifetime) e valor
lifetime. Genérico por `tierConfig` (qualquer org):

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

⚠️ O lente é **lifetime**, não período: `conversionLifetime` = membros que já
compraram alguma vez; `lifetimeValue` = gasto na vida. Faturamento de associados
por período é do `order.report.sales`. `meta.membershipStartedAt` avisa desde
quando existe membro.

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Relatório de vendas: venta generada (líquida) na atribuição

`order.report.sales?withAttribution` agora traz **`revenueNet`** (= `revenueGross − redeemed`), a **venta generada** — a base sobre a qual a Guper fatura — no total e na série diária, além de `participationNet`. Antes só havia o bruto (`revenueGross`); reportá-lo como "gerado" dava acima da fatura. Use `revenueNet`.

### <span class="rn-tag rn-tag--new">Novo endpoint</span> Produtos mais vendidos

[Produtos mais vendidos](/docs/{lang}/api-reference/order/report/products)

Para saber "o que mais vendeu" não é mais preciso paginar os itens e somar do seu
lado. Uma chamada ranqueia os itens por produto, SKU, categoria ou marca:

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

Traz unidades, receita de linha, pedidos e linhas — top N por receita, com o `total`
cobrindo todo o período. `product`/`sku` funcionam hoje; `category`/`brand` já ficam
prontos e enchem conforme a ingestão melhorar (a resposta traz a cobertura no `meta`).
Atenção: a `revenue` aqui é receita de **linha** (soma de price×quantity), não o total
do pedido — para faturamento use o relatório de vendas.

## 14 de setembro de 2026

### <span class="rn-tag rn-tag--new">Novo endpoint</span> RFM por safra de aquisição (cohort)

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

Para analisar clientes por safra não é mais preciso puxar centenas de milhares de
linhas de RFM e agrupar do seu lado. Uma chamada devolve o RFM agregado por safra
de aquisição — por mês da 1ª compra e/ou loja de aquisição:

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

Por safra: nº de clientes, valor lifetime e médio, nº médio de compras, cadência de
recompra e recência. Valores em centavos; `total` reconcilia com a soma das linhas.
Atenção: loja = loja de **aquisição** e o valor é o lifetime **org-wide** do cliente
(não vendas da loja — para isso use o relatório de vendas).

### <span class="rn-tag rn-tag--new">Novo endpoint</span> Relatório de cards de cashback (emitidos e resgatados)

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

Para ver "todas as campanhas" não é mais preciso rodar o relatório de campanha
uma por uma. Uma chamada devolve emissão e resgate agrupados por mês, campanha,
gatilho ou loja:

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

Traz cards, crédito distribuído, resgatado, saldo e expirados. Reconcilia com o
relatório de uma campanha (mesma conta). Valores em centavos; `rewardType`
separado (monetary padrão).

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Relatório de vendas: canal, desconto e coorte

O [relatório de vendas](/docs/{lang}/api-reference/order/report/sales) ganhou
`groupBy=interface` (participação por canal), a métrica `discounts` e o filtro
`client` (lista de clientes — uma coorte/experimento).

## 10 de setembro de 2026

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Regra de campanha: cliente colaborador

[Criar regra de campanha](/docs/{lang}/api-reference/loyalty/campaign/campaign-rules/create)

Novo `code` **19** (`collaborator`, escopo `campaign`): a campanha passa a poder
gatear pelo fato de o comprador ser colaborador da organizacao. O caso comum e o
inverso — **colaborador nao acumula cashback** — que se escreve com
`reverse: true`.

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

A regra **nao tem `params`**: o sentido vem do `reverse`. `false` = so
colaborador passa; `true` = colaborador nao passa.

A flag lida e o `client.isCollaborator` do proprio pedido — o mesmo campo que o
`rewardByOrder` ja aceita desde junho para marcar o comprador como colaborador.
**Pedido que nao traz a flag conta como "nao e colaborador"**, entao a regra com
`reverse: true` nao muda nada para quem nao envia o campo.

A regra vale em **campanha de compra**. Nos outros triggers (form-submission,
last-chance, reactivate-reward) o cliente e montado a partir do cadastro, que nao
carrega a flag — ali ela nao tem efeito.

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Lista de cards enxuta por padrão

[Listar cards](/docs/{lang}/api-reference/loyalty/card/list) não embute mais o
`flow` (ledger de crédito/débito) em cada linha — eram ~1 KB por card, o que
inviabilizava extrações em lote. A lista sai enxuta; para o ledger, use o
endpoint de flow do card ou passe `withFlow=true` (só vale para um card ou uma
página pequena). O `status` de cada card continua na lista.

## 9 de setembro de 2026

### <span class="rn-tag rn-tag--new">Novo endpoint</span> Listagem de pedidos com o pedido inteiro

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

A listagem de pedidos devolve as linhas resumidas; para ver itens, pagamentos,
campanhas, historico, loja e cliente era preciso um `GET` por pedido. Agora da
para pedir a pagina ja detalhada:

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

Mesmos filtros, ordenacao e paginacao da listagem normal, e cada linha vem com o
**mesmo payload** do `GET /api/order/data/{idOrder}`. Existe tambem na variante
por interface: `GET /api/order/{interface}/data/full`, ja traduzido para os
refIds.

Teto de 50 linhas por pagina — cada linha carrega os proprios itens e pagamentos,
entao `e=0` significaria o historico inteiro em uma resposta.

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

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

Para "NPS por loja" não é mais preciso paginar as avaliações e somar loja a
loja. Uma chamada devolve o NPS geral e a quebra por loja:

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

Cada linha traz os componentes crus (promotores/neutros/detratores), o `nps`, o
`avgRating` e quantas vieram sem vendedor. Filtra por `type` (nps/csat), `store`
e período (`days` ou `dateStart`/`dateEnd`).

## 8 de setembro de 2026

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Relatório de vendas: comparação de períodos

O [relatório de vendas](/docs/{lang}/api-reference/order/report/sales) ganhou o
parâmetro `compareWith`:

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

`previous` (janela de mesmo tamanho logo antes), `previousYear` (mesmas datas um
ano atrás) ou um intervalo `YYYY-MM-DD..YYYY-MM-DD`. A resposta ganha um bloco
`comparison` com o total do período-base e o `delta` (absoluto e %) em pedidos,
faturamento e ticket — dá para responder *"vendeu X, +12% vs o mês passado"*.

## 6 de setembro de 2026

### <span class="rn-tag rn-tag--new">Novo endpoint</span> Entrega e taxa de abertura por campanha

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

Para saber a taxa de abertura de uma campanha não era preciso mais varrer o log
mensagem a mensagem (que estourava timeout). O endpoint agrega por canal e no
total, e você referencia pela `messageSequence` que a campanha carrega:

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

Devolve `opened` (abertos), `delivered`, `failed`, `attempted` e as taxas de
entrega e abertura. `opened` = email aberto (Mailgun) ou WhatsApp lido. A
contagem é **por sequência**: duas campanhas que dividem a mesma `messageSequence`
somam aqui.

### <span class="rn-tag rn-tag--new">Novo endpoint</span> Relatório de vendas agregado

[Relatório de vendas](/docs/{lang}/api-reference/order/report/sales)

Para saber "quanto vendi ontem por loja" ou "faturamento por dia no mês" não era
preciso mais paginar `/order/data` e somar no cliente — agora há um endpoint que
já devolve o número.

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

Agrega por `day`, `month`, `store` ou combinações, filtra por loja e por status.
Três decisões importam: a **receita é líquida de cancelamento** por padrão (mas o
bloco `byStatus` sempre mostra todos os status, o cancelado inclusive, para o que
ficou de fora ser auditável); o **dia sai de `order_date` convertido para o fuso
da organização** (a venda cai no dia em que aconteceu, não no dia do sync); e
`updatedThrough` diz o maior `createAt` que entrou no cálculo — como o pedido
chega depois da venda, "ontem" é um número mutável.

Valores em centavos.

### <span class="rn-tag rn-tag--deprecated">Depreciação</span> financeSumary

O `financeSumary` somava pedido cancelado, perdia o último dia do período e
agrupava em UTC. Use o [relatório de vendas](/docs/{lang}/api-reference/order/report/sales)
(`groupBy=month` cobre o caso dele).

## 2 de setembro de 2026

### <span class="rn-tag rn-tag--new">Novo endpoint</span> Opt-out: registrar quem não quer ser contatado

[Registrar](/docs/{lang}/api-reference/sender/opt-preference/create) ·
[Consultar](/docs/{lang}/api-reference/sender/opt-preference/lookup) ·
[Revogar](/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) ·
[Histórico](/docs/{lang}/api-reference/sender/opt-preference/history)

Não havia onde registrar o cliente que pede para parar de receber mensagens. Agora há.

Registre **todos os identificadores que você tiver** — pessoa, e-mail e telefone:

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

É gravada uma linha por identificador e o envio é barrado quando **qualquer um** deles casa. É
esse o ponto: se o cliente se cadastra de novo e ganha um person id novo, o e-mail e o telefone
continuam casando, então o opt-out sobrevive ao cadastro novo. Se em vez disso ele troca de
e-mail dentro do mesmo cadastro, o alvo de pessoa continua casando.

**O opt-out é por organização.** O mesmo e-mail pode estar bloqueado numa organização e
continuar recebendo em outra — nunca atravessa organizações.

**Tudo é bloqueado, exceto o PIN de login.** Essa é a única isenção — bloqueá-lo trancaria o
cliente para fora da própria conta.

O `countryCallingCode` é **obrigatório sempre que `cellphone` for enviado**. A chave gravada é
DDI + dígitos; sem ele a chave sairia diferente da que o envio consulta e o opt-out não faria
nada, calado.

O bloqueio vale para todas as organizações desde o início. A lista começa vazia, então nada é
barrado até um cliente efetivamente pedir — cada bloqueio corresponde a um pedido explícito.

## 27 de agosto de 2026

### <span class="rn-tag rn-tag--breaking">Breaking change</span> O status do resgate agora e `redeemed`, nao `rescued`

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

A palavra `rescued` sugeria resgate no sentido de salvamento, nao de saldo. O
estado liquidado passa a se chamar `redeemed` em todo lugar.

**A chave da resposta muda.** O status e a *chave* dentro de `redeem`, nao um
valor — entao isto e mudanca de forma, nao de string:

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

Quem le `response.redeem.rescued` passa a receber `undefined`. Use
`response.redeem.redeemed` — ou, para sobreviver aos dois, pegue a unica chave
do objeto `redeem` em vez de fixar o nome.

**O `redeemedStatus` tambem muda.** A listagem de movimentos do card devolve o
valor gravado direto, entao ele vai de `"rescued"` para `"redeemed"`.

O historico foi migrado na mesma janela, entao nao ha periodo em que os dois
termos convivam no dado gravado. `reserved` e `canceled` seguem iguais.

### <span class="rn-tag rn-tag--new">Novo endpoint</span> `POST /redeem/settle/{hash}` liquida uma reserva de resgate

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

Liquidar uma reserva de resgate passa a ter uma rota cujo nome diz o que ela
faz:

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

Converte um hold `reserved` em débito final, exatamente como antes — mesmo
handler, mesma resposta. O `{hash}` é o id da transação, não o de um card: uma
chamada liquida todos os cards presos naquela reserva.

É `POST` porque a chamada **muda estado** — grava o status, escreve o log e
dispara a atribuição de campanha. A rota anterior era `GET`, o que não se
sustenta com prefetch, crawler e retry automático.

### <span class="rn-tag rn-tag--deprecated">Depreciação</span> `GET /redeem/rescue/{hash}`

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

Substituída por `POST /api/loyalty/redeem/settle/{hash}`. A rota antiga
**continua funcionando** e não tem remoção agendada, mas saiu da documentação.

`rescue` sugeria resgate no sentido de salvamento, não de saldo — a ponto de as
traduções do painel terem invertido o significado. O termo do ciclo é
`reserved → redeemed`, com `settle` como ação.

A migração é a URL e o verbo. Request e response não mudam: a resposta segue
trazendo `"status": "rescued"`, já que o valor gravado não mudou nesta versão.

---

## 26 de agosto de 2026

### <span class="rn-tag rn-tag--new">Novo endpoint</span> Guper por IA: login por pessoa com OAuth 2.1

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

Cada organização passa a ter um endereço que assistentes de IA compatíveis com
MCP entendem — `https://{organization}.myguper.com/mcp`. A pessoa cola o
endereço no assistente, entra com o **mesmo login do painel**, e o assistente
passa a operar o Guper com **exatamente as permissões que ela já tem**.

Junto vem um authorization server OAuth 2.1 com PKCE no `connect`:

- `GET /.well-known/oauth-authorization-server/api/connect` — discovery
- `POST /api/connect/oauth/register` — registro dinâmico de cliente
- `GET` e `POST /api/connect/oauth/authorize` — autorização
- `POST /api/connect/oauth/token` — troca do code e renovação
- `POST /api/connect/oauth/revoke` — revogação
- `GET /api/connect/oauth/jwks` — chave pública

O token é um JWT com `aud` igual à URI canônica do recurso da organização, e o
`scope` traz as permissões do perfil no painel. Um token emitido para uma
organização não vale em outra.

**Nada muda para quem já integra.** `apiKey`/`apiSecret` → token → chamadas
continuam idênticos, e nenhum endpoint existente foi alterado. O caminho novo
fica ao lado, para quando o acesso for de uma pessoa e precisar respeitar o
perfil dela.

---

## 19 de agosto de 2026

### <span class="rn-tag rn-tag--fix">Correção</span> `confirmOrder` não anuncia mais acúmulo em venda anônima

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

Quando o pedido é confirmado sem cliente identificado, não há a quem
creditar — nenhum reward card é criado. Mesmo assim, `cashback.accumulatedOrder`
vinha preenchido com o valor **previsto**, e não com o que foi creditado.
Quem lia esse campo exibia ao consumidor um acúmulo que nunca existiu.

Agora, na venda anônima, `redeemedOrder` e `accumulatedOrder` voltam `0`.
A chave `cashback` continua presente e com os mesmos tipos — nada muda para
quem já lê o campo, além de o número passar a corresponder à realidade.

Venda com cliente identificado não muda em nada. Campanha com beneficiário
próprio (indicação, colaborador) também não: ali o crédito acontece de fato
mesmo sem comprador identificado, e o valor é preservado.

Na mesma passagem, a página de referência foi corrigida — ela ainda mostrava
uma resposta sem `customerId` e sem `redeemedOrder`, campos que o serviço já
retornava. Agora documenta os dois casos, identificado e anônimo.

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

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

O endpoint deixou de existir — a chamada agora responde `404`.

Ele era redundante: `POST /api/loyalty/transaction/cancel/{TID}` passa
pelo mesmo processo interno de devolução da reserva, e cobre também o
caso que o `redeem/cancel` atendia — soltar um resgate reservado no
checkout que nunca virou pedido (carrinho abandonado, falha no
pagamento). Como nesse cenário ainda não houve acúmulo, não há nada a
debitar: só a reserva volta para o saldo do cliente.

Nenhuma integração deve ser afetada — a rota não recebeu uma única
chamada em produção desde 15 de maio de 2025. Se ainda assim houver
código chamando esse caminho, a migração é trocar a URL pelo
`transaction/cancel`, usando o mesmo identificador de transação.

**Antes**

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

**Agora**

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

---

## 25 de junho de 2026

### <span class="rn-tag rn-tag--improvement">Melhoria</span> Novo caminho `/mdw/vtex/*` no middleware (alinhamento com outros `mdw_*`)

O serviço `middleware` agora aceita um novo prefixo de caminho —
`/mdw/vtex/*` — equivalente ao legado `/api/middleware/*`. Os dois
prefixos batem no mesmo backend, com request e response idênticos.
Use o novo para integrações novas; o antigo segue funcionando.

Exemplos:

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

A motivação é alinhar com os outros adaptadores de integração
(`/mdw/clip`, `/mdw/shopify/front`) e abrir caminho para depreciar o
prefixo `/api/middleware` no futuro — sem janela de coordenação
forçada (cada consumer migra no seu ritmo).

---

## 24 de junho de 2026

### <span class="rn-tag rn-tag--new">Novo endpoint</span> Novo serviço `integration` — gestão das integrações ativadas por org

Identidade das integrações foi movida do middleware para um serviço
próprio. Substitui `/api/middleware/interface/*` e `/api/middleware/source`
(que viraram facade signed pro novo serviço — retrocompatível, mas novos
consumers devem usar `/api/integration/*` diretamente).

**`source`** — catálogo global de tipos de integração (vtex, shopify, cegid, polishop, ...). Leitura aberta; escrita restrita a serviços Guper internos.

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

**`interface`** — instâncias ativadas pela org (ex: a org tem VTEX `ecommerce` + Linx `loja-fisica`). A org vem implícita do header signature.

- `GET    /api/integration/interface` — lista interfaces da org
- `GET    /api/integration/interface/{id}` — leitura por id
- `GET    /api/integration/interface/by/slug/{slug}` — leitura por slug (hot path)
- `GET    /api/integration/interface/by/source/{source}` — lista interfaces de um tipo (ex: todas as VTEX da org)
- `POST   /api/integration/interface` — cria interface
- `PUT    /api/integration/interface/{id}` — atualiza (campo `activated` aceita boolean: `true` ativa, `false` desativa)
- `DELETE /api/integration/interface/{id}` — remove interface

### <span class="rn-tag rn-tag--deprecated">Depreciação</span> `/api/middleware/interface/*` e `/api/middleware/source`

Permanecem funcionando como facade transparente (proxy signed pro
`integration`) — não há quebra imediata. Migre consumers para
`/api/integration/*` diretamente; remoção da facade será anunciada com
antecedência.

---

## 23 de junho de 2026

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

Padrão `/api/catalog/{interface}/{resource}/...` para mapear refIds
externos (`vtex`, `shopify`, `cegid`, ...) a brands, categories e
sellers. Substitui o mapeamento legado via middleware (ver entrada de
Depreciação abaixo).

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

- `GET    /api/catalog/{interface}/{resource}` — lista refs da org para a interface
- `GET    /api/catalog/{interface}/{resource}/{refId}` — leitura por refId externo
- `POST   /api/catalog/{interface}/{resource}` — find-or-create (cria entidade + ref)
- `PUT    /api/catalog/{interface}/{resource}/{refId}` — link a entidade já existente
- `DELETE /api/catalog/{interface}/{resource}/{refId}` — remove só o ref (entidade permanece)
- `POST   /api/catalog/{interface}/{resource}/_resolve` — bulk lookup (até 500 refIds, devolve mapa `refId → id|null`)

### <span class="rn-tag rn-tag--new">Novo endpoint</span> Endpoints external_ref no `register` (payment, person com role)

Padrão `/api/register/{interface}/{resource}/...` para mapear refIds
externos a payments e persons. Substitui o mapeamento legado via
middleware (ver entrada de Depreciação abaixo).

**payment** segue a mesma forma do 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 tem `role` no path** (`cashier`, `salesperson`, `manager`, `client`):

- `GET    /api/register/{interface}/person/{role}` — lista
- `GET    /api/register/{interface}/person/{role}/{refId}` — leitura
- `PUT    /api/register/{interface}/person/{role}/{refId}` — link a pessoa existente
- `DELETE /api/register/{interface}/person/{role}/{refId}`
- `POST   /api/register/{interface}/person/{role}/_resolve`

`role` na PK permite que o mesmo `refId` mapeie pessoas diferentes em
contextos diferentes (ex.: `refId=99` pode ser `cashier` apontando para
uma pessoa e `salesperson` apontando para outra).

### <span class="rn-tag rn-tag--improvement">Melhoria</span> `seller` movida de `register` para `catalog`

Conceitualmente, seller é uma dimensão de catálogo (dono de inventário e
produtos, igual brand e category), não de cadastro. A entidade foi
movida para catalog e o endpoint canônico passa a ser
`/api/catalog/seller/*`.

`/api/register/seller/*` permanece como **alias retrocompatível** — os
endpoints continuam respondendo igual mas internamente fazem proxy para
catalog. Consumidores existentes (storeManager, smartPOS, admin) não
precisam mudar nada agora.

Novo código deve usar `/api/catalog/seller/*` direto.

### <span class="rn-tag rn-tag--deprecated">Depreciação</span> `/api/middleware/{interface}/{resource}` Reference endpoints

Os endpoints CRUD de mapeamento de refIds externos no middleware estão
depreciados:

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

Use os equivalentes em `catalog` (brand/category/seller) ou `register`
(payment/person/{role}) — ver entradas acima. Os endpoints legados
continuam funcionando durante a migração; o middleware faz dual-write,
mantendo ambos os caminhos sincronizados. Serão removidos numa release
futura, com aviso antecipado.

---

## 16 de junho de 2026

### <span class="rn-tag rn-tag--deprecated">Depreciação</span> `GET /api/loyalty/reward` (Reward Direto: Saldo) foi depreciado

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

O endpoint `GET /api/loyalty/reward` lia seus parâmetros de um **body
JSON** num GET (comportamento não confiável em vários clientes e
proxies) e dependia de uma interface de middleware configurada por
organização. Não tinha consumidores ativos e já estava marcado como
não-funcional no código.

A página de referência dele foi removida. Para obter o saldo de reward
cards de um cliente, use `GET /api/loyalty/report/rewardBalances/person/{person}`
— recebe o id da pessoa na URL, dispensa body e retorna o detalhamento
`available / expired / canceled / used` por wallet.

---

## 12 de maio de 2026

### <span class="rn-tag rn-tag--breaking">Breaking change</span> `GET /api/loyalty/transaction/byOrder/{idOrder}` agora retorna uma lista de transações

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

Um pedido pode legitimamente carregar mais de uma transação de loyalty
— acúmulo e resgate emitidos por fluxos separados, cancelamentos
parciais, retries no mesmo checkout. O endpoint retornava uma única
transação no topo, mascarando o caso de múltiplas.

A resposta agora carrega a lista completa em `transactions: [...]`,
ordenada da mais antiga para a mais recente.

**Antes**

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

**Depois**

```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"
        }
    ]
}
```

Se a sua integração lia `body.TID` no topo, agora itere por
`body.transactions[]` e escolha o TID desejado (tipicamente o mais
recente não cancelado).

Disponível a partir do `loyalty v0.48.81`.
