Contatos (clientes)

Localize um cliente pelo celular, CPF, e-mail ou pelo código do seu sistema; cadastre quem ainda não existe; consulte e exclua.

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

No Reton, cada cliente da sua loja é um contato, e toda venda, ponto e mensagem fica pendurado nele. Cada contato tem um id que começa com con_.

Para registrar uma venda você nem precisa do id: mande a venda pelo celular ou CPF. Esta página serve para cadastrar quem ainda não existe (a venda volta 404) e para consultar ou conferir os dados de um cliente.

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

Localizar cliente

GET/api/v1/contatos

Procura o cliente por celular, CPF/CNPJ, e-mail ou pelo código do seu sistema.

Envie apenas um parâmetro na URL: o celular, ou o documento (CPF/CNPJ), ou o email, ou o idExterno. Mandar dois na mesma chamada dá erro 400. Ex.: /contatos?celular=11987654321.

Se ninguém for encontrado, a resposta é 200 com total: 0 e a lista vazia — não é erro: é o sinal para você cadastrar o cliente.

O celular é comparado sem máscara, sem o 55 e com ou sem o 9 da frente — (11) 98765-4321 acha quem foi cadastrado como 11987654321. Por isso a lista pode, raramente, trazer duas pessoas: a primeira é a que bate exatamente com o que você mandou.

Clientes que estão na Lixeira do Reton não aparecem na busca.

Parâmetros da URL

  • celularstring

    Celular com DDD, com ou sem máscara.

  • documentostring

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

  • emailstring

    E-mail (maiúsculas e minúsculas não importam).

  • idExternostring

    O código do cliente no seu sistema, enviado no cadastro.

Erros que você deve tratar

  • 400 VALIDATION_ERRORNenhum parâmetro na URL, ou mais de um na mesma chamada.
