Vendas

Registre cada venda no Reton — ela gera pontos ou cashback e mantém o cliente fora do risco — e estorne quando for cancelada.

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

Cada venda que você manda alimenta tudo o que o Reton faz com aquele cliente: gera pontos, cashback ou carimbo (se você usa o programa de fidelidade), zera a contagem de "dias sem comprar" e entra nos relatórios de faturamento.

No Reton, uma venda é tecnicamente uma interação — é por isso que o endereço é /interacoes. Onde esta página diz "venda", o sistema diz "interação"; é a mesma coisa.

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

Registrar venda

POST/api/v1/interacoes

Grava uma venda para um cliente e devolve os pontos/cashback que ela gerou.

O mínimo é quem comprou e o valor em reais, com ponto decimal: 150.90, não 15090 nem "150,90".

Quem comprou: mande o celular ou o CPF

Você não precisa do id do Reton: mande o que o caixa tem na mão — celular, documento (CPF/CNPJ) ou idExterno (o código do cliente no seu sistema). O celular pode vir com ou sem máscara e com ou sem o 55. Se já tiver guardado o contatoId, também vale.

Pode mandar mais de um. O Reton tenta nesta ordem e fica com o primeiro que achar: contatoId → documento → celular → idExterno. Mandar CPF e celular juntos ajuda: um cliente cadastrado só com o celular ainda é encontrado quando o CPF não bate.

Cliente não encontrado? A resposta é 404 e a venda não é gravada — o Reton não cadastra cliente sozinho. Cadastre o cliente e mande a mesma venda de novo.
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.

Sempre mande o codigoItem

O codigoItem é o número da venda no seu sistema (ou o número do item, se você manda item por item). Ele faz duas coisas: deixa você reenviar sem medo e permite estornar depois pelo mesmo código.

  • Reenviar é seguro: se a sua chamada deu timeout e você não sabe se a venda entrou, mande de novo igualzinha. Se ela já tinha entrado, o Reton responde 200 (e não erro) com os mesmos campos da primeira resposta, mais duplicada: true — sem pontuar duas vezes nem descontar cashback de novo. Só regraAplicada, percentualAplicado e lotesConsumidos não voltam no reenvio.
  • Sem o código, o Reton se protege sozinho: uma segunda venda idêntica (mesmo cliente, mesmo valor, mesmo dia e mesma observação) é recusada com 409 INTERACAO_DUPLICADA. Se o cliente realmente comprou duas vezes a mesma coisa no dia, mande um codigoItem diferente para cada.

Uma chamada por venda ou por item?

O mais simples é uma chamada por venda, com codigoItem = número da venda. Se você quer poder cancelar um item de uma venda com vários, mande uma chamada por item: codigoItem = código daquele item e codigoTransacao = número da venda (o mesmo em todos os itens). Aí dá para estornar um item pelo codigoItem ou a venda inteira pelo codigoTransacao.

Mande a dataHora da venda com o fuso: 2026-09-30T14:30:00-03:00. Sem ela, o Reton usa o momento em que recebeu a chamada — o que atrapalha quando você envia vendas atrasadas.

Corpo da requisição (JSON)

  • celularstring

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

    Até 20 caracteres.

  • documentostring

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

    Até 20 caracteres.

  • idExternostring

    O código do cliente no seu sistema (o mesmo enviado no cadastro).

    Até 100 caracteres.

  • contatoIdstring

    Ou o id do cliente no Reton (con_…). Pelo menos um destes quatro é obrigatório.

  • valornumberobrigatório

    Valor da venda em reais, com ponto decimal: 150.90.

  • codigoItemstring

    Número da venda (ou do item) no seu sistema. Único na sua conta — é o que torna o reenvio seguro.

    Até 100 caracteres.

  • codigoTransacaostring

    Número da venda quando você manda item por item. Permite estornar a venda inteira de uma vez.

    Até 100 caracteres.

  • dataHorastring

    Quando a venda aconteceu, com fuso (2026-09-30T14:30:00-03:00 ou …Z). Padrão: agora.

  • tagsstring[]

    Categorias da venda (até 20). Servem para as regras de pontuação "por categoria" que você cria no Reton. Se mandar tags, o campo categoria é ignorado.

  • categoriastring

    Uma categoria só, em texto. Prefira tags.

    Até 100 caracteres.

  • observacaostring

    Descrição livre da venda (ex.: o que foi comprado).

    Até 1000 caracteres.

  • cashbackUsarnumber

    Quanto do saldo de cashback o cliente quer usar nesta compra, em reais. Se o saldo não cobrir, a venda é recusada (nada é gravado).

  • cupomstring

    Código de cupom de desconto do Reton. Não combina com cashbackUsar na mesma venda.

    Até 50 caracteres.

  • operadorIdstring

    O vendedor (op_…), se você quer atribuir a venda a ele. Sem isso, a venda fica com o operador "API".

