Documentação da API

Integre o sistema da sua empresa às consultas do Retomatech. As consultas debitam os créditos da sua conta (o saldo da empresa, se você é membro de uma equipe), igual ao Terminal de Consulta do site.

1. Entrar (token de acesso)

POST/api/externo/login

Envie o e-mail e a senha de uma conta do site. A resposta traz um token válido por 1 hora; envie-o em todas as chamadas no cabeçalho Authorization: Bearer <token>. Quando expirar (resposta 401), entre de novo.

curl -X POST https://retomatech.com.br/api/externo/login \
  -H "Content-Type: application/json" \
  -d '{"email": "integracao@suaempresa.com.br", "senha": "SUA_SENHA"}'

{"access_token": "eyJhbGciOi...", "token_type": "bearer", "expira_em_segundos": 3600,
 "conta": {"nome": "Sua Empresa", "tipo": "escritorio"}}

Conta com verificação em duas etapas não entra pela API (não há como digitar o código). Crie na sua equipe uma conta só para a integração, sem verificação em duas etapas, e guarde a senha em local seguro no seu servidor — nunca no navegador ou no aplicativo do cliente. 10 senhas erradas em 15 minutos bloqueiam novas tentativas por 15 minutos.

2. Produtos e saldo

GET/api/terminal/produtos

Lista os produtos do catálogo liberados para a conta (id, nome, módulos e custo em créditos), o saldo e os tipos de chave aceitos.

curl https://retomatech.com.br/api/terminal/produtos -H "Authorization: Bearer $TOKEN"

{"produtos": [{"id": 1, "nome": "RT", "descricao": "...", "categoria": "Combos",
               "modulos": [{"code": 187, "name": "Débitos e Restrições"}], "custo_creditos": 1}],
 "saldo": 120, "cobranca": true, "tipos_chave": ["placa", "chassi", "renavam", "motor", "cpf", "cnpj"]}

3. Consultar

POST/api/terminal/consultar

Campo	Descrição
`tipo_chave`	`placa`, `chassi`, `renavam`, `motor`, `cpf` ou `cnpj`
`chave`	O valor consultado (ex.: `ABC1D23`)
`produtos`	Lista de ids de produtos (até 10)
`chave_idempotencia`	Opcional, recomendado: um id único seu por pedido (até 80 letras, números, `-` ou `_`). Se a rede cair e você reenviar o mesmo pedido, recebe a mesma consulta sem novo débito.

curl -X POST https://retomatech.com.br/api/terminal/consultar \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"tipo_chave": "placa", "chave": "ABC1D23", "produtos": [1], "chave_idempotencia": "pedido-000123"}'

A resposta traz id da consulta, status (nada_consta, restricao_leve, sinistro, sem_registro ou erro), modelo, proprietario, debitos_total, resumo, o retorno de cada módulo em modulos e o débito em creditos (custo e saldo). Módulo que falhar não é cobrado.

4. Consulta já feita e PDF

GET/api/terminal/consultas — as últimas 100 consultas da conta.

GET/api/terminal/consultas/{id} — uma consulta com o retorno completo.

GET/api/terminal/consultas/{id}/pdf — o relatório em PDF (com o logo da sua empresa). Acrescente ?download=true para baixar como anexo.

5. Erros

Código	Quando
400	Chave inválida ou tipo de chave desconhecido
401	Sem token, token expirado ou usuário/senha inválidos
402	Saldo insuficiente ou limite mensal do membro atingido
403	Produto não liberado para a conta, ou conta não pode usar a API
404	Consulta não encontrada (ou de outra conta)
409	O mesmo pedido (mesma `chave_idempotencia`) ainda está em andamento
429	Muitas chamadas: até 30 consultas por minuto por conta

O corpo do erro é {"detail": "mensagem"}.

6. Exemplo em Python

import requests

BASE = "https://retomatech.com.br"
login = requests.post(f"{BASE}/api/externo/login",
                      json={"email": "integracao@suaempresa.com.br", "senha": "SUA_SENHA"}, timeout=30)
login.raise_for_status()
h = {"Authorization": f"Bearer {login.json()['access_token']}"}

produtos = requests.get(f"{BASE}/api/terminal/produtos", headers=h, timeout=30).json()["produtos"]
r = requests.post(f"{BASE}/api/terminal/consultar", headers=h, timeout=120, json={
    "tipo_chave": "placa", "chave": "ABC1D23", "produtos": [produtos[0]["id"]],
    "chave_idempotencia": "pedido-000123"})
r.raise_for_status()
consulta = r.json()
print(consulta["status"], consulta["resumo"])
pdf = requests.get(f"{BASE}/api/terminal/consultas/{consulta['id']}/pdf", headers=h, timeout=60)
open("consulta.pdf", "wb").write(pdf.content)

← Entrar no Retomatech