Guia de integração

API BigDataBoy

Uma API REST para consultas de pessoas físicas, empresas, KYC e processos judiciais. Todas as respostas são JSON.

URL base

https://bigdataboy.zynkra.com.br/v1

Você não precisa de credenciais de nenhum provedor externo. Toda a integração é feita apenas com a sua API key BigDataBoy, gerada no painel.

Autenticação

Envie sua chave em todas as requisições pelo header X-API-Key. As chaves começam com bdb_.

X-API-Key: bdb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Crie uma conta em /cadastro.
Adicione créditos via PIX em Painel → Créditos.
Gere a chave em Painel → API e integração.

A chave é exibida apenas uma vez. Gerar uma nova chave revoga a anterior imediatamente. Nunca exponha a chave em código executado no navegador ou em apps móveis — faça as chamadas a partir do seu servidor.

Primeira requisição

cURL

curl -X POST "https://bigdataboy.zynkra.com.br/v1/pessoas/consulta/12345678900" \
  -H "X-API-Key: $BIGDATABOY_KEY"

Python

import os, requests

r = requests.post(
    "https://bigdataboy.zynkra.com.br/v1/pessoas/consulta/12345678900",
    headers={"X-API-Key": os.environ["BIGDATABOY_KEY"]},
    timeout=60,
)
r.raise_for_status()
print("Saldo restante:", r.headers["X-Balance"])
print(r.json())

Node.js

const res = await fetch("https://bigdataboy.zynkra.com.br/v1/pessoas/consulta/12345678900", {
  method: "POST",
  headers: { "X-API-Key": process.env.BIGDATABOY_KEY },
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
console.log("Saldo restante:", res.headers.get("X-Balance"));
console.log(await res.json());

Endpoints

Todos os endpoints usam o método POST, sem corpo. O parâmetro vai na URL, somente com números.

Endpoint	Descrição	Custo
POST/v1/pessoas/consulta/{cpf}	Consulta Individual	1 token
POST/v1/pessoas/kyc/{cpf}	KYC Compliance	1 token
POST/v1/processos/{processo}	Processos Judiciais	1 token
POST/v1/pessoas/midias/{cpf}	Exposição em Mídias	1 token
POST/v1/fastpass/{cpf}	Onboarding Turbo	1 token
POST/v1/fastpass/taxid/{cpf}	IDTag	1 token
POST/v1/empresas/{cnpj}	Empresas Básico	1 token
POST/v1/empresas/quadrosocietario/{cnpj}	Quadro Societário	1 token
GET/v1/saldo	Saldo atual	Grátis

Esquemas detalhados e teste interativo na referência OpenAPI.

Cobrança e saldo

Cada requisição bem-sucedida (HTTP 200) consome 1 token.
Requisições com erro (4xx/5xx) não são cobradas — o token é estornado automaticamente.
O saldo restante é retornado no header X-Balance de toda resposta 200.
Consulte o saldo a qualquer momento com GET /v1/saldo (gratuito).
Créditos não expiram.

curl "https://bigdataboy.zynkra.com.br/v1/saldo" -H "X-API-Key: $BIGDATABOY_KEY"
# {"balance": 249}

Erros

Erros retornam JSON no formato {"detail": "mensagem"}.

Status	Significado	Cobrado
200	Consulta realizada	Sim
401	API key ausente ou inválida	Não
402	Saldo insuficiente — adicione créditos	Não
404	Nenhum dado encontrado para o documento	Não
422	Parâmetro inválido	Não
502	Falha temporária no provedor de dados	Não

Boas práticas

Armazene a chave em variável de ambiente ou cofre de segredos.
Use timeout de pelo menos 60 segundos — algumas consultas agregam várias fontes.
Em erros 502, faça nova tentativa com backoff exponencial.
Monitore o header X-Balance para recarregar antes de o saldo acabar.