Como consultar o extrato de pontos de um cliente pela API v2

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.

Para que serve?

Com essas rotas, a loja ou a integração consegue, por exemplo:

  • consultar o saldo atual de pontos do cliente por canal;
  • listar cada movimentação da carteira;
  • saber de onde veio o lançamento e o que aconteceu com o saldo;
  • identificar o saldo antes e depois da movimentação;
  • obter a data de vencimento dos pontos em créditos, quando aplicável.

Um uso prático é montar comunicações como: o cliente possui X pontos no total e uma parte deles vence em determinada data.

Como funciona?

A consulta foi dividida em duas rotas, porque o histórico de um cliente pode ter milhares de registros e precisa de paginação.

Consultar cliente, canais e saldo atual

GET /v2/points/customers/{customerId}

Retorna:

  • dados do cliente titular da carteira;
  • canais de venda vinculados;
  • saldo atual de pontos em cada canal.

O customerId representa o titular da carteira consultada.

Consultar o histórico de lançamentos

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.

O que cada rota retorna

Dados do cliente

Identificam o titular da carteira, independentemente da existência de pedido:

  • id
  • codigo
  • cpfCnpj
  • nomeRazaoSocial
  • email

Canais de venda

Um mesmo cliente pode ter saldo e movimentações em canais diferentes. Cada canal tem seu próprio saldo.

Dados do canal:

  • id
  • nome
  • dominio
  • tipo
  • saldoAtualPontos

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

Estrutura de um lançamento

Cada lançamento traz:

  • id
  • data
  • canal
  • origem
  • operacao
  • situacao
  • saldoAnterior
  • quantidadePontos
  • saldoResultante
  • dataVencimento, quando aplicável

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

Origem, operação e situação

Origem

Responde: por onde a movimentação foi gerada?

ValorSignificado
pedidoMovimentação ligada ao ciclo de pontos de um pedido
painelMovimentação administrativa
apiMovimentação provocada por integração externa
sistemaMovimentaçã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.

Operação

Responde: o que aconteceu com o saldo?

ValorSignificadoRegra
creditoPontos adicionadossaldo resultante = saldo anterior + quantidade
debitoPontos retiradossaldo resultante = saldo anterior − quantidade
alteracaoSaldo sobrescritosaldo resultante = quantidade
nenhumaSaldo não mudousaldo 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.

Situação

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.

Combinações válidas

A API retorna apenas as combinações previstas:

OrigemOperaçãoSituaçãoSignificado
pedidocreditopendentePontos gerados, ainda fora do saldo
pedidocreditodisponivelPontos liberados e adicionados
pedidocreditoredisponibilizadoPontos voltaram para a carteira
pedidonenhumaindisponivelPontos pendentes cancelados antes de entrar no saldo
pedidodebitoabatidoPontos usados como pagamento
pedidodebitoindisponivelPontos disponíveis removidos após cancelamento
painelcreditoconcluidoCrédito administrativo
paineldebitoconcluidoDébito administrativo
painelalteracaoconcluidoSaldo sobrescrito no painel
apicreditoconcluidoCrédito por integração
apidebitoconcluidoDébito por integração
apialteracaoconcluidoSaldo definido por integração
sistemadebitoexpiradoPontos vencidos removidos automaticamente

Contextos por tipo de lançamento

Quando a origem é pedido

O lançamento traz dados do pedido, como id, numero, status, cliente e, se houver intermediação, intermediador.

Em cenários B2B2C:

  • o cliente do extrato é o titular da carteira;
  • o consumidor é quem recebe o pedido;
  • o intermediador é quem realizou a compra e possui a carteira movimentada.

Isso evita misturar os dados do consumidor final com o saldo do parceiro intermediador.

Quando a origem é painel

O lançamento identifica o usuário que fez o ajuste, com dados como id, codigoInterno, codigoLoja, nome e email.

Quando a origem é api

O lançamento identifica a integração responsável, com id e nomeApi.

Data de vencimento

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.

Filtros e paginação

Na rota de transações, os filtros atuam sobre os lançamentos, sem alterar o cliente titular da resposta.

Filtros disponíveis:

  • origem
  • operação
  • situação
  • pedido
  • canal de venda
  • data

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.

Importante

  • As regras acima valem integralmente para as transações geradas a partir desta entrega.
  • Para o histórico anterior, existem limitações:
    • 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.
  • Esta entrega não altera as regras de geração, uso ou expiração de pontos.
  • Esta entrega não diferencia ajuste digitado no painel de ajuste feito por upload de planilha.

Perguntas frequentes

Por que existem duas rotas?

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.

O saldo atual é o mesmo do painel?

Sim. A consulta de saldo por canal permite obter o saldo total alinhado ao saldo apresentado no painel do cliente.

Como descubro a próxima data de vencimento?

Na rota de transações, use os créditos com dataVencimento preenchida e identifique a data mais próxima entre os pontos ainda vigentes.

Qual a diferença entre saldoAtual e saldoResultante?

saldoAtual é o saldo disponível agora. saldoResultante é o saldo logo após um lançamento específico do histórico.

Em pedidos intermediados, quem aparece no extrato?

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.

Posso filtrar só créditos de um canal?

Sim. Na rota de transações, combine filtros como operacao, canal e, se necessário, origem ou data.

Ajustes feitos por planilha aparecem como quê?

Como origem painel. Nesta entrega, não há distinção entre ajuste digitado e ajuste por upload.

Social Share

Deixe um comentário

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *