Entrar
.md

Notas de release

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

Cada entrada tem uma tag:

  • Breaking change — contrato de request ou response mudou; integrações precisam adaptar.
  • Novo endpoint — endpoint adicionado.
  • Melhoria — mudança retrocompatível.
  • Correção — corrige comportamento errado sem mudar o contrato.
  • Depreciação — endpoint descontinuado; migre para a alternativa indicada.

12 de novembro de 2026

Melhoria Saldo vencido no relatório de cards

Cashback emitido e resgatado por campanha (agregado)

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

Novo endpoint Atualizar clientes em lote

Atualizar clientes em lote

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.

Novo endpoint Cancelar e reativar cards em lote

Cancelar cards em lote · Reativar cards em lote

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

Novo endpoint Cancelar e reativar card

Cancelar card · Reativar card

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

5 de novembro de 2026

Melhoria Data do pedido no Reward by Order

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

Melhoria Audiência por card ativo

Consultar audiência (QON)

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

Novo endpoint Os refIds de uma entidade, sem varrer a interface

Listar refs de uma Categoria · de uma Marca · de um Vendedor · de um Pagamento

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.

Correção 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).

Melhoria Relatório de produtos quebrado por loja e por tempo

Produtos mais vendidos

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

Novo endpoint Valide seu payload antes de integrar

Valide seu payload

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

Melhoria "Diferente de" na regra Tipo de entidade

Regras de campanha: Criar

A regra de campanha Tipo de entidade (code 11) 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

Melhoria Listar mensagens por telefone, com o corpo, numa chamada

Messages: Listar

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.

Melhoria Tipo da compra no rewardByOrder

Acúmulo por pedido

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

Melhoria A receita decomposta, do preço de tabela ao líquido

Relatório de vendas

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

Novo endpoint Sincronizar vínculos loja ↔ política

Sincronizar vínculos loja ↔ política

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.

Melhoria Políticas de resgate disputam entre si

Políticas de resgate

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

Melhoria Permissões por api-key

Conceder scopes ao acesso

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

Melhoria Campanha em rascunho

Listar campanhas

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

Melhoria Status da campanha na listagem

Listar campanhas

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

Breaking change Token vencido deixa de ser aceito

Obter 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 outra vez.

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

Novo endpoint Audiência endereçada por período

Audiência por período

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

Novo endpoint Entrega e abertura por período

Entrega por período

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.

Melhoria Provedor que não confirma entrega não derruba mais a taxa

Entrega por campanha

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

Novo endpoint Funil das campanhas de notificação

Funil de notificação

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.

Melhoria Ranking por campanha e por origem devolve o líquido

Relatório de vendas

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

Melhoria Relatório de vendas: quebra e filtro por nível, lista de lojas e o alerta de desconto

Relatório de vendas

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

Breaking change PUT /api/connect/user exige login

Atualizar usuário

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

Melhoria Trava de tentativas no login e na emissão de token

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

Melhoria Venda atribuída, influenciada e impactada no relatório de vendas

Relatório de vendas

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

Melhoria Política de resgate: mínimo de compra dinâmico (minOrderRate)

Política de resgate · Acúmulo por pedido

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.

Novo endpoint Tempo até o resgate do cashback

Tempo até o resgate

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

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

Novo endpoint Resgates de cashback com pedido e lojas

Resgates de cashback

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.

Correção Cards de cashback: resgate conta só quando a venda liquida

Cards de cashback

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.

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

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

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

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

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

Novo endpoint Relatório de associados / membros do programa

Associados do programa

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.

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

Novo endpoint Produtos mais vendidos

Produtos mais vendidos

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

Novo endpoint RFM por safra de aquisição (cohort)

RFM por safra

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

Novo endpoint Relatório de cards de cashback (emitidos e resgatados)

Cards de cashback

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

Melhoria Relatório de vendas: canal, desconto e coorte

O relatório de vendas 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

Melhoria Regra de campanha: cliente colaborador

Criar regra de campanha

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.

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

Melhoria Lista de cards enxuta por padrão

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

Novo endpoint Listagem de pedidos com o pedido inteiro

Listar pedidos (completo)

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.

Novo endpoint NPS / CSAT por loja (consolidado)

NPS por loja

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

Melhoria Relatório de vendas: comparação de períodos

O relatório de vendas 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

Novo endpoint Entrega e taxa de abertura por campanha

Entrega e abertura

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.

Novo endpoint Relatório de vendas agregado

Relatório de vendas

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.

Depreciação financeSumary

O financeSumary somava pedido cancelado, perdia o último dia do período e agrupava em UTC. Use o relatório de vendas (groupBy=month cobre o caso dele).

2 de setembro de 2026

Novo endpoint Opt-out: registrar quem não quer ser contatado

Registrar · Consultar · Revogar · Listar · Contar · Histórico

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

Breaking change O status do resgate agora e redeemed, nao rescued

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.

Novo endpoint POST /redeem/settle/{hash} liquida uma reserva de resgate

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.

Depreciação GET /redeem/rescue/{hash}

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

Novo endpoint Guper por IA: login por pessoa com OAuth 2.1

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

Correção confirmOrder não anuncia mais acúmulo em venda anônima

Confirmar pedido por token

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.

Breaking change GET /api/loyalty/redeem/cancel/{hash} foi removido

Use 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

Melhoria 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

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

Depreciação /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

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

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

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

Depreciação /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

Depreciação GET /api/loyalty/reward (Reward Direto: Saldo) foi depreciado

Para saldo por cliente, use Report · Saldo por pessoa.

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

Breaking change GET /api/loyalty/transaction/byOrder/{idOrder} agora retorna uma lista de transações

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

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

Depois

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