Integre o seu sistema ao Recerto Localiza
Consulte e enriqueça CPFs e CNPJs direto do seu sistema: telefones (com indicação de WhatsApp), e-mails, endereços, situação cadastral, óbito, recuperação judicial e vínculos. É a mesma base usada no painel da Recerto, com cobrança por documento consultado no saldo pré-pago da sua conta.
| Ambiente | Endereço base | Painel | Chave |
|---|---|---|---|
| Sandbox (testes) | https://api.sandbox.recerto.com.br/v1 | sandbox.recerto.com.br | rct_test_ |
| Produção | https://api.recerto.com.br/v1 | app.recerto.com.br | rct_live_ |
| Referência completa (OpenAPI) | https://api.recerto.com.br/docs e /docs-json para gerar clientes | ||
Começo rápido
- Tenha uma conta e saldo. Cadastre a empresa em app.recerto.com.br e faça uma recarga (PIX ou boleto) em Carteira.
- Gere a chave de API. No painel, em Conta > Integrações (API), clique em Nova chave. Só o dono ou o gerente da conta pode gerar. Se preferir, peça à equipe Recerto, que gera em nome da sua empresa. A chave começa com
rct_live_e aparece uma única vez. - Teste a conexão (não cobra nada):
export RECERTO=https://api.recerto.com.br/v1 export RECERTO_KEY=rct_live_xxx # guarde em um cofre, nunca no código curl -s $RECERTO/api-keys/current -H "Authorization: Bearer $RECERTO_KEY"
{ "id": "2a514616-a20d-49dd-b4fc-75f8db2bf0ea", "name": "ERP do cartório", "prefix": "e4faf167db4f", "scopes": ["localiza:read", "localiza:write", "wallet:read", "webhooks:manage"], "expiresAt": "2027-02-17T15:27:34.734Z", "status": "ativa", "organization": { "id": "80bd03af-...", "name": "Tabelionato de Protestos" } } - Faça a primeira consulta (debita o preço de um documento):
curl -s -X POST $RECERTO/localiza/lookup \ -H "Authorization: Bearer $RECERTO_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: consulta-96001338914-001" \ -d '{"documento":"960.013.389-14"}'
Preço e cobrança
- A cobrança sai do saldo pré-pago da conta, na hora da consulta avulsa ou na confirmação do lote. Sem saldo, a API responde
SALDO_INSUFICIENTEe nada é consultado. - Em lotes, documentos inválidos e repetidos não são cobrados. A prévia do lote mostra o valor antes de você confirmar.
- O preço vigente da sua conta está sempre em
GET /localiza/price(campoprecoCentavos). Use esse valor no seu sistema em vez de fixar no código. - Cada débito aparece no extrato da conta (
GET /wallet/transactions) e no histórico de chamadas da chave, com o valor e a quantidade de documentos cobrados.
Autenticação
Envie a chave em todas as requisições, por um dos dois cabeçalhos (o primeiro é o recomendado):
Authorization: Bearer rct_live_e4faf167db4f_2e84... X-Api-Key: rct_live_e4faf167db4f_2e84...
Formato da chave: rct_live_<prefixo>_<segredo>. O prefixo (12 caracteres) identifica a chave no painel e nos registros; o segredo nunca é guardado pela Recerto, só o seu hash (SHA-256). Por isso, uma chave perdida não pode ser recuperada: gere outra.
Permissões (escopos)
| Escopo | O que libera | Padrão |
|---|---|---|
localiza:read | Preço, lotes, itens, fichas e exportação dos resultados. | sim |
localiza:write | Consulta avulsa e criação, confirmação e cancelamento de lotes. Gera débito. | sim |
wallet:read | Saldo, extrato e recargas. | sim |
webhooks:manage | Cadastrar, listar e remover webhooks e ver as entregas. | sim |
wallet:write | Gerar cobranças de recarga (PIX ou boleto). O pagamento continua fora da API. | opcional |
Um sistema que só lê resultados (BI, por exemplo) deve receber apenas localiza:read. A chave nunca recebe mais permissões do que o usuário que a gerou.
Gerar, rotacionar e revogar chaves
Tudo é feito no painel, em Conta > Integrações (API), por usuários com o papel Dono ou Gerente. Uma chave de API não cria nem revoga outras chaves.
| Ação | Como funciona |
|---|---|
| Gerar | Nome do sistema, descrição, permissões, vencimento (opcional, até 2 anos) e lista de IPs autorizados (opcional). O painel registra quem gerou, quando e de qual IP. |
| Rotacionar | Gera uma chave nova com a mesma configuração. A antiga para na hora ou depois de um período de transição de até 7 dias, para você trocar sem parar o sistema. |
| Revogar | Vale na hora: a próxima chamada com a chave recebe 401 CHAVE_REVOGADA. O motivo e quem revogou ficam registrados. |
| Acompanhar | Para cada chave: último uso (data, IP e sistema), chamadas, erros e valor cobrado nos últimos 30 dias, e o histórico de cada chamada. |
Boas práticas de segurança
- Só no servidor. A chave nunca deve ir para o navegador, aplicativo de celular, planilha ou repositório de código. Guarde em variável de ambiente ou cofre de segredos (AWS Secrets Manager, Azure Key Vault, Vault).
- Uma chave por sistema. ERP, rotina noturna e BI com chaves separadas: se uma vazar, você revoga só ela e sabe exatamente de onde veio cada chamada.
- Mínimo de permissões e, quando o seu servidor tiver IP fixo, lista de IPs (aceita IP exato ou rede CIDR, como
200.98.10.0/24). - Vencimento e rotação. Prefira chaves com vencimento e rotacione pelo menos uma vez por ano, ou na saída de alguém que tinha acesso a ela.
- Suspeita de vazamento: revogue no painel na hora e gere outra. Confira no histórico de chamadas os IPs e horários que não reconhecer.
- HTTPS sempre. Chame sempre
https://. Uma chave enviada por HTTP sem criptografia deve ser considerada exposta: revogue e gere outra.
Consulta avulsa
Consulta um CPF ou CNPJ (com ou sem pontuação) e devolve a ficha na mesma resposta, em geral em poucos segundos.
curl -s -X POST https://api.recerto.com.br/v1/localiza/lookup \
-H "Authorization: Bearer $RECERTO_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: consulta-96001338914-001" \
-d '{"documento":"960.013.389-14"}'
const resposta = await fetch("https://api.recerto.com.br/v1/localiza/lookup", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.RECERTO_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "consulta-96001338914-001",
},
body: JSON.stringify({ documento: "960.013.389-14" }),
});
const corpo = await resposta.json();
if (!resposta.ok) throw new Error(`${corpo.code ?? resposta.status}: ${corpo.message} (${resposta.headers.get("x-request-id")})`);
console.log(corpo.ficha.telefones);
import os
import requests
r = requests.post(
"https://api.recerto.com.br/v1/localiza/lookup",
headers={
"Authorization": f"Bearer {os.environ['RECERTO_KEY']}",
"Idempotency-Key": "consulta-96001338914-001",
},
json={"documento": "960.013.389-14"},
timeout=60,
)
corpo = r.json()
if not r.ok:
raise RuntimeError(f"{corpo.get('code', r.status_code)}: {corpo['message']} ({r.headers.get('X-Request-Id')})")
print(corpo["ficha"]["telefones"])
$ch = curl_init("https://api.recerto.com.br/v1/localiza/lookup");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("RECERTO_KEY"),
"Content-Type: application/json",
"Idempotency-Key: consulta-96001338914-001",
],
CURLOPT_POSTFIELDS => json_encode(["documento" => "960.013.389-14"]),
]);
$corpo = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status >= 400) throw new Exception(($corpo["code"] ?? $status) . ": " . $corpo["message"]);
print_r($corpo["ficha"]["telefones"]);
Resposta 201 (dados fictícios do ambiente de testes):
{
"item": {
"id": "59e98c34-73d8-4437-ba81-c847b28f15bb",
"batchId": "b8dfb203-fa90-47dc-a7ee-63453b2ef466",
"document": "96001338914",
"docType": "CPF",
"status": "FOUND",
"chargedCents": 350,
"processedAt": "2026-11-19T15:28:21.333Z"
},
"ficha": {
"documento": "96001338914",
"tipo": "CPF",
"nome": "FERNANDA ALMEIDA SILVA",
"situacao": "CPF ativo",
"recuperacaoJudicial": false,
"obito": false,
"nascimento": "08/04/1951",
"idade": 75,
"nomeMae": "Beatriz Pereira Silva",
"telefones": [{ "numero": "(48) 99979-3513", "tipo": "CELULAR", "operadora": "CLARO", "whatsapp": true }],
"emails": ["fernanda.almeida@exemplo.test"],
"enderecos": [{ "texto": "Rua da Figueira, 827 - Cristo Rei - Florianopolis/SC - CEP 98152-476", "cidade": "Florianopolis", "uf": "SC", "cep": "98152-476" }],
"renda": "R$ 4.531,02",
"atividade": "Encarregado da recepção",
"vinculos": []
}
}
item.status: FOUND (encontrado), NOT_FOUND (sem dados) ou ERROR (falha na consulta; o valor não é cobrado e volta para o saldo).
Consulta em lote
Para muitos documentos de uma vez (até 100 mil por lote). O lote é criado em prévia (grátis, mostra quantos são válidos e o valor), depois confirmado (debita o saldo) e processado em segundo plano.
1. Criar o lote (prévia, sem custo)
curl -s -X POST $RECERTO/localiza/batches \
-H "Authorization: Bearer $RECERTO_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: lote-novembro-001" \
-d '{
"name": "Devedores novembro",
"documentos": [
{ "documento": "960.013.389-14", "nome": "Fernanda Almeida" },
{ "documento": "11.222.333/0001-81" },
{ "documento": "123" }
]
}'
{
"id": "4a38e6e4-5c4d-44df-a9b6-781757272571",
"name": "Devedores novembro",
"status": "PREVIEW",
"totalRows": 3, "validCount": 2, "invalidCount": 1, "duplicateCount": 0,
"unitPriceCents": 350,
"estimatedCents": 700
}
Também dá para enviar uma planilha (xlsx ou csv, até 10 MB) em POST /localiza/batches/preview, no campo file de um multipart/form-data.
2. Confirmar (debita o saldo)
Reserva validCount × preço do saldo e coloca o lote na fila. Confirmar de novo não cobra outra vez. Para desistir antes de confirmar: POST /localiza/batches/{id}/cancel.
3. Acompanhar e baixar os resultados
| Rota | Para quê |
|---|---|
GET/localiza/batches/{id} | Status (QUEUED, PROCESSING, DONE), progresso (0 a 100) e contagens. |
GET/localiza/batches/{id}/items | Itens com a ficha, paginados (?page=1&pageSize=100) e com filtros (status=FOUND, temTelefone=true, temEmail=true, temWhatsapp=true, obito=false, busca=...). |
GET/localiza/batches/{id}/export?formato=xlsx | Arquivo pronto (xlsx ou csv), modelo=simples|completo ou colunas escolhidas em colunas= (lista em /localiza/export-columns). |
GET/localiza/batches | Lista dos lotes da conta, paginada. |
localiza.batch.completed. Se consultar, use intervalo de 3 a 5 segundos.A ficha do documento
| Campo | Conteúdo |
|---|---|
nome, nomeFantasia | Nome (CPF) ou razão social e nome fantasia (CNPJ). |
situacao | Situação cadastral na Receita. |
obito, recuperacaoJudicial | Indicadores de óbito (CPF) e de recuperação judicial (CNPJ). |
telefones[] | numero, tipo (CELULAR ou FIXO), operadora e whatsapp (true quando o número tem WhatsApp). |
emails[] | E-mails encontrados. |
enderecos[] | texto completo, cidade, uf e cep. |
nascimento, idade, nomeMae, renda, atividade | Dados de pessoa física, quando disponíveis. |
vinculos[] | Sócios e empresas ligadas ao documento. |
Saldo
{ "saldoCentavos": 166800, "saldo": "R$ 1.668,00" }
Extrato: GET /wallet/transactions. Antes de um lote grande, compare estimatedCents da prévia com o saldo.
Webhooks
A Recerto avisa o seu sistema quando um lote termina (localiza.batch.completed) ou uma recarga é paga (payment.confirmed).
curl -s -X POST $RECERTO/webhooks \
-H "Authorization: Bearer $RECERTO_KEY" -H "Content-Type: application/json" \
-d '{"url":"https://erp.suaempresa.com.br/recerto/webhook","events":["localiza.batch.completed","payment.confirmed"]}'
A resposta traz o secret (whsec_...), que assina as entregas. Cada entrega é um POST JSON com os cabeçalhos:
Recerto-Event: localiza.batch.completed Recerto-Signature: t=1792549518,v1=88e8bac145df3bbc3cae198673bfb2996b9b809e1ed7c3c29ee2f69bdf07c69f
v1 é o HMAC-SHA256 (hexadecimal) de t + "." + corpo bruto, com o secret como chave. Verifique sempre, compare em tempo constante e rejeite t com mais de 5 minutos de diferença:
const crypto = require("crypto");
function assinaturaValida(corpoBruto, cabecalho, secret, toleranciaSeg = 300) {
const partes = Object.fromEntries((cabecalho || "").split(",").map((p) => p.split("=", 2)));
if (!partes.t || !partes.v1) return false;
const esperado = crypto.createHmac("sha256", secret).update(`${partes.t}.${corpoBruto}`).digest("hex");
const a = Buffer.from(esperado, "hex");
const b = Buffer.from(partes.v1, "hex");
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return false;
return Math.abs(Date.now() / 1000 - Number(partes.t)) <= toleranciaSeg;
}
Responda 2xx em até 10 segundos e processe depois. Sem resposta, a Recerto tenta de novo (cerca de 10 s, 20 s, 40 s e 80 s, até 5 tentativas). A mesma entrega pode chegar mais de uma vez: use o id do corpo para ignorar repetições.
Erros
Todo erro vem no mesmo formato, com message em português (pode ser mostrado ao usuário) e, quando há, um code estável para o seu sistema tratar:
{ "statusCode": 401, "code": "CHAVE_REVOGADA", "message": "Esta chave de API foi revogada. Gere uma nova no painel da Recerto.", "error": "Unauthorized" }
| HTTP | code | Quando |
|---|---|---|
| 400 | (validação) | Dados inválidos. message pode vir como lista. |
| 400 | SALDO_INSUFICIENTE | Saldo não cobre a consulta ou o lote. Traz saldoCentavos e necessarioCentavos. |
| 401 | CHAVE_INVALIDA | Chave inexistente, digitada errada ou ausente. |
| 401 | CHAVE_REVOGADA | A chave foi revogada no painel. |
| 401 | CHAVE_EXPIRADA | A chave passou do vencimento. |
| 401 | CHAVE_DE_OUTRO_AMBIENTE | Chave de sandbox (rct_test_) usada em produção, ou de produção (rct_live_) usada no sandbox. |
| 403 | ESCOPO_INSUFICIENTE | A chave não tem a permissão da rota. |
| 403 | IP_NAO_AUTORIZADO | A chamada veio de um IP fora da lista da chave. |
| 403 | API_SUSPENSA / CONTA_INATIVA | Acesso pela API suspenso ou conta inativa. Fale com a Recerto. |
| 404 | Recurso não existe ou não é da sua conta. | |
| 409 | Idempotency-Key reutilizada com outro corpo, ou a primeira ainda em andamento. | |
| 413 | Planilha acima de 10 MB. | |
| 429 | LIMITE_REQUISICOES | Limite de requisições. Espere o Retry-After (segundos). |
| 5xx | Erro do nosso lado. Tente de novo com espera e com a mesma Idempotency-Key. |
Toda resposta traz o cabeçalho X-Request-Id. Guarde-o nos seus logs e informe ao suporte quando abrir um chamado: com ele localizamos a chamada exata. Você também pode enviar o seu próprio X-Request-Id (8 a 100 caracteres) e ele será usado.
Reenvio seguro (Idempotency-Key)
Todo POST aceita o cabeçalho Idempotency-Key. Use sempre nas operações que cobram (consulta avulsa, criação e confirmação de lote): gere um valor único por operação (um UUID, ou consulta-<id do seu sistema>) e reutilize o mesmo valor ao reenviar depois de timeout ou queda de rede.
- Mesma chave e mesmo corpo: a API devolve a resposta original, com
Idempotent-Replayed: true, sem cobrar de novo. - Mesma chave com outro corpo:
409. - Se a primeira tentativa deu erro, a chave é liberada e o reenvio executa normalmente.
Limites
- 120 requisições por minuto por chave. As respostas trazem
X-RateLimit-Limit,X-RateLimit-RemainingeX-RateLimit-Reset. - Acima do limite:
429comRetry-After. Para volume alto, use lotes, que não têm esse limite por documento. - Lote: até 100 mil documentos. Planilha: até 10 MB.
Registro das chamadas
Toda chamada feita com chave de API é registrada: data e hora, chave, rota, resposta, tempo, IP de origem, sistema (User-Agent), valor cobrado e quantidade de documentos. Também ficam registradas as tentativas recusadas (chave inválida, revogada, vencida ou de IP não autorizado).
Os donos e gerentes da conta veem esse histórico no painel, em Conta > Integrações (API), junto do consumo por chave e por dia. O registro é guardado por cerca de 13 meses.
Sandbox (ambiente de testes)
O sandbox é uma cópia completa da API, com a mesma versão da produção, separada dela: outro endereço, outro painel, outras contas e outro banco de dados. As consultas devolvem dados fictícios e o saldo é de teste. Nada é cobrado e nenhum dado real passa por lá.
| Sandbox | Produção | |
|---|---|---|
| Endereço da API | https://api.sandbox.recerto.com.br/v1 | https://api.recerto.com.br/v1 |
| Painel (conta e chaves) | sandbox.recerto.com.br | app.recerto.com.br |
| Chave | rct_test_... | rct_live_... |
| Consultas | Fichas fictícias e determinísticas (o mesmo documento traz sempre a mesma ficha) | Base real |
| Saldo | De teste: você mesmo adiciona | Recarga por PIX ou boleto |
| Cobrança, erros, limites, webhooks e registro das chamadas | Iguais nos dois ambientes | |
401 CHAVE_DE_OUTRO_AMBIENTE. Assim uma chave de testes nunca consulta a base real por engano. E nunca use a chave de produção em testes.Como começar
- Crie uma conta em sandbox.recerto.com.br. É separada da conta de produção. Pode usar os mesmos dados da empresa.
- Em Conta > Integrações (API), gere uma chave. Ela começa com
rct_test_. - Adicione saldo de teste, em Carteira no painel do sandbox ou pela API:
curl -s -X POST https://api.sandbox.recerto.com.br/v1/sandbox/balance \ -H "Authorization: Bearer $RECERTO_KEY" \ -H "Content-Type: application/json" \ -d '{"amountCents": 50000}'Até R$ 1.000,00 por pedido e até R$ 10.000,00 de saldo. A rota só existe no sandbox: em produção ela responde404. - Integre usando os documentos de teste abaixo. Quando tudo funcionar, gere a chave
rct_live_no painel de produção (ou peça à equipe Recerto) e troque o endereço base.
Documentos de teste
Estes CPFs e CNPJs têm resultado fixo no sandbox, para você testar cada caso do seu sistema. Qualquer outro documento válido também funciona e traz uma ficha fictícia sorteada (cerca de 10% vêm como não encontrados).
| Documento | Tipo | Resultado |
|---|---|---|
111.444.777-35 | CPF | Encontrado, com celular com WhatsApp, fixo, e-mail e endereço |
222.333.444-05 | CPF | Encontrado, sem nenhum telefone (só endereço) |
333.444.555-08 | CPF | Encontrado, com óbito informado |
444.555.666-19 | CPF | Não encontrado na base |
11.222.333/0001-81 | CNPJ | Empresa ativa, com telefones, e-mail e sócios |
22.333.444/0001-81 | CNPJ | Empresa com situação BAIXADA |
33.444.555/0001-81 | CNPJ | Não encontrado na base |
Para testar SALDO_INSUFICIENTE, mande um lote maior do que o saldo de teste. A lista também está em GET /v1/sandbox.
Recarga e webhook de pagamento
No sandbox a recarga é criada no ambiente de testes do gateway de pagamento. Para receber o webhook payment.confirmed sem pagar nada, crie a recarga e simule o pagamento (chave com o escopo wallet:write):
curl -s -X POST https://api.sandbox.recerto.com.br/v1/wallet/recharges \
-H "Authorization: Bearer $RECERTO_KEY" -H "Content-Type: application/json" \
-d '{"amountCents": 10000, "method": "PIX"}'
curl -s -X POST https://api.sandbox.recerto.com.br/v1/wallet/recharges/<id>/simulate-payment \
-H "Authorization: Bearer $RECERTO_KEY"
Toda resposta traz o cabeçalho X-Recerto-Ambiente (sandbox ou producao). Ele ajuda o seu sistema a conferir que está falando com o ambiente certo.
Antes de ir para produção
- Endereço base e chave lidos de configuração (variável de ambiente ou cofre), nunca fixos no código.
- Tratamento dos códigos de erro, principalmente
SALDO_INSUFICIENTE,CHAVE_REVOGADAe429. Idempotency-Keyem toda operação que cobra.- Webhooks com a assinatura conferida e as repetições ignoradas pelo
id. - Lista de IPs na chave de produção, se o seu servidor tem IP fixo.
Suporte
Integração e chaves: contato@recerto.com.br. Informe o X-Request-Id da chamada e o prefixo da chave (nunca a chave inteira).