Você está no sandbox: chaves rct_test_, dados fictícios e saldo de teste. Nada aqui é cobrado. Os exemplos abaixo já apontam para este ambiente.
Recerto API v1

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.

REST + JSONHTTPS, respostas em JSON, valores em centavos e datas em ISO 8601 (UTC).
Chave por sistemaGerada no painel, com permissões, vencimento e lista de IPs. Revogação na hora.
Tudo registradoCada chamada fica no histórico da conta, com o valor cobrado e o X-Request-Id.
AmbienteEndereço basePainelChave
Sandbox (testes)https://api.sandbox.recerto.com.br/v1sandbox.recerto.com.brrct_test_
Produçãohttps://api.recerto.com.br/v1app.recerto.com.brrct_live_
Referência completa (OpenAPI)https://api.recerto.com.br/docs e /docs-json para gerar clientes

Começo rápido

Comece pelo sandbox. Desenvolva e teste a integração inteira no sandbox, sem custo e sem dados reais. Quando estiver pronta, troque só o endereço base e a chave para os de produção. O código é o mesmo.
  1. Tenha uma conta e saldo. Cadastre a empresa em app.recerto.com.br e faça uma recarga (PIX ou boleto) em Carteira.
  2. 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.
  3. 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" }
    }
  4. 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

R$ 3,50por documento consultado
  • 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_INSUFICIENTE e 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 (campo precoCentavos). 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)

EscopoO que liberaPadrão
localiza:readPreço, lotes, itens, fichas e exportação dos resultados.sim
localiza:writeConsulta avulsa e criação, confirmação e cancelamento de lotes. Gera débito.sim
wallet:readSaldo, extrato e recargas.sim
webhooks:manageCadastrar, listar e remover webhooks e ver as entregas.sim
wallet:writeGerar 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çãoComo funciona
GerarNome 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.
RotacionarGera 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.
RevogarVale na hora: a próxima chamada com a chave recebe 401 CHAVE_REVOGADA. O motivo e quem revogou ficam registrados.
AcompanharPara cada chave: último uso (data, IP e sistema), chamadas, erros e valor cobrado nos últimos 30 dias, e o histórico de cada chamada.
A equipe Recerto também pode gerar uma chave para a sua empresa (por exemplo, na implantação). Nesse caso o painel registra quem pediu a chave e quem a gerou, e a chave é entregue por um canal seguro.

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

POST/v1/localiza/lookupescopo localiza:write · cobra 1 documento

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"}'

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)

POST/v1/localiza/batchesescopo localiza:write
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)

POST/v1/localiza/batches/{id}/confirmescopo localiza:write

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

RotaPara quê
GET/localiza/batches/{id}Status (QUEUED, PROCESSING, DONE), progresso (0 a 100) e contagens.
GET/localiza/batches/{id}/itemsItens 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=xlsxArquivo pronto (xlsx ou csv), modelo=simples|completo ou colunas escolhidas em colunas= (lista em /localiza/export-columns).
GET/localiza/batchesLista dos lotes da conta, paginada.
Em vez de consultar o status em laço, cadastre um webhook com o evento localiza.batch.completed. Se consultar, use intervalo de 3 a 5 segundos.

A ficha do documento

CampoConteúdo
nome, nomeFantasiaNome (CPF) ou razão social e nome fantasia (CNPJ).
situacaoSituação cadastral na Receita.
obito, recuperacaoJudicialIndicadores 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, atividadeDados de pessoa física, quando disponíveis.
vinculos[]Sócios e empresas ligadas ao documento.
LGPD. Os dados devem ser usados só para a finalidade informada no contrato (por exemplo, contato com devedores para regularização de títulos). Não repasse a terceiros nem guarde além do necessário. Toda consulta fica registrada com a chave, o horário e o IP de origem.

Saldo

GET/v1/walletescopo wallet:read
{ "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).

POST/v1/webhooksescopo webhooks:manage
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" }
HTTPcodeQuando
400(validação)Dados inválidos. message pode vir como lista.
400SALDO_INSUFICIENTESaldo não cobre a consulta ou o lote. Traz saldoCentavos e necessarioCentavos.
401CHAVE_INVALIDAChave inexistente, digitada errada ou ausente.
401CHAVE_REVOGADAA chave foi revogada no painel.
401CHAVE_EXPIRADAA chave passou do vencimento.
401CHAVE_DE_OUTRO_AMBIENTEChave de sandbox (rct_test_) usada em produção, ou de produção (rct_live_) usada no sandbox.
403ESCOPO_INSUFICIENTEA chave não tem a permissão da rota.
403IP_NAO_AUTORIZADOA chamada veio de um IP fora da lista da chave.
403API_SUSPENSA / CONTA_INATIVAAcesso pela API suspenso ou conta inativa. Fale com a Recerto.
404Recurso não existe ou não é da sua conta.
409Idempotency-Key reutilizada com outro corpo, ou a primeira ainda em andamento.
413Planilha acima de 10 MB.
429LIMITE_REQUISICOESLimite de requisições. Espere o Retry-After (segundos).
5xxErro 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-Remaining e X-RateLimit-Reset.
  • Acima do limite: 429 com Retry-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á.

SandboxProdução
Endereço da APIhttps://api.sandbox.recerto.com.br/v1https://api.recerto.com.br/v1
Painel (conta e chaves)sandbox.recerto.com.brapp.recerto.com.br
Chaverct_test_...rct_live_...
ConsultasFichas fictícias e determinísticas (o mesmo documento traz sempre a mesma ficha)Base real
SaldoDe teste: você mesmo adicionaRecarga por PIX ou boleto
Cobrança, erros, limites, webhooks e registro das chamadasIguais nos dois ambientes
Cada ambiente recusa a chave do outro com 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

  1. Crie uma conta em sandbox.recerto.com.br. É separada da conta de produção. Pode usar os mesmos dados da empresa.
  2. Em Conta > Integrações (API), gere uma chave. Ela começa com rct_test_.
  3. 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 responde 404.
  4. 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).

DocumentoTipoResultado
111.444.777-35CPFEncontrado, com celular com WhatsApp, fixo, e-mail e endereço
222.333.444-05CPFEncontrado, sem nenhum telefone (só endereço)
333.444.555-08CPFEncontrado, com óbito informado
444.555.666-19CPFNão encontrado na base
11.222.333/0001-81CNPJEmpresa ativa, com telefones, e-mail e sócios
22.333.444/0001-81CNPJEmpresa com situação BAIXADA
33.444.555/0001-81CNPJNã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_REVOGADA e 429.
  • Idempotency-Key em 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).