{"openapi":"3.1.0","info":{"title":"API do Reton","version":"1.0.0","description":"Cadastre clientes, registre vendas, estorne e consulte a fidelidade da sua conta no Reton. Documentação completa: https://reton.com.br/ajuda/api"},"servers":[{"url":"https://app.reton.com.br/api/v1"}],"security":[{"ChaveApi":[]}],"components":{"securitySchemes":{"ChaveApi":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Gerada em Configurações › API e Webhooks, no painel do Reton."}}},"tags":[{"name":"Contatos","description":"Localize um cliente pelo celular, CPF, e-mail ou pelo código do seu sistema; cadastre quem ainda não existe; consulte e exclua."},{"name":"Vendas","description":"Registre cada venda no Reton — ela gera pontos ou cashback e mantém o cliente fora do risco — e estorne quando for cancelada."},{"name":"Fidelidade","description":"Mostre ao cliente quanto ele tem de pontos ou cashback e deixe ele trocar pontos por prêmios do seu catálogo."},{"name":"Lojas","description":"Liste e mantenha as lojas da sua rede, para separar clientes, vendas e relatórios por loja."}],"paths":{"/contatos":{"get":{"operationId":"localizar-contato","summary":"Localizar cliente","description":"Procura o cliente por celular, CPF/CNPJ, e-mail ou pelo código do seu sistema.","tags":["Contatos"],"parameters":[{"name":"celular","in":"query","required":false,"description":"Celular com DDD, com ou sem máscara.","schema":{"type":"string","description":"Celular com DDD, com ou sem máscara.","example":"11987654321"}},{"name":"documento","in":"query","required":false,"description":"CPF ou CNPJ, com ou sem pontuação.","schema":{"type":"string","description":"CPF ou CNPJ, com ou sem pontuação.","example":"52998224725"}},{"name":"email","in":"query","required":false,"description":"E-mail (maiúsculas e minúsculas não importam).","schema":{"type":"string","description":"E-mail (maiúsculas e minúsculas não importam).","format":"email","example":"maria.silva@email.com"}},{"name":"idExterno","in":"query","required":false,"description":"O código do cliente no seu sistema, enviado no cadastro.","schema":{"type":"string","description":"O código do cliente no seu sistema, enviado no cadastro.","example":"CLI-1042"}}],"responses":{"200":{"description":"Encontrado / Ninguém com esse celular","content":{"application/json":{"examples":{"exemplo1":{"summary":"Encontrado","value":{"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"}}},"exemplo2":{"summary":"Ninguém com esse celular","value":{"success":true,"data":{"total":0,"contatos":[]},"meta":{"requestId":"req_V1StGXR8Z5jdHi6B"}}}}}}},"400":{"description":"VALIDATION_ERROR: Nenhum parâmetro na URL, ou mais de um na mesma chamada."},"401":{"description":"UNAUTHORIZED: chave de API ausente, inválida ou revogada."},"403":{"description":"FORBIDDEN: a conta não está num plano com API (Pro)."}}},"post":{"operationId":"cadastrar-contato","summary":"Cadastrar cliente","description":"Cria um cliente. Só nome e celular são obrigatórios.","tags":["Contatos"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nome","celular"],"properties":{"nome":{"type":"string","description":"Primeiro nome do cliente.","maxLength":255},"celular":{"type":"string","description":"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.","minLength":8,"maxLength":20},"sobrenome":{"type":"string","description":"Sobrenome.","maxLength":255},"email":{"type":"string","description":"E-mail do cliente.","format":"email","maxLength":255},"numeroDocumento":{"type":"string","description":"CPF ou CNPJ, com ou sem pontuação. Não pode repetir o de outro cliente seu.","maxLength":20},"tipoDocumento":{"type":"string","description":"Que documento é o numeroDocumento.","enum":["cpf","cnpj","passaporte","rne","outro"],"default":"cpf"},"tipoPessoa":{"type":"string","description":"Pessoa física (pf) ou jurídica (pj).","enum":["pf","pj"],"default":"pf"},"dataNascimento":{"type":"string","description":"Data de nascimento: 1990-05-15. Também aceita data e hora com fuso (1990-05-15T00:00:00-03:00).","format":"date"},"sexo":{"type":"string","description":"Sexo.","enum":["masculino","feminino","outro"]},"idExterno":{"type":"string","description":"O código deste cliente no seu sistema. Guarde-o aqui para depois achar o cliente por ele (GET /contatos?idExterno=).","maxLength":100},"tags":{"type":"array","items":{"type":"string"},"description":"Etiquetas (até 20, de até 50 caracteres cada). Viram minúsculas."},"optinWhatsapp":{"type":"boolean","description":"O cliente aceitou receber mensagens por WhatsApp.","default":false},"optinEmail":{"type":"boolean","description":"O cliente aceitou receber e-mails.","default":false},"optinSms":{"type":"boolean","description":"O cliente aceitou receber SMS.","default":false},"unidadeCodigo":{"type":"string","description":"Código da loja onde o cliente foi cadastrado (o mesmo codigo de Lojas).","maxLength":50},"unidadeId":{"type":"string","description":"Ou o id da loja (uni_…), no lugar do código."},"notas":{"type":"string","description":"Anotação livre sobre o cliente.","maxLength":5000},"customFields":{"type":"object","description":"Campos personalizados que você criou no Reton (Configurações › Campos personalizados). A chave é o nome interno do campo; o valor é conferido pelo tipo dele."},"cep":{"type":"string","description":"CEP.","maxLength":10},"logradouro":{"type":"string","description":"Rua, avenida…","maxLength":255},"numero":{"type":"string","description":"Número do endereço.","maxLength":20},"complemento":{"type":"string","description":"Complemento.","maxLength":255},"bairro":{"type":"string","description":"Bairro.","maxLength":100},"cidade":{"type":"string","description":"Cidade.","maxLength":100},"estado":{"type":"string","description":"UF, com duas letras (SP).","maxLength":2},"nomeFantasia":{"type":"string","description":"Pessoa jurídica: nome fantasia.","maxLength":255},"nomeContato":{"type":"string","description":"Pessoa jurídica: com quem falar.","maxLength":255},"cargo":{"type":"string","description":"Pessoa jurídica: cargo de quem fala.","maxLength":100},"inscricaoEstadual":{"type":"string","description":"Pessoa jurídica: inscrição estadual.","maxLength":20},"origemCadastro":{"type":"string","description":"Por onde o cliente chegou (texto livre, para seus relatórios).","maxLength":50},"origemPlataforma":{"type":"string","description":"De qual sistema veio o cadastro. Se não enviar, o Reton grava api: + o nome da chave usada.","maxLength":50}}},"examples":{"principal":{"summary":"Exemplo","value":{"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}},"variacao1":{"summary":"Com todos os campos","value":{"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"}}}}}},"responses":{"201":{"description":"Cadastrado","content":{"application/json":{"examples":{"exemplo1":{"summary":"Cadastrado","value":{"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"}}}}}}},"400":{"description":"Dado inválido","content":{"application/json":{"examples":{"exemplo1":{"summary":"Dado inválido","value":{"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"}}}}}}},"401":{"description":"UNAUTHORIZED: chave de API ausente, inválida ou revogada."},"403":{"description":"FORBIDDEN: a conta não está num plano com API (Pro)."},"409":{"description":"Já existe","content":{"application/json":{"examples":{"exemplo1":{"summary":"Já existe","value":{"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"}}}}}}}}}},"/contatos/{id}":{"get":{"operationId":"consultar-contato","summary":"Consultar cliente","description":"Traz um cliente pelo id do Reton.","tags":["Contatos"],"parameters":[{"name":"id","in":"path","required":true,"description":"O id do contato (con_…).","schema":{"type":"string","description":"O id do contato (con_…).","example":"con_LC4dQtpwbrLudiRS"}}],"responses":{"200":{"description":"Cliente","content":{"application/json":{"examples":{"exemplo1":{"summary":"Cliente","value":{"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"}}}}}}},"400":{"description":"VALIDATION_ERROR: O id não tem o formato con_…."},"401":{"description":"UNAUTHORIZED: chave de API ausente, inválida ou revogada."},"403":{"description":"FORBIDDEN: a conta não está num plano com API (Pro)."},"404":{"description":"Não existe (ou está na Lixeira)","content":{"application/json":{"examples":{"exemplo1":{"summary":"Não existe (ou está na Lixeira)","value":{"success":false,"error":{"code":"NOT_FOUND","message":"Contato não encontrado."},"meta":{"requestId":"req_V1StGXR8Z5jdHi6B"}}}}}}}}},"delete":{"operationId":"excluir-contato","summary":"Excluir cliente","description":"Manda o cliente para a Lixeira do Reton (dá para restaurar no painel por 90 dias).","tags":["Contatos"],"parameters":[{"name":"id","in":"path","required":true,"description":"O id do contato (con_…).","schema":{"type":"string","description":"O id do contato (con_…).","example":"con_LC4dQtpwbrLudiRS"}}],"responses":{"200":{"description":"Na Lixeira","content":{"application/json":{"examples":{"exemplo1":{"summary":"Na Lixeira","value":{"success":true,"data":{"id":"con_LC4dQtpwbrLudiRS","deletado":true,"deletadoEm":"2026-09-30T15:02:11.482Z"},"meta":{"requestId":"req_V1StGXR8Z5jdHi6B"}}}}}}},"400":{"description":"VALIDATION_ERROR: O id não tem o formato con_…."},"401":{"description":"UNAUTHORIZED: chave de API ausente, inválida ou revogada."},"403":{"description":"FORBIDDEN: a conta não está num plano com API (Pro)."},"404":{"description":"NOT_FOUND: Não existe, ou já está na Lixeira."}}}},"/interacoes":{"post":{"operationId":"registrar-venda","summary":"Registrar venda","description":"Grava uma venda para um cliente e devolve os pontos/cashback que ela gerou.","tags":["Vendas"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["valor"],"properties":{"celular":{"type":"string","description":"Celular do cliente, com DDD. Com ou sem máscara, com ou sem o 55.","maxLength":20},"documento":{"type":"string","description":"CPF ou CNPJ do cliente, com ou sem pontuação.","maxLength":20},"idExterno":{"type":"string","description":"O código do cliente no seu sistema (o mesmo enviado no cadastro).","maxLength":100},"contatoId":{"type":"string","description":"Ou o id do cliente no Reton (con_…). Pelo menos um destes quatro é obrigatório."},"valor":{"type":"number","description":"Valor da venda em reais, com ponto decimal: 150.90.","minimum":0.01},"codigoItem":{"type":"string","description":"Número da venda (ou do item) no seu sistema. Único na sua conta — é o que torna o reenvio seguro.","maxLength":100},"codigoTransacao":{"type":"string","description":"Número da venda quando você manda item por item. Permite estornar a venda inteira de uma vez.","maxLength":100},"dataHora":{"type":"string","description":"Quando a venda aconteceu, com fuso (2026-09-30T14:30:00-03:00 ou …Z). Padrão: agora.","format":"date-time"},"tags":{"type":"array","items":{"type":"string"},"description":"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."},"categoria":{"type":"string","description":"Uma categoria só, em texto. Prefira tags.","maxLength":100},"observacao":{"type":"string","description":"Descrição livre da venda (ex.: o que foi comprado).","maxLength":1000},"cashbackUsar":{"type":"number","description":"Quanto do saldo de cashback o cliente quer usar nesta compra, em reais. Se o saldo não cobrir, a venda é recusada (nada é gravado).","minimum":0},"cupom":{"type":"string","description":"Código de cupom de desconto do Reton. Não combina com cashbackUsar na mesma venda.","maxLength":50},"operadorId":{"type":"string","description":"O vendedor (op_…), se você quer atribuir a venda a ele. Sem isso, a venda fica com o operador \"API\"."}}},"examples":{"principal":{"summary":"Exemplo","value":{"celular":"(11) 98765-4321","valor":150.9,"codigoItem":"PDV1-000123-1","dataHora":"2026-09-30T14:30:00-03:00","observacao":"Ração 15kg"}},"variacao1":{"summary":"Ou pelo CPF","value":{"documento":"529.982.247-25","valor":150.9,"codigoItem":"PDV1-000123-1","dataHora":"2026-09-30T14:30:00-03:00"}}}}}},"responses":{"200":{"description":"Reenvio (já tinha entrado)","content":{"application/json":{"examples":{"exemplo1":{"summary":"Reenvio (já tinha entrado)","value":{"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"}}}}}}},"201":{"description":"Venda registrada","content":{"application/json":{"examples":{"exemplo1":{"summary":"Venda registrada","value":{"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"}}}}}}},"400":{"description":"VALIDATION_ERROR: Campo 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."},"401":{"description":"UNAUTHORIZED: chave de API ausente, inválida ou revogada."},"403":{"description":"FORBIDDEN: a conta não está num plano com API (Pro)."},"404":{"description":"Cliente não encontrado","content":{"application/json":{"examples":{"exemplo1":{"summary":"Cliente não encontrado","value":{"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"}}}}}}},"409":{"description":"Venda idêntica sem codigoItem","content":{"application/json":{"examples":{"exemplo1":{"summary":"Venda idêntica sem codigoItem","value":{"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"}}}}}}}}}},"/interacoes/estorno":{"post":{"operationId":"estornar-venda","summary":"Estornar (cancelar) uma venda","description":"Desfaz uma venda que não valeu: tira do faturamento e retira os pontos, o cashback ou o carimbo que ela deu.","tags":["Vendas"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"codigoItem":{"type":"string","description":"Código da venda/item enviado no registro.","maxLength":100},"codigoTransacao":{"type":"string","description":"Número da venda: estorna todos os itens dela. Não vale com escopo: \"recompensa\".","maxLength":100},"interacaoId":{"type":"string","description":"O id da venda no Reton (int_…).","maxLength":60},"escopo":{"type":"string","description":"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.","enum":["venda","recompensa"],"default":"venda"},"motivo":{"type":"string","description":"Por que foi estornada (fica no histórico do cliente).","maxLength":500}}},"example":{"codigoItem":"PDV1-000123-1","motivo":"Cliente devolveu o produto"}}}},"responses":{"200":{"description":"Venda cancelada","content":{"application/json":{"examples":{"exemplo1":{"summary":"Venda cancelada","value":{"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"}}}}}}},"400":{"description":"VALIDATION_ERROR: Nenhum dos três identificadores, ou escopo: \"recompensa\" com codigoTransacao."},"401":{"description":"UNAUTHORIZED: chave de API ausente, inválida ou revogada."},"403":{"description":"FORBIDDEN: a conta não está num plano com API (Pro)."},"404":{"description":"INTERACAO_NAO_ENCONTRADA: Nenhuma venda com esse código ou id na sua conta."},"409":{"description":"Cliente já usou os pontos","content":{"application/json":{"examples":{"exemplo1":{"summary":"Cliente já usou os pontos","value":{"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"}}}}}}}}}},"/fidelidade/saldo":{"get":{"operationId":"consultar-saldo","summary":"Consultar saldo","description":"Quanto o cliente tem hoje — já descontado o que venceu — e quanto vence em breve. Pelo celular ou CPF.","tags":["Fidelidade"],"parameters":[{"name":"celular","in":"query","required":false,"description":"Celular do cliente, com DDD. Com ou sem máscara.","schema":{"type":"string","description":"Celular do cliente, com DDD. Com ou sem máscara.","example":"11987654321"}},{"name":"documento","in":"query","required":false,"description":"CPF ou CNPJ, com ou sem pontuação.","schema":{"type":"string","description":"CPF ou CNPJ, com ou sem pontuação.","example":"52998224725"}},{"name":"idExterno","in":"query","required":false,"description":"O código do cliente no seu sistema.","schema":{"type":"string","description":"O código do cliente no seu sistema.","example":"CLI-1042"}},{"name":"diasExpiracao","in":"query","required":false,"description":"Janela de \"vence em breve\", em dias: quanto do saldo vence nos próximos N dias.","schema":{"type":"integer","description":"Janela de \"vence em breve\", em dias: quanto do saldo vence nos próximos N dias.","minimum":1,"maximum":365,"default":30}}],"responses":{"200":{"description":"Programa de pontos / Programa de cashback","content":{"application/json":{"examples":{"exemplo1":{"summary":"Programa de pontos","value":{"success":true,"data":{"contatoId":"con_LC4dQtpwbrLudiRS","modelo":"pontos","saldoReal":350,"pontosExpirando":50,"dataExpiracao":"2026-10-15T03:00:00.000Z"},"meta":{"requestId":"req_V1StGXR8Z5jdHi6B"}}},"exemplo2":{"summary":"Programa de cashback","value":{"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"}}}}}}},"400":{"description":"VALIDATION_ERROR: Nenhum parâmetro de cliente na URL, ou mais de um; ou diasExpiracao não é um inteiro de 1 a 365."},"401":{"description":"UNAUTHORIZED: chave de API ausente, inválida ou revogada."},"403":{"description":"FORBIDDEN: a conta não está num plano com API (Pro)."},"404":{"description":"Cliente não encontrado","content":{"application/json":{"examples":{"exemplo1":{"summary":"Cliente não encontrado","value":{"success":false,"error":{"code":"NOT_FOUND","message":"Cliente não encontrado."},"meta":{"requestId":"req_V1StGXR8Z5jdHi6B"}}}}}}}}}},"/fidelidade/saldo/{contatoId}":{"get":{"operationId":"consultar-saldo-por-id","summary":"Consultar saldo pelo id","description":"O mesmo saldo, para quem já guardou o id do cliente no Reton.","tags":["Fidelidade"],"parameters":[{"name":"contatoId","in":"path","required":true,"description":"O id do cliente (con_…).","schema":{"type":"string","description":"O id do cliente (con_…).","example":"con_LC4dQtpwbrLudiRS"}},{"name":"diasExpiracao","in":"query","required":false,"description":"Janela de \"vence em breve\", em dias.","schema":{"type":"integer","description":"Janela de \"vence em breve\", em dias.","minimum":1,"maximum":365,"default":30}}],"responses":{"200":{"description":"Programa de pontos","content":{"application/json":{"examples":{"exemplo1":{"summary":"Programa de pontos","value":{"success":true,"data":{"contatoId":"con_LC4dQtpwbrLudiRS","modelo":"pontos","saldoReal":350,"pontosExpirando":50,"dataExpiracao":"2026-10-15T03:00:00.000Z"},"meta":{"requestId":"req_V1StGXR8Z5jdHi6B"}}}}}}},"400":{"description":"VALIDATION_ERROR: O id não tem o formato con_…, ou diasExpiracao inválido."},"401":{"description":"UNAUTHORIZED: chave de API ausente, inválida ou revogada."},"403":{"description":"FORBIDDEN: a conta não está num plano com API (Pro)."},"404":{"description":"NOT_FOUND: O cliente não existe na sua conta (ou está na Lixeira)."}}}},"/fidelidade/resgatar":{"post":{"operationId":"resgatar-recompensa","summary":"Resgatar recompensa","description":"Troca pontos do cliente por um prêmio do seu catálogo e gera o voucher.","tags":["Fidelidade"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contatoId","recompensaId"],"properties":{"contatoId":{"type":"string","description":"O id do cliente (con_…)."},"recompensaId":{"type":"string","description":"O id do prêmio (rec_…)."},"quantidade":{"type":"integer","description":"Quantas unidades do prêmio. Gera um voucher para cada.","minimum":1,"maximum":50,"default":1},"canalResgate":{"type":"string","description":"operador = entregue na hora; portal/app = fica pendente até a retirada.","enum":["operador","portal","app"],"default":"portal"},"varianteSelecionada":{"type":"object","description":"Para prêmios com variação: { \"tamanho\": \"M\" }. As opções são as cadastradas no prêmio."},"observacao":{"type":"string","description":"Anotação livre.","maxLength":1000},"operadorId":{"type":"string","description":"Quem fez o resgate (op_…). Sem isso, fica com o operador \"API\"."},"unidadeCodigo":{"type":"string","description":"Código da loja onde o resgate aconteceu.","maxLength":50},"unidadeId":{"type":"string","description":"Ou o id da loja (uni_…)."}}},"example":{"contatoId":"con_LC4dQtpwbrLudiRS","recompensaId":"rec_vpyTEeCYIYURK01b","canalResgate":"operador"}}}},"responses":{"201":{"description":"Resgatado","content":{"application/json":{"examples":{"exemplo1":{"summary":"Resgatado","value":{"success":true,"data":{"resgateIds":["res_WhnxINUFrRdQKFXS"],"voucherCodes":["RES-W4S6TY"],"pontosGastos":100,"saldoApos":250},"meta":{"requestId":"req_V1StGXR8Z5jdHi6B"}}}}}}},"400":{"description":"Sem pontos suficientes","content":{"application/json":{"examples":{"exemplo1":{"summary":"Sem pontos suficientes","value":{"success":false,"error":{"code":"VALIDATION_ERROR","message":"Saldo insuficiente. Tem 80 pontos, precisa de 100"},"meta":{"requestId":"req_V1StGXR8Z5jdHi6B"}}}}}}},"401":{"description":"UNAUTHORIZED: chave de API ausente, inválida ou revogada."},"403":{"description":"FORBIDDEN: a conta não está num plano com API (Pro)."}}}},"/fidelidade/resgates":{"get":{"operationId":"listar-resgates","summary":"Listar resgates","description":"Os resgates da sua conta, do mais novo para o mais antigo, com filtros e paginação.","tags":["Fidelidade"],"parameters":[{"name":"status","in":"query","required":false,"description":"Só os resgates nesse estado.","schema":{"type":"string","description":"Só os resgates nesse estado.","enum":["pendente","entregue","cancelado"]}},{"name":"busca","in":"query","required":false,"description":"Procura no nome ou celular do cliente, no nome do prêmio e no voucher.","schema":{"type":"string","description":"Procura no nome ou celular do cliente, no nome do prêmio e no voucher."}},{"name":"operadorId","in":"query","required":false,"description":"Só os feitos por esse operador (op_…).","schema":{"type":"string","description":"Só os feitos por esse operador (op_…)."}},{"name":"limit","in":"query","required":false,"description":"Itens por página (máximo 100).","schema":{"type":"integer","description":"Itens por página (máximo 100).","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","required":false,"description":"Quantos itens pular.","schema":{"type":"integer","description":"Quantos itens pular.","minimum":0,"default":0}}],"responses":{"200":{"description":"Página de resgates","content":{"application/json":{"examples":{"exemplo1":{"summary":"Página de resgates","value":{"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"}}}}}}},"401":{"description":"UNAUTHORIZED: chave de API ausente, inválida ou revogada."},"403":{"description":"FORBIDDEN: a conta não está num plano com API (Pro)."}}}},"/fidelidade/resgates/{id}":{"get":{"operationId":"consultar-resgate","summary":"Consultar resgate","description":"Um resgate pelo id (res_…) ou pelo código do voucher (RES-…).","tags":["Fidelidade"],"parameters":[{"name":"id","in":"path","required":true,"description":"O id (res_…) ou o voucher (RES-W4S6TY).","schema":{"type":"string","description":"O id (res_…) ou o voucher (RES-W4S6TY).","example":"RES-W4S6TY"}}],"responses":{"200":{"description":"Resgate","content":{"application/json":{"examples":{"exemplo1":{"summary":"Resgate","value":{"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"}}}}}}},"401":{"description":"UNAUTHORIZED: chave de API ausente, inválida ou revogada."},"403":{"description":"FORBIDDEN: a conta não está num plano com API (Pro)."},"404":{"description":"Não encontrado","content":{"application/json":{"examples":{"exemplo1":{"summary":"Não encontrado","value":{"success":false,"error":{"code":"NOT_FOUND","message":"Resgate não encontrado."},"meta":{"requestId":"req_V1StGXR8Z5jdHi6B"}}}}}}}}},"patch":{"operationId":"cancelar-resgate","summary":"Cancelar resgate","description":"Cancela um resgate e devolve os pontos ao cliente.","tags":["Fidelidade"],"parameters":[{"name":"id","in":"path","required":true,"description":"O id do resgate (res_…).","schema":{"type":"string","description":"O id do resgate (res_…).","example":"res_WhnxINUFrRdQKFXS"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["motivoCancelamento"],"properties":{"motivoCancelamento":{"type":"string","description":"Por que foi cancelado (fica no histórico).","minLength":1,"maxLength":500}}},"example":{"motivoCancelamento":"Cliente desistiu do prêmio"}}}},"responses":{"200":{"description":"Cancelado","content":{"application/json":{"examples":{"exemplo1":{"summary":"Cancelado","value":{"success":true,"data":{"cancelado":true,"resgateId":"res_WhnxINUFrRdQKFXS"},"meta":{"requestId":"req_V1StGXR8Z5jdHi6B"}}}}}}},"400":{"description":"VALIDATION_ERROR: Sem motivo; resgate não encontrado; resgate já cancelado. A message diz qual."},"401":{"description":"UNAUTHORIZED: chave de API ausente, inválida ou revogada."},"403":{"description":"FORBIDDEN: a conta não está num plano com API (Pro)."}}}},"/unidades":{"get":{"operationId":"listar-lojas","summary":"Listar lojas","description":"Todas as lojas ativas da conta.","tags":["Lojas"],"parameters":[{"name":"incluirInativas","in":"query","required":false,"description":"true para trazer também as desativadas.","schema":{"type":"boolean","description":"true para trazer também as desativadas.","default":false}}],"responses":{"200":{"description":"Lojas","content":{"application/json":{"examples":{"exemplo1":{"summary":"Lojas","value":{"success":true,"data":{"total":1,"unidades":[{"id":"uni_N98eudAvtndlbaM1","nome":"Loja Centro","codigo":"LJ01","endereco":"Rua das Flores, 120 — Centro","telefone":"1133334444","ativo":true,"principal":false,"criadoEm":"2026-09-30T14:51:44.508Z","atualizadoEm":"2026-09-30T14:51:44.782Z"}]},"meta":{"requestId":"req_V1StGXR8Z5jdHi6B"}}}}}}},"401":{"description":"UNAUTHORIZED: chave de API ausente, inválida ou revogada."},"403":{"description":"FORBIDDEN: a conta não está num plano com API (Pro)."}}},"post":{"operationId":"criar-loja","summary":"Cadastrar loja","description":"Cria uma loja nova.","tags":["Lojas"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nome"],"properties":{"nome":{"type":"string","description":"Nome da loja. Não pode repetir.","minLength":2,"maxLength":200},"codigo":{"type":"string","description":"O código da loja no seu sistema (ex.: LJ01).","maxLength":50},"endereco":{"type":"string","description":"Endereço.","maxLength":500},"telefone":{"type":"string","description":"Telefone.","maxLength":20},"principal":{"type":"boolean","description":"true para ela virar a loja principal da conta."}}},"example":{"nome":"Loja Centro","codigo":"LJ01","endereco":"Rua das Flores, 120 — Centro","telefone":"1133334444"}}}},"responses":{"201":{"description":"Criada","content":{"application/json":{"examples":{"exemplo1":{"summary":"Criada","value":{"success":true,"data":{"id":"uni_N98eudAvtndlbaM1","nome":"Loja Centro","codigo":"LJ01","endereco":"Rua das Flores, 120 — Centro","telefone":"1133334444","ativo":true,"principal":false,"criadoEm":"2026-09-30T14:51:44.508Z","atualizadoEm":"2026-09-30T14:51:44.782Z"},"meta":{"requestId":"req_V1StGXR8Z5jdHi6B"}}}}}}},"401":{"description":"UNAUTHORIZED: chave de API ausente, inválida ou revogada."},"403":{"description":"FORBIDDEN: a conta não está num plano com API (Pro)."},"409":{"description":"CONFLICT: Já existe uma loja com esse nome."},"422":{"description":"VALIDATION_ERROR: O seu plano não permite mais lojas."}}}},"/unidades/{id}":{"get":{"operationId":"consultar-loja","summary":"Consultar loja","description":"Uma loja pelo id.","tags":["Lojas"],"parameters":[{"name":"id","in":"path","required":true,"description":"O id da loja (uni_…).","schema":{"type":"string","description":"O id da loja (uni_…).","example":"uni_N98eudAvtndlbaM1"}}],"responses":{"200":{"description":"Loja","content":{"application/json":{"examples":{"exemplo1":{"summary":"Loja","value":{"success":true,"data":{"id":"uni_N98eudAvtndlbaM1","nome":"Loja Centro","codigo":"LJ01","endereco":"Rua das Flores, 120 — Centro","telefone":"1133334444","ativo":true,"principal":false,"criadoEm":"2026-09-30T14:51:44.508Z","atualizadoEm":"2026-09-30T14:51:44.782Z"},"meta":{"requestId":"req_V1StGXR8Z5jdHi6B"}}}}}}},"401":{"description":"UNAUTHORIZED: chave de API ausente, inválida ou revogada."},"403":{"description":"FORBIDDEN: a conta não está num plano com API (Pro)."},"404":{"description":"Não encontrada","content":{"application/json":{"examples":{"exemplo1":{"summary":"Não encontrada","value":{"success":false,"error":{"code":"NOT_FOUND","message":"Unidade não encontrada."},"meta":{"requestId":"req_V1StGXR8Z5jdHi6B"}}}}}}}}},"patch":{"operationId":"alterar-loja","summary":"Alterar loja","description":"Muda só os campos que você mandar.","tags":["Lojas"],"parameters":[{"name":"id","in":"path","required":true,"description":"O id da loja (uni_…).","schema":{"type":"string","description":"O id da loja (uni_…).","example":"uni_N98eudAvtndlbaM1"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nome":{"type":"string","description":"Novo nome.","minLength":2,"maxLength":200},"codigo":{"type":"string","description":"Novo código (ou null).","maxLength":50},"endereco":{"type":"string","description":"Novo endereço (ou null).","maxLength":500},"telefone":{"type":"string","description":"Novo telefone (ou null).","maxLength":20}}},"example":{"telefone":"1133334444"}}}},"responses":{"200":{"description":"Alterada","content":{"application/json":{"examples":{"exemplo1":{"summary":"Alterada","value":{"success":true,"data":{"id":"uni_N98eudAvtndlbaM1","nome":"Loja Centro","codigo":"LJ01","endereco":"Rua das Flores, 120 — Centro","telefone":"1133334444","ativo":true,"principal":false,"criadoEm":"2026-09-30T14:51:44.508Z","atualizadoEm":"2026-09-30T14:51:44.782Z"},"meta":{"requestId":"req_V1StGXR8Z5jdHi6B"}}}}}}},"401":{"description":"UNAUTHORIZED: chave de API ausente, inválida ou revogada."},"403":{"description":"FORBIDDEN: a conta não está num plano com API (Pro)."},"404":{"description":"NOT_FOUND: Loja não encontrada."},"409":{"description":"CONFLICT: Já existe outra loja com esse nome."}}},"delete":{"operationId":"desativar-loja","summary":"Desativar loja","description":"Desativa a loja (não apaga o histórico dela).","tags":["Lojas"],"parameters":[{"name":"id","in":"path","required":true,"description":"O id da loja (uni_…).","schema":{"type":"string","description":"O id da loja (uni_…).","example":"uni_N98eudAvtndlbaM1"}}],"responses":{"200":{"description":"Desativada","content":{"application/json":{"examples":{"exemplo1":{"summary":"Desativada","value":{"success":true,"data":{"ok":true,"message":"Unidade desativada."},"meta":{"requestId":"req_V1StGXR8Z5jdHi6B"}}}}}}},"401":{"description":"UNAUTHORIZED: chave de API ausente, inválida ou revogada."},"403":{"description":"FORBIDDEN: a conta não está num plano com API (Pro)."},"404":{"description":"NOT_FOUND: Loja não encontrada."},"422":{"description":"Única loja ativa","content":{"application/json":{"examples":{"exemplo1":{"summary":"Única loja ativa","value":{"success":false,"error":{"code":"VALIDATION_ERROR","message":"Não é possível desativar a única unidade ativa da empresa."},"meta":{"requestId":"req_V1StGXR8Z5jdHi6B"}}}}}}}}}}}}