Erros que você deve tratar

  • 400 VALIDATION_ERRORCampo faltando ou inválido (inclusive nenhum jeito de identificar o cliente); saldo de cashback insuficiente; cupom inválido; cupom junto com cashback. A message diz qual.
  • 404 NOT_FOUNDNenhum cliente com esse celular, documento, idExterno ou id (ou ele está na Lixeira). Cadastre e reenvie.
  • 409 INTERACAO_DUPLICADAVenda idêntica no mesmo dia, sem codigoItem.
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": "(11) 98765-4321",    "valor": 150.9,    "codigoItem": "PDV1-000123-1",    "dataHora": "2026-09-30T14:30:00-03:00",    "observacao": "Ração 15kg"  }'
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 · Venda registrada
{  "success": true,  "data": {    "interacaoId": "int_b7o9FVDzy4cg1fzk",    "contatoId": "con_LC4dQtpwbrLudiRS",    "pontosGerados": 150,    "valorBruto": 150.9,    "cashbackUsado": 0,    "valorLiquido": 150.9,    "cashbackGerado": 0,    "regraAplicada": null,    "percentualAplicado": null,    "lotesConsumidos": [],    "cupomAplicado": null,    "cupomDesconto": 0  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}
Resposta · 200 · Reenvio (já tinha entrado)
{  "success": true,  "data": {    "interacaoId": "int_b7o9FVDzy4cg1fzk",    "contatoId": "con_LC4dQtpwbrLudiRS",    "duplicada": true,    "mensagem": "Esta venda (codigoItem 'PDV1-000123-1') já tinha sido registrada. Nada foi somado de novo.",    "dataHora": "2026-09-30T17:30:00.000Z",    "estornada": false,    "pontosGerados": 150,    "valorBruto": 150.9,    "cashbackUsado": 0,    "valorLiquido": 150.9,    "cashbackGerado": 0,    "cupomAplicado": null,    "cupomDesconto": 0  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}
Resposta · 404 · Cliente não encontrado
{  "success": false,  "error": {    "code": "NOT_FOUND",    "message": "Cliente não encontrado. Cadastre-o em POST /api/v1/contatos e envie a venda de novo."  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}
Resposta · 409 · Venda idêntica sem codigoItem
{  "success": false,  "error": {    "code": "INTERACAO_DUPLICADA",    "message": "Já existe uma interação idêntica para este contato hoje (mesmo valor e descrição). Para registrar uma segunda compra igual, altere a descrição ou envie um codigoItem.",    "details": [      {        "contatoId": "con_LC4dQtpwbrLudiRS",        "valor": 150.9,        "data": "2026-09-30"      }    ]  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}

Estornar (cancelar) uma venda

POST/api/v1/interacoes/estorno

Desfaz uma venda que não valeu: tira do faturamento e retira os pontos, o cashback ou o carimbo que ela deu.

Use quando a venda não deveria existir no Reton. O estorno faz duas coisas de uma vez: tira a venda do faturamento (ela sai dos relatórios de receita) e desfaz tudo o que ela gerou para o cliente — pontos, cashback ou carimbo. Se ele usou um cupom nessa compra, o cupom volta para ele.

Quando usar

  • O cliente devolveu o produto e recebeu o dinheiro de volta.
  • A venda foi cancelada no caixa ou no seu sistema.
  • A venda foi lançada por engano (em duplicidade, de teste, sem ter acontecido).
  • O valor ou o cliente estavam errados: estorne e registre de novo, certo. ⚠️ Use um codigoItem novo no registro corrigido (ex.: PDV1-000123-1-R) — com o mesmo código, o Reton devolve a venda antiga, já estornada, em vez de gravar a nova.

Como dizer qual venda

  • codigoItem — a venda (ou o item) que você mandou com esse código;
  • codigoTransacao — todos os itens daquela venda de uma vez;
  • interacaoId — o id que o Reton devolveu no registro (int_…).
Se o cliente já usou os pontos ou o cashback daquela venda (trocou por um prêmio, por exemplo), o estorno é recusado com 409 ESTORNO_PONTOS_UTILIZADOS — tirar o que ele já gastou deixaria o saldo negativo. Cancele o resgate antes, ou resolva pelo painel do Reton.
A venda aconteceu de verdade, mas não devia ter dado pontos? Existe um estorno só da pontuação, que mantém a venda — mas é exceção, com restrições. Veja Estornar só os pontos antes de usar.

Corpo da requisição (JSON)

  • codigoItemstring

    Código da venda/item enviado no registro.

    Até 100 caracteres.

  • codigoTransacaostring

    Número da venda: estorna todos os itens dela. Não vale com escopo: "recompensa".

    Até 100 caracteres.

  • interacaoIdstring

    O id da venda no Reton (int_…).

    Até 60 caracteres.

  • escopostring

    Deixe o padrão venda (cancela a venda e desfaz a pontuação). recompensa é a exceção que mantém a venda — veja Estornar só os pontos.

    Valores: venda, recompensa. Padrão: venda.

  • motivostring

    Por que foi estornada (fica no histórico do cliente).

    Até 500 caracteres.

Erros que você deve tratar

  • 400 VALIDATION_ERRORNenhum dos três identificadores, ou escopo: "recompensa" com codigoTransacao.
  • 404 INTERACAO_NAO_ENCONTRADANenhuma venda com esse código ou id na sua conta.
  • 409 INTERACAO_JA_ESTORNADAEssa venda já foi estornada (se um item de uma venda já foi, a venda inteira é recusada).
  • 409 ESTORNO_PONTOS_UTILIZADOSO cliente já usou o que a venda gerou. details diz quanto e por quê.
  • 409 SEM_RECOMPENSASó com escopo: "recompensa" — a venda não gerou nada para tirar.
  • 409 ESTORNO_RECOMPENSA_BLOQUEADOSó com escopo: "recompensa" — a pontuação já foi estornada, a venda já foi cancelada ou o cliente já usou.
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"  }'
Resposta · 200 · Venda cancelada
{  "success": true,  "data": {    "estornados": [      {        "interacaoEspelhoId": "int_iFlDF9h5SD8GEQVQ",        "pontosEstornados": 150,        "cashbackEstornado": 0,        "carimbosRevertidos": 0,        "cupomDevolvido": null      }    ],    "totalPontosEstornados": 150,    "totalCashbackEstornado": 0,    "totalInteracoes": 1  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}
Resposta · 409 · Cliente já usou os pontos
{  "success": false,  "error": {    "code": "ESTORNO_PONTOS_UTILIZADOS",    "message": "Não é possível estornar. O cliente já usou 100 dos 150 pontos desta venda.",    "details": [      {        "pontosOriginal": 150,        "pontosUtilizados": 100,        "pontosDisponiveis": 50,        "cashbackOriginal": 0,        "cashbackUtilizado": 0,        "cashbackDisponivel": 0,        "impedimentos": [          {            "interacaoId": "int_b7o9FVDzy4cg1fzk",            "codigoItem": "PDV1-000123-1",            "motivos": [              {                "codigo": "pontos_utilizados",                "mensagem": "O cliente já usou 100 dos 150 pontos desta venda."              }            ]          }        ],        "dica": "Cancele o resgate/uso associado antes de estornar, ou faça um ajuste manual pela tela do Reton."      }    ]  },  "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