Pular para o conteúdo principal

Autenticação

As operações da API pública exigem a API Key da conta. A exceção é o download direto de um documento por um downloadUrl assinado e temporário, emitido por uma consulta autenticada.

A autenticação permite incorporar a BuscaProcessos ao seu produto mantendo a credencial sob controle da sua aplicação. Assim, usuários e equipes acessam os resultados pela experiência que você construiu, sem precisar operar chaves ou alternar entre sistemas.

Benefício para a integração​

  • um padrão simples de autenticação para todos os recursos da API;
  • credencial centralizada para sistemas e automações;
  • rotação e revogação sem alterar o contrato dos endpoints;
  • separação clara entre a experiência do usuário e o segredo de acesso.

URL base​

https://api.buscaprocessos.app.br

Use exclusivamente este host. Hosts diferentes podem retornar HTTP 404 com código INVALID_API_HOST.

Headers aceitos​

A API aceita, nesta ordem:

  1. x-api-key: <sua_api_key>
  2. Authorization: Bearer <sua_api_key>

Formato recomendado:

x-api-key: bp_live_SUA_CHAVE
Accept: application/json

Ambos os formatos são válidos. Prefira x-api-key na documentação e nos exemplos de integração.

Download direto de documentos​

GET /v1/processos/cnj/{cnj}/documentos-publicos continua exigindo a API Key. Cada item retornado mantém o campo downloadUrl, agora com um download_token temporário:

{
  "id": "f1e5c38b18402890148c0c9347e6d2c2",
  "downloadUrl": "https://api.buscaprocessos.app.br/v1/processos/cnj/0000000-00.2026.8.26.0000/documentos/f1e5c38b18402890148c0c9347e6d2c2/download?source=publicos&download_token=TOKEN_TEMPORARIO"
}

O URL completo pode ser aberto diretamente no navegador ou usado em um link HTML, sem reenviar a API Key:

<a href="DOWNLOAD_URL_RETORNADO_PELA_API">Baixar documento</a>
  • preserve o downloadUrl completo, inclusive a query string;
  • o token é vinculado à conta, ao CNJ e ao documento exato;
  • o prazo padrão é de 10 minutos;
  • consulte novamente documentos-publicos quando o link expirar;
  • retries do mesmo link reutilizam a cobrança já registrada;
  • integrações existentes podem continuar chamando a mesma rota com x-api-key ou Bearer.

O token não contém nem substitui permanentemente a API Key. Ele concede somente o download temporário do documento indicado.

Prefixo da chave​

Chaves geradas pelo produto usam o prefixo:

bp_live_

seguido de 40 caracteres hexadecimais.

Exemplo cURL​

curl --request GET \
  --url 'https://api.buscaprocessos.app.br/v1/processos?cpf_cnpj=00000000000' \
  --header "x-api-key: ${BUSCAPROCESSOS_API_KEY}" \
  --header 'Accept: application/json'

Exemplo com Bearer​

curl --request GET \
  --url 'https://api.buscaprocessos.app.br/v1/processos?cpf_cnpj=00000000000' \
  --header "Authorization: Bearer ${BUSCAPROCESSOS_API_KEY}" \
  --header 'Accept: application/json'

Variável de ambiente​

BUSCAPROCESSOS_API_KEY=bp_live_sua_chave_aqui

Pré-condições de uso​

Antes de autenticar com sucesso, a conta precisa:

  1. Estar com e-mail confirmado.
  2. Possuir uma conta ativa.
  3. Possuir uma API Key válida no Console API.
  4. Ter saldo disponível (exceto em poucos endpoints que permitem saldo zero).
  5. Não estar sob restrição de antifraude ativa.

Respostas de erro​

HTTPCódigoMensagem típica
401API_KEY_REQUIREDEnvie a chave em x-api-key ou Authorization: Bearer.
401INVALID_API_KEYA API key informada é inválida.
403ACCOUNT_INACTIVEA conta vinculada à API key não está ativa.
403EMAIL_VERIFICATION_REQUIREDConfirme o e-mail da conta para liberar o uso da API.
403INSUFFICIENT_CREDITSCréditos insuficientes para processar a consulta.
404INVALID_API_HOSTUse o host api.buscaprocessos.app.br.

Envelope:

{
  "error": {
    "code": "API_KEY_REQUIRED",
    "message": "Envie a chave em `x-api-key` ou `Authorization: Bearer`."
  }
}

Headers de resposta úteis​

A API pode expor:

  • X-BuscaProcessos-Credits-Remaining
  • X-BuscaProcessos-Request-Id
  • X-BuscaProcessos-Search-Log-Id

O corpo de sucesso também pode trazer meta.requestId, meta.searchLogId e meta.creditsRemaining.

CORS​

Headers de autenticação permitidos no CORS da API pública:

Content-Type, X-API-Key, Authorization

Mesmo com CORS aberto, a chave não deve ser usada em frontend público.

Onde obter a chave​

  1. Escolha o pacote em Planos da API
  2. Conclua a contratação em Contratar API
  3. Acesse o Console API ou Entrar
  4. Abra API Keys

Veja também: API Keys · Primeiros passos.