A API v2 permite consultar o extrato estruturado da carteira de pontos de um cliente. Com isso, é possível identificar o saldo atual por canal de venda e o histórico de lançamentos, com origem, operação, situação, saldos e, quando aplicável, a data de vencimento dos pontos.
A organização da consulta é:
Cliente
└── Canal de venda
└── Extrato
├── Saldo atual
└── Lançamentos
O pedido é apenas uma das possíveis origens de um lançamento. Ajustes feitos no painel, por integração ou automaticamente pelo sistema também aparecem no extrato.
Com essas rotas, a loja ou a integração consegue, por exemplo:
Um uso prático é montar comunicações como: o cliente possui X pontos no total e uma parte deles vence em determinada data.
A consulta foi dividida em duas rotas, porque o histórico de um cliente pode ter milhares de registros e precisa de paginação.
GET /v2/points/customers/{customerId}
Retorna:
O customerId representa o titular da carteira consultada.


GET /v2/points/customers/{customerId}/transactions
Retorna o histórico de transações do cliente, paginado e filtrável. Cada lançamento já traz os dados do canal de venda correspondente.
A ordenação traz os lançamentos mais recentes primeiro.


Identificam o titular da carteira, independentemente da existência de pedido:
idcodigocpfCnpjnomeRazaoSocialemailUm mesmo cliente pode ter saldo e movimentações em canais diferentes. Cada canal tem seu próprio saldo.
Dados do canal:
idnomedominiotiposaldoAtualPontosO saldo atual é o saldo disponível no momento da consulta. Ele é diferente do saldoResultante, que mostra o saldo logo após um lançamento histórico.
Cada lançamento traz:
iddatacanalorigemoperacaosituacaosaldoAnteriorquantidadePontossaldoResultantedataVencimento, quando aplicávelLeitura esperada:
Saldo anterior
→ quantidade de pontos da transação
→ saldo resultante
Exemplo: 500 pontos → crédito de 100 → 600 pontos.
Os valores de pontos não vêm negativos. O tipo da movimentação é definido pelo campo operacao.
Responde: por onde a movimentação foi gerada?
| Valor | Significado |
|---|---|
pedido | Movimentação ligada ao ciclo de pontos de um pedido |
painel | Movimentação administrativa |
api | Movimentação provocada por integração externa |
sistema | Movimentação automática do Sistema de Pontos, como a expiração |
O campo origem representa exclusivamente de onde veio a movimentação. Ele não indica mais o que aconteceu com o saldo.
Hoje, ajuste digitado no painel e ajuste por upload de planilha são tratados como a mesma origem (painel). Essa diferenciação não faz parte desta entrega.
Responde: o que aconteceu com o saldo?
| Valor | Significado | Regra |
|---|---|---|
credito | Pontos adicionados | saldo resultante = saldo anterior + quantidade |
debito | Pontos retirados | saldo resultante = saldo anterior − quantidade |
alteracao | Saldo sobrescrito | saldo resultante = quantidade |
nenhuma | Saldo não mudou | saldo resultante = saldo anterior |
Em alteracao, quantidadePontos representa o novo saldo informado, e não um valor a somar ou subtrair.
A operação nenhuma aparece em um caso específico de pedido: pontos ainda pendentes que foram cancelados antes de entrar na carteira. Eles estavam registrados, mas nunca haviam sido liberados.
Valores possíveis: pendente, disponivel, indisponivel, redisponibilizado, abatido, concluido, expirado.
Em lançamentos de pedido, a situação acompanha o ciclo da pontuação. Em painel e API, a operação é aplicada imediatamente e a situação é concluido. Na expiração automática, a situação é expirado.
A API retorna apenas as combinações previstas:
| Origem | Operação | Situação | Significado |
|---|---|---|---|
| pedido | credito | pendente | Pontos gerados, ainda fora do saldo |
| pedido | credito | disponivel | Pontos liberados e adicionados |
| pedido | credito | redisponibilizado | Pontos voltaram para a carteira |
| pedido | nenhuma | indisponivel | Pontos pendentes cancelados antes de entrar no saldo |
| pedido | debito | abatido | Pontos usados como pagamento |
| pedido | debito | indisponivel | Pontos disponíveis removidos após cancelamento |
| painel | credito | concluido | Crédito administrativo |
| painel | debito | concluido | Débito administrativo |
| painel | alteracao | concluido | Saldo sobrescrito no painel |
| api | credito | concluido | Crédito por integração |
| api | debito | concluido | Débito por integração |
| api | alteracao | concluido | Saldo definido por integração |
| sistema | debito | expirado | Pontos vencidos removidos automaticamente |
O lançamento traz dados do pedido, como id, numero, status, cliente e, se houver intermediação, intermediador.
Em cenários B2B2C:
Isso evita misturar os dados do consumidor final com o saldo do parceiro intermediador.
O lançamento identifica o usuário que fez o ajuste, com dados como id, codigoInterno, codigoLoja, nome e email.
O lançamento identifica a integração responsável, com id e nomeApi.
O campo dataVencimento se aplica a lançamentos que adicionam pontos à carteira (operacao: credito). Nos demais casos, o campo vem nulo ou omitido.
Com esse dado, é possível identificar a data mais próxima de vencimento de uma parte do saldo, além do saldo total do cliente.
Na rota de transações, os filtros atuam sobre os lançamentos, sem alterar o cliente titular da resposta.
Filtros disponíveis:
Também é possível combinar filtros.
A paginação usa offset e limit, e a resposta inclui o total de registros para montar a navegação entre páginas.
origem e operacao podem não estar disponíveis em todos os registros;saldoAnterior vem zerado no histórico antigo;quantidadePontos no histórico antigo fica disponível principalmente para pontos originados de pedido;dataVencimento no histórico antigo depende da disponibilidade do dado persistido.Porque o histórico de um cliente pode ter milhares de lançamentos. A primeira rota traz cliente, canais e saldo atual. A segunda traz o extrato paginado.
Sim. A consulta de saldo por canal permite obter o saldo total alinhado ao saldo apresentado no painel do cliente.
Na rota de transações, use os créditos com dataVencimento preenchida e identifique a data mais próxima entre os pontos ainda vigentes.
saldoAtual é o saldo disponível agora. saldoResultante é o saldo logo após um lançamento específico do histórico.
O titular da carteira. Em B2B2C, o consumidor final e o intermediador aparecem nos dados do pedido, sem misturar o saldo do parceiro com os dados do cliente final.
Sim. Na rota de transações, combine filtros como operacao, canal e, se necessário, origem ou data.
Como origem painel. Nesta entrega, não há distinção entre ajuste digitado e ajuste por upload.
Leave a Reply