Busca CEP - APIs para pesquisa automatizada

Modificado em Sex, 17 Jul na (o) 11:26 AM

ÍNDICE

Visão geral
Gerar uma chave de aplicação
Deletar uma chave
Como utilizar a chave nas chamadas à API
Consumo da API
Especificação das rotas
Webhook

Visão geral

O sistema BuscaCEP permite que organizações e contas pessoais integrem sistemas externos, para a realização de consultas automáticas, de duas formas:

Chave de aplicação (API Key) - autentica e autoriza chamadas de sistemas externos à API do BuscaCEP, atuando em nome da organização ou da conta pessoal.
Webhook - permite que o BuscaCEP notifique um sistema externo, via HTTP POST, quando ocorrerem eventos, como a conclusão de execução de consulta automática.

Ambas são configuradas pelos administradores na página de gerenciamento da organização.

Gerar uma chave de aplicação

Para utilizar as APIs, gere uma chave de aplicação.

1. Acesse a página de gerenciamento em https://hml.buscacep.org.br/private/management → Chaves de aplicação → Adicionar.

2. Informe:

Descrição - obrigatória, até 100 caracteres.
Validade - em 1-2 ano(s), a partir da data de criação.

3. Clique em 'Criar'.

4. Copie a chave que é exibida uma única vez na tela.

⚠ A chave não pode ser visualizada depois. Se for perdida, é necessário deletar e gerar uma nova.

Deletar uma chave

Caso deseje excluir uma chave de integração, clique em Deletar na lista de chaves. A exclusão é imediata, e todas as chamadas realizadas com essa chave serão rejeitadas a partir desse momento.

Como utilizar a chave nas chamadas à API

Toda requisição que utiliza a chave de aplicação deve enviar o header:

X-Api-Key: <chave gerada>

Exemplo ( curl )

curl -X GET "https://<host>/api/automated-searches/<automatedSearchId>" -H "X-ApiKey: <chave>"

Consumo da API

As rotas expostas pela API estão documentadas em https://buscacep.org.br/swagger/index.html:

Para utilizar, primeiro informe a chave de API:

Rotas (Endpoints)

Método	Rota	Descrição
POST	/api/automated-searches	Cria uma consulta automática
GET	/api/automated-searches/{id}	Obtém uma consulta automática
PUT	/api/automated-searches/{id}	Atualiza uma consulta automática
PATCH	/api/automated-searches/{id}/active	Ativa/desativa uma consulta automática
GET	/api/automated-searches	Lista todas as consultas automáticas da organização
GET	/api/automatedsearches/{id}/notarial-acts	Lista (paginado) os atos notariais encontrados pela consulta

Especificação das rotas

Criar consulta automática - POST /api/automated-searches

Cria uma nova consulta automática para a organização/conta pessoal.

Requisição ( AutomatedSearchData ):

