API do Reton

Conecte o seu sistema (PDV, ERP, e-commerce) ao Reton: cadastre clientes, registre as vendas deles e estorne — em 5 passos, com o comando pronto para copiar.

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

A API serve para o seu sistema conversar com o Reton sozinho, sem ninguém digitar nada no painel. O uso mais comum: a cada venda fechada no caixa, o seu sistema avisa o Reton — e o cliente ganha os pontos ou o cashback na hora.

  • Formato: JSON, para o endereço do topo da página.
  • Plano: Pro. No Free, as chamadas voltam 403 e nada é gravado.
  • Segurança: chame só do seu servidor — no navegador ou num app de celular, a chave ficaria exposta.
Não quer usar o terminal? Baixe a coleção do Postman (botão no topo) e siga Testar no Postman — as chamadas já vêm prontas.

Passo 1

Gere a sua chave de API

  1. Entre no Reton com um usuário administrador ou gerente.
  2. No menu lateral, abra Configurações.
  3. No grupo Integrações, clique em API e Webhooks.
  4. Clique em Nova chave, dê um nome que identifique a integração (ex.: "PDV loja 1") e clique em Gerar chave.
  5. Copie a chave na hora. Ela começa com sk_live_ e só aparece inteira uma vez. Se perder, gere outra e revogue a antiga.
Crie uma chave para cada integração (uma para o PDV, outra para o e-commerce…). Assim, se uma vazar, você revoga só ela e o resto continua funcionando.

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

Passo 2

Guarde a chave numa variável de ambiente

Trate a chave como uma senha: nada de escrevê-la no código, mandar por WhatsApp ou subir para o GitHub. No servidor, guarde numa variável de ambiente. Para testar no terminal, é assim:

Os exemplos desta documentação são para o terminal do Linux, macOS ou Git Bash (no Windows). No PowerShell do Windows, curl pode ser outro programa e a quebra de linha \ não funciona — use o Git Bash, o WSL, ou o Postman (veja a seção logo abaixo).
Terminal
export RETON_API_KEY="sk_live_cole_a_sua_chave_aqui"

Passo 3

Faça a primeira chamada: cadastre um cliente

Toda venda pertence a um cliente, então comece cadastrando um. Só nome e celular são obrigatórios.

O exemplo ao lado usa poucos campos de propósito — é só para o primeiro teste. O cadastro aceita muito mais (e-mail, CPF, data de nascimento, endereço, etiquetas, aceite de WhatsApp/e-mail, loja, campos personalizados…): veja todos os campos em Cadastrar cliente.

Se ele já existir no Reton, a API não cria outro: responde 409 e mostra quem é em error.details[0].contatoId. Tudo bem — siga para o passo 4.

