Fidelidade: saldo e resgates

Mostre ao cliente quanto ele tem de pontos ou cashback e deixe ele trocar pontos por prêmios do seu catálogo.

https://app.reton.com.br/api/v1Atualizado em 30 de setembro de 2026
Coleção do PostmanOpenAPI 3.1
Navegar na API

Estes endpoints só fazem sentido se a sua loja usa o programa de fidelidade do Reton. Os pontos e o cashback nascem das vendas que você registra — não há endpoint para "dar pontos" avulsos pela API.

Seu programa é de…Como o cliente usa o que juntou
PontosTroca por um prêmio do catálogo: Resgatar recompensa.
CashbackAbate na próxima compra: mande cashbackUsar ao registrar a venda.
CarimbosO cartão completa sozinho com as vendas; a entrega do prêmio é feita no painel do Reton.

Os comandos desta página saem prontos para copiar. A chave fica só nesta aba — não é salva nem enviada.

Consultar saldo

GET/api/v1/fidelidade/saldo

Quanto o cliente tem hoje — já descontado o que venceu — e quanto vence em breve. Pelo celular ou CPF.

É a pergunta do caixa antes de fechar a venda: "quantos pontos você tem?". Envie apenas um parâmetro na URL para dizer quem é o cliente: o celular, ou o documento (CPF/CNPJ), ou o idExterno. Mandar dois na mesma chamada dá erro 400. Ex.: /fidelidade/saldo?celular=11987654321.

O formato da resposta segue o modelo do seu programa (campo modelo). No de pontos, olhe saldoReal; no de cashback, saldoCashback (em reais).

Os números vêm sem formatação: 8024 pontos, 42.5 de cashback. Formate só na hora de mostrar ao cliente — "8.024 pontos", "R$ 42,50". Não troque o ponto por vírgula antes de fazer contas: no JSON, 8.024 seria oito vírgula zero vinte e quatro.

Parâmetros da URL

  • celularstring

    Celular do cliente, com DDD. Com ou sem máscara.

  • documentostring

    CPF ou CNPJ, com ou sem pontuação.

  • idExternostring

    O código do cliente no seu sistema.

  • diasExpiracaointeger

    Janela de "vence em breve", em dias: quanto do saldo vence nos próximos N dias.

    Padrão: 30.

Erros que você deve tratar

  • 400 VALIDATION_ERRORNenhum parâmetro de cliente na URL, ou mais de um; ou diasExpiracao não é um inteiro de 1 a 365.
  • 404 NOT_FOUNDNenhum cliente com esse celular/documento/código na sua conta (ou está na Lixeira).