Requisição
curl "https://app.reton.com.br/api/v1/contatos?celular=11987654321" \  -H "X-API-Key: $RETON_API_KEY"
Resposta · 200 · Encontrado
{  "success": true,  "data": {    "total": 1,    "contatos": [      {        "id": "con_LC4dQtpwbrLudiRS",        "nome": "Maria",        "sobrenome": "Silva",        "celular": "11987654321",        "email": "maria.silva@email.com",        "tipoPessoa": "pf",        "tipoDocumento": "cpf",        "numeroDocumento": "52998224725",        "dataNascimento": "1990-05-15T00:00:00.000Z",        "tags": [          "vip"        ],        "idExterno": "CLI-1042",        "origemPlataforma": "api:PDV loja 1",        "classificacao": "saudavel",        "ativo": true,        "optinWhatsapp": true,        "optinEmail": false,        "optinSms": false,        "unidadeId": null,        "unidadeCodigo": null,        "unidadeNome": null,        "customFields": {},        "canalCadastro": "api",        "criadoEm": "2026-09-30T14:51:34.294Z",        "atualizadoEm": "2026-09-30T14:51:34.556Z"      }    ]  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}
Resposta · 200 · Ninguém com esse celular
{  "success": true,  "data": {    "total": 0,    "contatos": []  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}

Consultar cliente

GET/api/v1/contatos/:id

Traz um cliente pelo id do Reton.

A resposta tem o mesmo formato de cada item da busca. Para o saldo de pontos ou cashback, use Consultar saldo — ele desconta o que já venceu.

Parâmetros do caminho

  • idstringobrigatório

    O id do contato (con_…).

Erros que você deve tratar

  • 400 VALIDATION_ERRORO id não tem o formato con_….
  • 404 NOT_FOUNDNão existe na sua conta, ou está na Lixeira.
Requisição
curl "https://app.reton.com.br/api/v1/contatos/con_LC4dQtpwbrLudiRS" \  -H "X-API-Key: $RETON_API_KEY"
Resposta · 200 · Cliente
{  "success": true,  "data": {    "id": "con_LC4dQtpwbrLudiRS",    "nome": "Maria",    "sobrenome": "Silva",    "celular": "11987654321",    "email": "maria.silva@email.com",    "tipoPessoa": "pf",    "tipoDocumento": "cpf",    "numeroDocumento": "52998224725",    "dataNascimento": "1990-05-15T00:00:00.000Z",    "tags": [      "vip"    ],    "idExterno": "CLI-1042",    "origemPlataforma": "api:PDV loja 1",    "classificacao": "saudavel",    "ativo": true,    "optinWhatsapp": true,    "optinEmail": false,    "optinSms": false,    "unidadeId": null,    "unidadeCodigo": null,    "unidadeNome": null,    "customFields": {},    "canalCadastro": "api",    "criadoEm": "2026-09-30T14:51:34.294Z",    "atualizadoEm": "2026-09-30T14:51:34.556Z"  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}
Resposta · 404 · Não existe (ou está na Lixeira)
{  "success": false,  "error": {    "code": "NOT_FOUND",    "message": "Contato não encontrado."  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}

Cadastrar cliente

POST/api/v1/contatos

Cria um cliente. Só nome e celular são obrigatórios.

Mande o que você tiver — o mínimo é nome e celular. Ao lado há dois exemplos: um enxuto e um com todos os campos de pessoa física; a lista completa, com o que cada campo aceita, está logo abaixo. Para cliente pessoa jurídica, use tipoPessoa: "pj", tipoDocumento: "cnpj" e os campos nomeFantasia, nomeContato, cargo e inscricaoEstadual.

E se o cliente já existir? O Reton não cria em dobro: responde 409 e diz quem já tem aquele celular ou CPF em error.details[0].contatoId. Use esse id e siga em frente.

Só marque optinWhatsapp / optinEmail / optinSms como true se o cliente realmente aceitou receber mensagens: é o registro do consentimento dele (LGPD).

Corpo da requisição (JSON)

  • nomestringobrigatório

    Primeiro nome do cliente.

    Até 255 caracteres.

  • celularstringobrigatório

    Celular com DDD. Pode vir com ou sem máscara e com ou sem o 55: (11) 98765-4321, 11987654321 e 5511987654321 são o mesmo número. O Reton guarda só os dígitos.

    Até 20 caracteres.

  • sobrenomestring

    Sobrenome.

    Até 255 caracteres.

  • emailstring

    E-mail do cliente.

    Até 255 caracteres.

  • numeroDocumentostring

    CPF ou CNPJ, com ou sem pontuação. Não pode repetir o de outro cliente seu.

    Até 20 caracteres.

  • tipoDocumentostring

    Que documento é o numeroDocumento.

    Valores: cpf, cnpj, passaporte, rne, outro. Padrão: cpf.

  • tipoPessoastring

    Pessoa física (pf) ou jurídica (pj).

    Valores: pf, pj. Padrão: pf.

  • dataNascimentostring

    Data de nascimento: 1990-05-15. Também aceita data e hora com fuso (1990-05-15T00:00:00-03:00).

  • sexostring

    Sexo.

    Valores: masculino, feminino, outro.

  • idExternostring

    O código deste cliente no seu sistema. Guarde-o aqui para depois achar o cliente por ele (GET /contatos?idExterno=).

    Até 100 caracteres.

  • tagsstring[]

    Etiquetas (até 20, de até 50 caracteres cada). Viram minúsculas.

  • optinWhatsappboolean

    O cliente aceitou receber mensagens por WhatsApp.

    Padrão: false.

  • optinEmailboolean

    O cliente aceitou receber e-mails.

    Padrão: false.

  • optinSmsboolean

    O cliente aceitou receber SMS.

    Padrão: false.

  • unidadeCodigostring

    Código da loja onde o cliente foi cadastrado (o mesmo codigo de Lojas).

    Até 50 caracteres.

  • unidadeIdstring

    Ou o id da loja (uni_…), no lugar do código.

  • notasstring

    Anotação livre sobre o cliente.

    Até 5000 caracteres.

  • customFieldsobject

    Campos personalizados que você criou no Reton (Configurações › Campos personalizados). A chave é o nome interno do campo; o valor é conferido pelo tipo dele.

  • cepstring

    CEP.

    Até 10 caracteres.

  • logradourostring

    Rua, avenida…

    Até 255 caracteres.

  • numerostring

    Número do endereço.

    Até 20 caracteres.

  • complementostring

    Complemento.

    Até 255 caracteres.

  • bairrostring

    Bairro.

    Até 100 caracteres.

  • cidadestring

    Cidade.

    Até 100 caracteres.

  • estadostring

    UF, com duas letras (SP).

    Até 2 caracteres.

  • nomeFantasiastring

    Pessoa jurídica: nome fantasia.

    Até 255 caracteres.

  • nomeContatostring

    Pessoa jurídica: com quem falar.

    Até 255 caracteres.

  • cargostring

    Pessoa jurídica: cargo de quem fala.

    Até 100 caracteres.

  • inscricaoEstadualstring

    Pessoa jurídica: inscrição estadual.

    Até 20 caracteres.

  • origemCadastrostring

    Por onde o cliente chegou (texto livre, para seus relatórios).

    Até 50 caracteres.

  • origemPlataformastring

    De qual sistema veio o cadastro. Se não enviar, o Reton grava api: + o nome da chave usada.

    Até 50 caracteres.

Erros que você deve tratar

  • 400 VALIDATION_ERRORCampo faltando ou em formato errado — error.details lista quais. Também quando a loja informada não existe.
  • 409 CONFLICTJá há um cliente com esse celular (motivo: "celular") ou CPF/CNPJ (motivo: "documento"). O id dele vem em details[0].contatoId.
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": "(11) 98765-4321",    "email": "maria.silva@email.com",    "numeroDocumento": "529.982.247-25",    "dataNascimento": "1990-05-15",    "idExterno": "CLI-1042",    "optinWhatsapp": true  }'
Com todos os campos
# Todos os campos de pessoa física. Apague os que não usar.# unidadeCodigo e customFields precisam existir no seu Reton.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": "(11) 98765-4321",    "email": "maria.silva@email.com",    "tipoPessoa": "pf",    "tipoDocumento": "cpf",    "numeroDocumento": "529.982.247-25",    "dataNascimento": "1990-05-15",    "sexo": "feminino",    "idExterno": "CLI-1042",    "tags": [      "vip",      "cliente-antigo"    ],    "optinWhatsapp": true,    "optinEmail": true,    "optinSms": false,    "unidadeCodigo": "LJ01",    "notas": "Prefere ser atendida pela manhã.",    "customFields": {      "tamanho_calcado": "36"    },    "cep": "01310-100",    "logradouro": "Avenida Paulista",    "numero": "1000",    "complemento": "Apto 12",    "bairro": "Bela Vista",    "cidade": "São Paulo",    "estado": "SP",    "origemCadastro": "Loja física",    "origemPlataforma": "PDV Loja 1"  }'
Resposta · 201 · Cadastrado
{  "success": true,  "data": {    "id": "con_LC4dQtpwbrLudiRS",    "nome": "Maria",    "sobrenome": "Silva",    "celular": "11987654321",    "email": "maria.silva@email.com",    "tipoPessoa": "pf",    "tags": [],    "pontosSaldo": 0,    "classificacao": "saudavel",    "ativo": true,    "unidadeId": null,    "unidadeCodigo": null,    "unidadeNome": null,    "customFields": {},    "canalCadastro": "api",    "criadoPor": {      "tipo": "api",      "apiKeyId": "key_LgypViyLXFkaiQWx",      "apiKeyNome": "PDV loja 1",      "apiKeyHashPrefix": "57b4c78c"    },    "criadoEm": "2026-09-30T14:51:34.294Z"  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}
Resposta · 409 · Já existe
{  "success": false,  "error": {    "code": "CONFLICT",    "message": "Já existe um contato com o celular 11987654321: \"Maria\" (con_LC4dQtpwbrLudiRS).",    "details": [      {        "motivo": "celular",        "contatoId": "con_LC4dQtpwbrLudiRS"      }    ]  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}
Resposta · 400 · Dado inválido
{  "success": false,  "error": {    "code": "VALIDATION_ERROR",    "message": "Erro de validação nos dados enviados.",    "details": [      {        "field": "email",        "message": "email inválido",        "code": "invalid_format"      }    ]  },  "meta": {    "requestId": "req_V1StGXR8Z5jdHi6B"  }}

Excluir cliente

DELETE/api/v1/contatos/:id

Manda o cliente para a Lixeira do Reton (dá para restaurar no painel por 90 dias).

A exclusão pela API não apaga de vez: o cliente vai para a Lixeira, some das listas e da busca, e pode ser restaurado no painel por 90 dias. Depois disso, é apagado definitivamente.

Parâmetros do caminho

  • idstringobrigatório

    O id do contato (con_…).

Erros que você deve tratar

  • 400 VALIDATION_ERRORO id não tem o formato con_….
  • 404 NOT_FOUNDNão existe, ou já está na Lixeira.
Requisição
curl -X DELETE "https://app.reton.com.br/api/v1/contatos/con_LC4dQtpwbrLudiRS" \  -H "X-API-Key: $RETON_API_KEY"
Resposta · 200 · Na Lixeira
{  "success": true,  "data": {    "id": "con_LC4dQtpwbrLudiRS",    "deletado": true,    "deletadoEm": "2026-09-30T15:02:11.482Z"  },  "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