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
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 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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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 comcards.
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
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
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)
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)
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
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
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)
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
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
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
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
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}
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
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— discoveryPOST /api/connect/oauth/register— registro dinâmico de clienteGETePOST /api/connect/oauth/authorize— autorizaçãoPOST /api/connect/oauth/token— troca do code e renovaçãoPOST /api/connect/oauth/revoke— revogaçãoGET /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
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/sourceGET /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 orgGET /api/integration/interface/{id}— leitura por idGET /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 interfacePUT /api/integration/interface/{id}— atualiza (campoactivatedaceita boolean:trueativa,falsedesativa)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 interfaceGET /api/catalog/{interface}/{resource}/{refId}— leitura por refId externoPOST /api/catalog/{interface}/{resource}— find-or-create (cria entidade + ref)PUT /api/catalog/{interface}/{resource}/{refId}— link a entidade já existenteDELETE /api/catalog/{interface}/{resource}/{refId}— remove só o ref (entidade permanece)POST /api/catalog/{interface}/{resource}/_resolve— bulk lookup (até 500 refIds, devolve maparefId → 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}/paymentPOST /api/register/{interface}/payment— find-or-createGET /api/register/{interface}/payment/{refId}PUT /api/register/{interface}/payment/{refId}— linkDELETE /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}— listaGET /api/register/{interface}/person/{role}/{refId}— leituraPUT /api/register/{interface}/person/{role}/{refId}— link a pessoa existenteDELETE /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
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.