Requisição
curl "https://app.reton.com.br/api/v1/fidelidade/saldo?celular=11987654321" \  -H "X-API-Key: $RETON_API_KEY"
Ou pelo CPF
# O mesmo saldo, pelo CPF do cliente (só os números)curl "https://app.reton.com.br/api/v1/fidelidade/saldo?documento=52998224725" \  -H "X-API-Key: $RETON_API_KEY"
Resposta · 200 · Programa de pontos
{  "success": true,  "data": {    "contatoId": "con_LC4dQtpwbrLudiRS",    "modelo": "pontos",    "saldoReal": 350,    "pontosExpirando": 50,    "dataExpiracao": "2026-10-15T03:00:00.000Z"  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}
Resposta · 200 · Programa de cashback
{  "success": true,  "data": {    "contatoId": "con_LC4dQtpwbrLudiRS",    "modelo": "cashback",    "saldoPontos": 0,    "saldoCashback": 42.5,    "cashbackExpirando": 12.5,    "cashbackExpiraEm": "2026-10-15T03:00:00.000Z",    "totalAcumulado": 80,    "totalUsado": 37.5,    "minimoParaUsar": 10,    "limitePorUso": {      "tipo": "sem_limite",      "valor": null    }  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}
Resposta · 404 · Cliente não encontrado
{  "success": false,  "error": {    "code": "NOT_FOUND",    "message": "Cliente não encontrado."  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}

Consultar saldo pelo id

GET/api/v1/fidelidade/saldo/:contatoId

O mesmo saldo, para quem já guardou o id do cliente no Reton.

A resposta é igual à de Consultar saldo — só muda como você aponta o cliente.

Parâmetros do caminho

  • contatoIdstringobrigatório

    O id do cliente (con_…).

Parâmetros da URL

  • diasExpiracaointeger

    Janela de "vence em breve", em dias.

    Padrão: 30.

Erros que você deve tratar

  • 400 VALIDATION_ERRORO id não tem o formato con_…, ou diasExpiracao inválido.
  • 404 NOT_FOUNDO cliente não existe na sua conta (ou está na Lixeira).
Requisição
curl "https://app.reton.com.br/api/v1/fidelidade/saldo/con_LC4dQtpwbrLudiRS" \  -H "X-API-Key: $RETON_API_KEY"
Resposta · 200 · Programa de pontos
{  "success": true,  "data": {    "contatoId": "con_LC4dQtpwbrLudiRS",    "modelo": "pontos",    "saldoReal": 350,    "pontosExpirando": 50,    "dataExpiracao": "2026-10-15T03:00:00.000Z"  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}

Resgatar recompensa

POST/api/v1/fidelidade/resgatar

Troca pontos do cliente por um prêmio do seu catálogo e gera o voucher.

O recompensaId (começa com rec_) é o id do prêmio no catálogo do Reton — você o encontra em Fidelidade › Recompensas, no painel. O Reton confere saldo, estoque e as regras do prêmio antes de debitar.

  • canalResgate: "operador" — o prêmio foi entregue na hora, no balcão. O resgate já nasce entregue.
  • canalResgate: "portal" ou "app" (padrão portal) — o cliente pediu e vai retirar depois. O resgate nasce pendente e a loja entrega pelo painel, com o voucher.

Corpo da requisição (JSON)

  • contatoIdstringobrigatório

    O id do cliente (con_…).

  • recompensaIdstringobrigatório

    O id do prêmio (rec_…).

  • quantidadeinteger

    Quantas unidades do prêmio. Gera um voucher para cada.

    Padrão: 1.

  • canalResgatestring

    operador = entregue na hora; portal/app = fica pendente até a retirada.

    Valores: operador, portal, app. Padrão: portal.

  • varianteSelecionadaobject

    Para prêmios com variação: { "tamanho": "M" }. As opções são as cadastradas no prêmio.

  • observacaostring

    Anotação livre.

    Até 1000 caracteres.

  • operadorIdstring

    Quem fez o resgate (op_…). Sem isso, fica com o operador "API".

  • unidadeCodigostring

    Código da loja onde o resgate aconteceu.

    Até 50 caracteres.

  • unidadeIdstring

    Ou o id da loja (uni_…).

Erros que você deve tratar

  • 400 VALIDATION_ERRORCampo inválido; cliente ou prêmio não encontrado; saldo insuficiente; sem estoque; limite de resgates do prêmio atingido. A message diz qual.
Requisição
curl -X POST "https://app.reton.com.br/api/v1/fidelidade/resgatar" \  -H "X-API-Key: $RETON_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "contatoId": "con_LC4dQtpwbrLudiRS",    "recompensaId": "rec_vpyTEeCYIYURK01b",    "canalResgate": "operador"  }'
Resposta · 201 · Resgatado
{  "success": true,  "data": {    "resgateIds": [      "res_WhnxINUFrRdQKFXS"    ],    "voucherCodes": [      "RES-W4S6TY"    ],    "pontosGastos": 100,    "saldoApos": 250  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}
Resposta · 400 · Sem pontos suficientes
{  "success": false,  "error": {    "code": "VALIDATION_ERROR",    "message": "Saldo insuficiente. Tem 80 pontos, precisa de 100"  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}

Listar resgates

GET/api/v1/fidelidade/resgates

Os resgates da sua conta, do mais novo para o mais antigo, com filtros e paginação.

Para percorrer tudo, some limit ao offset a cada página até o offset passar do total.

Parâmetros da URL

  • statusstring

    Só os resgates nesse estado.

    Valores: pendente, entregue, cancelado.

  • buscastring

    Procura no nome ou celular do cliente, no nome do prêmio e no voucher.

  • operadorIdstring

    Só os feitos por esse operador (op_…).

  • limitinteger

    Itens por página (máximo 100).

    Padrão: 20.

  • offsetinteger

    Quantos itens pular.

    Padrão: 0.

Requisição
curl "https://app.reton.com.br/api/v1/fidelidade/resgates?status=pendente&limit=20" \  -H "X-API-Key: $RETON_API_KEY"
Resposta · 200 · Página de resgates
{  "success": true,  "data": {    "items": [      {        "id": "res_WhnxINUFrRdQKFXS",        "voucherCode": "RES-W4S6TY",        "pontosUsados": 100,        "status": "pendente",        "canalResgate": "site",        "varianteSelecionada": null,        "observacao": null,        "motivoCancelamento": null,        "criadoEm": "2026-09-30T14:51:42.608Z",        "entregueEm": null,        "canceladoEm": null,        "contato": {          "id": "con_LC4dQtpwbrLudiRS",          "nome": "Maria",          "celular": "11987654321",          "foto": null        },        "recompensa": {          "id": "rec_vpyTEeCYIYURK01b",          "nome": "Café grátis",          "tipo": "brinde",          "icone": null        },        "operador": {          "id": "op_avNMa0IQROfQV7Nq",          "nome": "API"        },        "canceladoPorNome": null      }    ],    "total": 1,    "limit": 20,    "offset": 0  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}

Consultar resgate

GET/api/v1/fidelidade/resgates/:id

Um resgate pelo id (res_…) ou pelo código do voucher (RES-…).

Útil no balcão: o cliente mostra o voucher, você consulta pelo código e confere se ele ainda está pendente antes de entregar.

Resgates feitos pelo site ou pelo app do cliente aparecem com canalResgate: "site".

Parâmetros do caminho

  • idstringobrigatório

    O id (res_…) ou o voucher (RES-W4S6TY).

Erros que você deve tratar

  • 404 NOT_FOUNDNenhum resgate com esse id ou voucher na sua conta.
Requisição
curl "https://app.reton.com.br/api/v1/fidelidade/resgates/RES-W4S6TY" \  -H "X-API-Key: $RETON_API_KEY"
Resposta · 200 · Resgate
{  "success": true,  "data": {    "id": "res_WhnxINUFrRdQKFXS",    "voucherCode": "RES-W4S6TY",    "pontosUsados": 100,    "status": "entregue",    "canalResgate": "operador",    "varianteSelecionada": null,    "observacao": null,    "motivoCancelamento": null,    "criadoEm": "2026-09-30T14:51:42.608Z",    "entregueEm": "2026-09-30T14:51:42.535Z",    "canceladoEm": null,    "contato": {      "id": "con_LC4dQtpwbrLudiRS",      "nome": "Maria",      "celular": "11987654321"    },    "recompensa": {      "id": "rec_vpyTEeCYIYURK01b",      "nome": "Café grátis",      "tipo": "brinde"    },    "operador": {      "id": "op_avNMa0IQROfQV7Nq",      "nome": "API"    }  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}
Resposta · 404 · Não encontrado
{  "success": false,  "error": {    "code": "NOT_FOUND",    "message": "Resgate não encontrado."  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}

Cancelar resgate

PATCH/api/v1/fidelidade/resgates/:id

Cancela um resgate e devolve os pontos ao cliente.

Aqui o id precisa ser o do resgate (res_…) — o voucher não vale para cancelar.

Parâmetros do caminho

  • idstringobrigatório

    O id do resgate (res_…).

Corpo da requisição (JSON)

  • motivoCancelamentostringobrigatório

    Por que foi cancelado (fica no histórico).

    Até 500 caracteres.

Erros que você deve tratar

  • 400 VALIDATION_ERRORSem motivo; resgate não encontrado; resgate já cancelado. A message diz qual.
Requisição
curl -X PATCH "https://app.reton.com.br/api/v1/fidelidade/resgates/res_WhnxINUFrRdQKFXS" \  -H "X-API-Key: $RETON_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "motivoCancelamento": "Cliente desistiu do prêmio"  }'
Resposta · 200 · Cancelado
{  "success": true,  "data": {    "cancelado": true,    "resgateId": "res_WhnxINUFrRdQKFXS"  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}

Estornar só os pontos de uma venda (exceção)

O ideal é cancelar a venda (Estornar venda): ela sai do faturamento e a pontuação é desfeita junto, e o histórico do cliente fica coerente. Este estorno aqui é diferente: tira só os pontos, o cashback ou o carimbo e deixa a venda valendo.

Quando faz sentido

Só quando a venda aconteceu de verdade (o cliente pagou e levou), mas não devia ter pontuado:

  • uma regra ou promoção estava configurada errada e pontuou quem não devia (ex.: "pontos em dobro" ligado por engano);
  • o produto não participa do programa de fidelidade, mas a venda foi enviada como se participasse;
  • a venda foi para uso interno ou funcionário, que não deveria acumular.
Não use para devolução, venda lançada por engano, valor errado ou cliente errado — aí a venda também está errada, e o certo é cancelá-la (e registrar de novo, se for o caso). Tirar só os pontos deixaria no faturamento uma venda que não existiu.

O que saber antes

  • Saem todos os pontos (ou o cashback, ou o carimbo) daquela venda — não só o excesso. Se ela deu 300 em vez de 150, saem os 300; para devolver os 150 certos, use o Dar pontos no painel.
  • Não dá para desfazer pela API.
  • Se o cliente já usou o que a venda gerou, é recusado (409 ESTORNO_RECOMPENSA_BLOQUEADO).
  • Aponte a venda pelo codigoItem ou pelo interacaoId — nunca pelo codigoTransacao (é uma venda de cada vez).
Requisição
# Tira só a pontuação desta venda; a venda continua no faturamentocurl -X POST "https://app.reton.com.br/api/v1/interacoes/estorno" \  -H "X-API-Key: $RETON_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "codigoItem": "PDV1-000123-1",    "escopo": "recompensa",    "motivo": "Promoção de pontos em dobro ligada por engano"  }'
Resposta · 200
{  "success": true,  "data": {    "interacaoId": "int_b7o9FVDzy4cg1fzk",    "pontosEstornados": 150,    "cashbackEstornado": 0,    "carimbosRevertidos": 0,    "vendaMantida": true  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}
Resposta · 409 (não há o que tirar)
{  "success": false,  "error": {    "code": "SEM_RECOMPENSA",    "message": "Esta venda não gerou ponto, cashback nem carimbo."  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}

Isso foi útil?

Ainda precisa de ajuda?

Não achou o que procurava? A gente responde de gente pra gente.

Falar com a gentesuporte@sac.reton.com.br