{

"personEntries": [

{ "identifier": "12345678901", "name": "Nome da pessoa/empresa" }

"actType": "Deed",

"startDate": "2024-01-01T00:00:00",

"endDate": null,

"nextExecutionDate": "2026-08-01T00:00:00",

"recurrenceIntervalInDays": 30,

"resultType": "Full",

"emailNotificationType": "OnlyWhenNewActsFound",

"responsibleIdentifier": "12345678901"

}

Campo	Tipo	Obrigatório	Observações
personEntries[]	PersonEntryData[]	Sim (mín. 1)	Pessoas/empresas monitoradas pela consulta automática. Campos de cada item abaixo.
personEntries[].identifier	string (CPF ou CNPJ)	Sim	CPF ou CNPJ da pessoa/empresa monitorada
personEntries[].name	string (2–200 caracteres)	Sim	Nome da pessoa/empresa monitorada, sem espaços nas pontas
actType	"PowerOfAttorney" \| "Deed"	Não	Filtra por tipo de ato (Procuração ou Escritura). Omitido = ambos
startDate	datetime	Não	Retorna os atos que foram criados a partir dessa data
endDate	datetime	Não	Retorna os atos que foram criados até essa data
nextExecutionDate	datetime	Não	Próxima data de execução agendada. Quando não informada, é calculada automaticamente.
recurrenceIntervalInDays	int (15 - 30)	Sim	Intervalo de recorrência da execução automática, em dias. Atualmente, pode ser configurado para o intervalo de 15 a 30 dias.
resultType	"Full" \| "Incremental"	Sim	Full = o resultado de cada consulta e documento gerado irá conter todos os atos que já foram encontrados; Incremental = só o que mudou desde a última execução da consulta
emailNotificationType	"EveryExecution" \| "OnlyWhenNewActsFound"	Não	Quando notificar por email. Os e-mails que vão receber notificação devem ser configurados no site. OnlyWhenNewActsFound só tem efeito quando o resultType é Incremental . Quando resultType = Full , a notificação ocorre sempre.
responsibleIdentifier	string (CPF)	Sim	CPF do responsável referenciado no documento gerado ao fim de cada processamento. Deve ser administrador da organização. Não pode ser alterado depois de criado.

Resposta ( AutomatedSearchSummary ):

{

"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",

"dateCreated": "2026-01-10T12:00:00Z",

"dateUpdated": null,

"nextExecutionDate": "2026-08-01T00:00:00Z",

"isActive": true,

"recurrenceIntervalInDays": 30,

"resultType": "Full",

"emailNotificationType": "OnlyWhenNewActsFound"

}

Campo	Tipo	Observações
id	Guid	Identificador da consulta automática criada
dateCreated	datetime	Data/hora de criação
dateUpdated	datetime	Data/hora da última atualização
nextExecutionDate	datetime	Próxima data de execução agendada
isActive	bool	Indicativo de consulta ativa
recurrenceIntervalInDays	int	Recorrência da execução em dias
resultType	"Full" \| "Incremental"	Tipo da consulta
emailNotificationType	"EveryExecution" \| "OnlyWhenActsFound" \| null	Condição para disparo do e-mail de notificação.

Obter consulta automática - GET /api/automated-searches/{id}

Retorna os detalhes completos de uma consulta automática.

Requisição: identificador da consulta automática na rota.

Resposta: (AutomatedSearchModel que estende AutomatedSearchSummary):

Campo	Tipo	Observações
id	Guid	Identificador da consulta automática criada
dateCreated	datetime	Data/hora de criação
dateUpdated	datetime	Data/hora da última atualização
nextExecutionDate	datetime	Próxima data de execução agendada
isActive	bool	Indicativo de consulta ativa
recurrenceIntervalInDays	int	Recorrência da execução em dias
resultType	"Full" \| "Incremental"	Tipo da consulta
emailNotificationType	"EveryExecution" \| "OnlyWhenActsFound" \| null	Condição para disparo do e-mail de notificação.
actType	"PowerOfAttorney" \| "Deed"
startDate	datetime	Retorna os atos que foram criados a partir dessa data
endDate	datetime	Retorna os atos que foram criados até essa data
personEntries[]	personEntryData[]	Pessoas/empresas monitoradas pela consulta
personEntries[].identifier	string (CPF ou CNPJ)	CPF ou CNPJ da pessoa/empresa monitorada
personEntries[].name	string	Nome da pessoa/empresa monitorada
contacts[]	ContactSummary[]	Contatos que recebem notificação por e-mail desta consulta.
contacts[].id	Guid	Identificador do contato
contacts[].name	string	Nome do contato
contacts[].email	string	e-mail do contato

Atualizar consulta automática - PUT /api/automated-searches/{id}

Atualizar uma consulta automática existente.

Requisição (AutomatedSearchData): identificador da consulta automática na rota e mesmos campos da criação (seção Criar consulta automática acima), apenas com a inclusão do campo abaixo:

Campo	Tipo	Observações
responsibleIdentifier	string (CPF)	Campo ignorado nas atualizações.

Resposta: (AutomatedSearchSummary): mesmo formato e campos da criação.

Ativa/desativar consulta automática - PATCH /api/automated-searches/{id}/active

Ativa ou desativa a execução recorrente de uma consulta automática, sem excluí-la.

Requisição identificador da consulta automática na rota e booleano no corpo.

true

Campo	Tipo	Obrigatório	Observações
(corpo)	bool	Sim	true ativa, false desativa a consulta automática

Resposta: AutomatedSearchSummary (mesmo formato e campos da criação, ver seção Criar consulta automática acima, com isActive refletindo o novo valor).

Listar consultas automáticas - GET /api/automated-searches

Lista todas as consultas automáticas da organização/conta pessoal.

Requisição: sem corpo, sem parâmetros.

Resposta: array de AutomatedSearchSummary (mesmo formato da seção Criar consulta automática

acima):

[

{

"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",

"dateCreated": "2026-01-10T12:00:00Z",

"dateUpdated": null,

"nextExecutionDate": "2026-08-01T00:00:00Z",

"isActive": true,

"recurrenceIntervalInDays": 30,

"resultType": "Full",

"emailNotificationType": "OnlyWhenNewActsFound"

}

]

Atos notariais encontrados - GET /api/automated-searches/{id}/notarial-acts

Lista de forma paginada os atos notariais encontrados pela consulta automática.

Requisição: identificador da consulta automática na rota e query params
( AutomatedSearchNotarialActPaginatedSearchParams)

Campo	Tipo	Obrigatório	Observações
personEntryIdentifier	string (CPF/CNPJ)	Não	Filtra pelos atos de uma pessoa/empresa específica da lista monitorada
limit	int (1–100)	Não	Padrão 10
offset	int	Não	paginação
order	Ascending \| Descending	Não	Direção da ordenação
orderBy	Type \| NotaryOfficeName \| Date \| City \| Uf	Não	Campos de ordenação

Resposta: PaginatedSearchResponse<AutomatedSearchNotarialActModel>

{

"items": [

{

"type": "Deed",

"book": "123",

"bookComplement": "A",

"page": "45",

"pageComplement": null,

"date": "2026-03-15T00:00:00",

"notaryOffice": {

"name": "1º Tabelionato de Notas",

"cns": 12345,

"uf": "SP",

"city": "São Paulo"

}

"totalCount": 1

}

Campo	Tipo	Observações
items[]	AutomatedSearchNotarialActModel[]	Página atual de atos notariais encontrados
items[].type	"PowerOfAttorney" \| "Deed"	Tipo do ato
items[].book	string	Livro do ato no cartório
items[].bookComplement	string	Complemento do livro
items[].page	string	Folha do ato no cartório
items[].pageComplement	string	Complemento da folha
items[].date	datetime	Data do ato
items[].notaryOffice	AutomatedSearchNotarialActNotaryOfficeModel	Tabelionato de Notas onde o ato foi lavrado. Campos abaixo
items[].notaryOffice.name	string	Denominação do cartório
items[].notaryOffice.cns	int	CNS (Código Nacional de Serventia)
items[].notaryOffice.uf	UF	UF do cartório
items[].notaryOffice.city	string	Cidade do cartório
totalCount	int	Total de atos encontrados (todas as páginas)

Webhook

Configuração

1. Acesse a área de gerenciamento e vá para a seção Webhook.

2. Clique em Configurar (ou Editar, se já existir).

3. Informe:

URL (obrigatória, HTTPS, até 500 caracteres).
Ativo (liga/desliga o envio sem precisar excluir a configuração).
Eventos(pelo menos 1 selecionado) ver tabela de eventos abaixo.

4. Ao salvar, um segredo é exibido uma única vez, com opção de copiar. Opcionalmente

(recomendável), ele pode ser utilizado para validar a assinatura das entregas (ver Assinatura da

entrega, abaixo).

Cada organização tem no máximo um webhook cadastrado. Para trocar URL, edite o existente.

Regerar segredo

Botão Regenerar segredo na tela de webhook. Gera um novo segredo. O anterior deixa de validar imediatamente. Use se o segredo for exposto/comprometido.

Entrega de eventos

Eventos suportados:

Evento ( eventType no payload)	Quando dispara	Dados
automated-searchexecution.completed	Uma execução de busca automatizada termina de processar	{ "automatedSearchId": " <string>" }

Evento ( eventType no

payload)

Quando dispara

Dados

automated-searchexecution.completed

Uma execução de busca

automatizada termina de

processar

{ "automatedSearchId": "

<string>" }

lista cresce conforme novas funcionalidades forem adicionadas; a tela de configuração sempre
reflete os eventos disponíveis no momento.

Formato do Payload

Toda entrega é um POST com corpo JSON no formato:

{

"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",

"eventType": "automated-search-execution.completed",

"data": {

"automatedSearchId": "..."

}

id - identificador único da entrega (útil para deduplicação/idempotência do lado do receptor).
eventType — string do evento (tabela acima).
data — objeto específico do evento.

Content-Type: application/json .

Assinatura da entrega (segurança)

Cada requisição de webhook chega em dois headers:

X-Webhook-Timestamp: <timestamp Unix em segundos>

X-Webhook-Signature: <hash HMAC-SHA256 em hexadecimal>

Exemplo:

A assinatura é calculada assim:

mensagem = "{timestamp}.{corpo_json_bruto}"

assinatura = HMAC_SHA256(chave = secret, mensagem).hexdigest()

No receptor, para validar:

1. Recalcule a assinatura usando o secret do webhook, o valor exato do header X-WebhookTimestamp e o corpo bruto da requisição (sem re-serializar o JSON, use o "body cru").

2. Compare com X-Webhook-Signature (comparação em tempo constante).

3. (Recomendado) Rejeite se o timestamp estiver muito distante do horário atual (ex.: > 5 minutos),

para mitigar replay de requisições antigas.

Exemplo em Node.js:

const crypto = require('crypto');

function isValidSignature(rawBody, timestampHeader, signatureHeader, secret) {

const expected = crypto

.createHmac('sha256', secret)

.update(timestampHeader, 'utf8')

.update('.', 'utf8')

.update(rawBody)

.digest('hex');

return crypto.timingSafeEqual(

Buffer.from(expected, 'hex'),

Buffer.from(signatureHeader, 'hex')

);

}

Exemplo em C#:

using System.Security.Cryptography ;

using System.Text;

static bool IsValidSignature(string rawBody, string timestampHeader, string

signatureHeader, string secret) {

var key = Encoding.UTF8.GetBytes(secret);

var message = Encoding.UTF8.GetBytes($"{timestampHeader}.{rawBody}");

using var hmac = new HMACSHA256(key);

var expected = hmac.ComputeHash(message);

var received = Convert.FromHexString(signatureHeader);

return CryptographicOperations.FixedTimeEquals(expected, received);

)

Retentativas

O BuscaCEP considera sucesso qualquer resposta HTTP 2xx.
Em caso de falha (erro de rede, timeout, status ≠ 2xx), reagenda com backoff

Tentativa	Intervalo até a próxima
1ª falha	1 minuto
2ª falha	5 minutos
3ª falha	30 minutos
4ª falha	120 minutos
5ª falha	sem novas tentativas

=> Total de até 5 tentativas por entrega antes de desistir definitivamente.

Boas práticas para o receptor

Responder rapidamente (2xx) e processar de forma assíncrona, se o processamento for demorado.
Validar a assinatura antes de processar o corpo ( payload ).
Tratar entregas de forma idempotente usando o campo id (retentativas podem, em cenários de falha de rede após o processamento já ter ocorrido do lado do receptor, gerando reprocessamento).
Manter o segredo fora do código-fonte (variável de ambiente / cofre de segredos).
Em caso de perda/vazamento, pode gerar um novo segredo no gerenciamento.