Não existe ambiente de testes separado: a chave age na sua conta de verdade. Para testar, use você mesmo como cliente (o seu celular), registre a venda do passo 4 e estorne no passo 5 — o estorno tira a venda do faturamento.
Recebeu 401? A chave não chegou ou está errada — confira o passo 2. 403? A conta está no plano Free.
Requisição
curl -X POST "https://app.reton.com.br/api/v1/contatos" \  -H "X-API-Key: $RETON_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "nome": "Maria",    "sobrenome": "Silva",    "celular": "11987654321",    "numeroDocumento": "529.982.247-25",    "idExterno": "CLI-1042"  }'
Resposta · 201 (resumida)
{  "success": true,  "data": {    "id": "con_LC4dQtpwbrLudiRS",    "nome": "Maria",    "sobrenome": "Silva",    "celular": "11987654321",    "…": "…"  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}

Passo 4

Registre uma venda para esse cliente

Mande a venda com o celular do cliente — você não precisa guardar nenhum id do Reton. Também vale o documento (CPF/CNPJ) ou o idExterno. O valor vai em reais com ponto (150.90).

O codigoItem é o número da venda no seu sistema — sempre mande: é ele que deixa você reenviar a mesma venda sem pontuar duas vezes, e estornar depois.

A resposta diz quantos pontos (pontosGerados) ou quanto de cashback (cashbackGerado) a venda deu — dá para imprimir no cupom. Voltou 404? O cliente não está no Reton: volte ao passo 3.

A venda só gera pontos, cashback ou carimbo se o programa de fidelidade estiver ligado. No Reton, abra Fidelidade › Configuração e escolha o modelo (pontos, cashback ou carimbos) e as regras. Sem isso, a venda é registrada normalmente — entra no faturamento e no histórico do cliente —, mas pontosGerados e cashbackGerado voltam 0. Passo a passo: Ativar o módulo de fidelidade.
Requisição
curl -X POST "https://app.reton.com.br/api/v1/interacoes" \  -H "X-API-Key: $RETON_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "celular": "11987654321",    "valor": 150.9,    "codigoItem": "PDV1-000123-1",    "dataHora": "2026-09-30T14:30:00-03:00"  }'
Ou pelo CPF
# Mesma venda, identificando o cliente pelo CPF (com ou sem pontuação)curl -X POST "https://app.reton.com.br/api/v1/interacoes" \  -H "X-API-Key: $RETON_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "documento": "529.982.247-25",    "valor": 150.9,    "codigoItem": "PDV1-000123-1",    "dataHora": "2026-09-30T14:30:00-03:00"  }'
Resposta · 201
{  "success": true,  "data": {    "interacaoId": "int_b7o9FVDzy4cg1fzk",    "contatoId": "con_LC4dQtpwbrLudiRS",    "pontosGerados": 150,    "valorBruto": 150.9,    "cashbackGerado": 0,    "…": "…"  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}

Passo 5

Se a venda for cancelada, estorne

Cliente devolveu? Mande o estorno com o mesmo codigoItem. A venda sai do faturamento e os pontos dela são retirados do cliente.

Valor ou cliente errado? Estorne e registre de novo, certo — com um codigoItem novo. Detalhes em Estornar venda.

Requisição
curl -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",    "motivo": "Cliente devolveu o produto"  }'

Pronto: o fluxo que o seu sistema vai seguir

Juntando tudo, a cada venda fechada no seu sistema:

  1. Cliente novo no seu sistema? Cadastre no Reton: POST /contatos. Se ele já existia lá, a API responde 409 — tudo bem, siga.
  2. Registre a venda: POST /interacoes com o celular (ou o CPF) do cliente e o codigoItem.
  3. Voltou 404? O cliente não está no Reton — cadastre e mande a mesma venda de novo.
  4. Falhou por rede ou deu 500? Espere alguns segundos e repita a venda igualzinha — o codigoItem impede que ela conte duas vezes.
  5. Venda cancelada depois? POST /interacoes/estorno com o mesmo codigoItem.
  6. Quer mostrar o saldo no caixa? GET /fidelidade/saldo?celular=….

Daqui para frente: Autenticação · Erros · Contatos · Vendas · Fidelidade · Lojas.

Prefere testar no Postman? (sem terminal)

Baixe a coleção do Postman (botão no topo desta página): ela já vem com todas as chamadas desta documentação montadas, com os exemplos preenchidos e a chave configurada em um lugar só.

  1. No Postman, clique em Import e escolha o arquivo reton.postman_collection.json.
  2. Clique na coleção API do Reton › aba Variables. Em RETON_API_KEY, cole a sua chave na coluna Current value e salve (Ctrl+S).
  3. Abra Vendas › Registrar venda, troque o celular por um de verdade e clique em Send.
No Postman, variável se escreve com chaves duplas: {{RETON_API_KEY}}. O $RETON_API_KEY dos comandos desta página é do terminal — colado no Postman, ele vai como texto e a resposta é 401.
A coleção aponta para produção (baseUrl). Todas as requisições herdam a chave da coleção — não precisa pôr o cabeçalho X-API-Key em cada uma.

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