xBlack
Painel
documentação

API do xBlack

REST sobre HTTPS, resposta em JSON, autenticação por chave. Consulta CPF, placa e telefone com o mesmo saldo e o mesmo preço por consulta do painel — a API não tem plano próprio.

base url
https://api.xblackapi.com/v1
rotas
04 endpoints
rate limit
60 req/min
autenticação

Chave no header

Toda requisição leva a chave em Authorization. Ela identifica a conta e o saldo — não existe usuário e senha na API. Você gera e revoga chaves em Painel → API.

header
Authorization: Bearer xbk_live_sua_chave
Accept: application/json

Nunca no front-end. A chave dá acesso ao seu saldo — se ela sair no bundle do navegador, qualquer visitante consegue ler e gastar. Mantenha em variável de ambiente do servidor.

início rápido

Primeira chamada

Troque a chave e rode. A resposta é o registro completo, com o protocolo para conciliação. Campo que a fonte não tem não vem como null: ele simplesmente não aparece no JSON — só os seis campos de controle estão sempre lá.

curl -sS "https://api.xblackapi.com/v1/cpf/41788214055" \
  -H "Authorization: Bearer xbk_live_sua_chave" \
  -H "Accept: application/json"

resposta · 200

{
  "protocolo": "XB-CMSOYR8NP000L0WW8M0EVK1EH",
  "consultado_em": "2026-08-11T17:58:00.000Z",
  "custo_creditos": 1,
  "saldo_restante": 71,
  "latencia_ms": 412,
  "encontrado": true,
  "cpf": "41788214055",
  "nome": "Marcos Aurélio Tavares Lima",
  "nascimento": "12/03/1981",
  "nome_mae": "Terezinha Tavares Lima",
  "nome_pai": "Aurélio Ferreira Lima",
  "sexo": "M",
  "estado_civil": "Casado",
  "obito": "não",
  "telefone": "11984327710",
  "email": "[email protected]",
  "endereco": {
    "logradouro": "Rua Padre Estêvão Pernet, 128",
    "bairro": "Tatuapé",
    "municipio": "São Paulo",
    "uf": "SP",
    "cep": "03315000"
  }
}
cobrança

O que debita e o que não debita

Você paga por resposta com resultado. Nem toda requisição vira crédito gasto.

Custo
Cada consulta respondida debita o custo da rota do seu saldo.
Sem resultado
Também debita. A consulta rodou e a fonte respondeu — a resposta vem com encontrado: false.
Estorno
Erro do provedor ou timeout devolve o crédito automaticamente.
Rate limit
60 req/min por chave, no padrão.
Protocolo
Toda resposta traz protocolo, para conciliar com o extrato de créditos.
Validade
Créditos não vencem e não resetam. Não há mensalidade.
respostas

Códigos de status

Só o 200 não é erro — e ele cobre também a consulta que não achou registro. Quem diz se veio dado é o campo encontrado, nunca o status.

  • 200okConsulta respondida. Crédito debitado — inclusive quando encontrado é false.
  • 400parâmetro inválidoFormato do documento não bate. Nada é debitado.
  • 401chave inválidaHeader Authorization ausente, errado ou revogado.
  • 402saldo insuficienteCompre créditos para voltar a receber respostas.
  • 429rate limitAcima do limite da chave. A espera em segundos vem na mensagem do erro.
  • 501módulo indisponívelA rota existe, a fonte está fora do catálogo. Nada é debitado.
  • 502provedor foraA fonte não respondeu. Estorno automático.
endpoints

Referência das rotas

Cada rota com o parâmetro que aceita, o custo em créditos e a resposta que devolve.

GET/v1/cpf/{cpf}1 cr

CPF — dados cadastrais

parâmetro

cpf — 11 dígitos, sem pontuação.

requisição

curl -sS "https://api.xblackapi.com/v1/cpf/41788214055" \
  -H "Authorization: Bearer xbk_live_sua_chave" \
  -H "Accept: application/json"

resposta · 200

json
{
  "protocolo": "XB-CMSOYR8NP000L0WW8M0EVK1EH",
  "consultado_em": "2026-08-11T17:58:00.000Z",
  "custo_creditos": 1,
  "saldo_restante": 71,
  "latencia_ms": 412,
  "encontrado": true,
  "cpf": "41788214055",
  "nome": "Marcos Aurélio Tavares Lima",
  "nascimento": "12/03/1981",
  "nome_mae": "Terezinha Tavares Lima",
  "nome_pai": "Aurélio Ferreira Lima",
  "sexo": "M",
  "estado_civil": "Casado",
  "obito": "não",
  "telefone": "11984327710",
  "email": "[email protected]",
  "endereco": {
    "logradouro": "Rua Padre Estêvão Pernet, 128",
    "bairro": "Tatuapé",
    "municipio": "São Paulo",
    "uf": "SP",
    "cep": "03315000"
  }
}
GET/v1/placa/{placa}2 cr

Placa — ficha do veículo

parâmetro

placa — 7 caracteres, Mercosul ou padrão antigo.

requisição

curl -sS "https://api.xblackapi.com/v1/placa/RIO2A18" \
  -H "Authorization: Bearer xbk_live_sua_chave" \
  -H "Accept: application/json"

resposta · 200

json
{
  "protocolo": "XB-CMSOYR8NP000L0WW8M0EVK1EJ",
  "consultado_em": "2026-08-11T17:58:07.000Z",
  "custo_creditos": 2,
  "saldo_restante": 65,
  "latencia_ms": 640,
  "encontrado": true,
  "placa": "RIO2A18",
  "modelo": "Toyota Corolla XEi 2.0",
  "chassi": "9BRBLWHEXM0294417",
  "proprietario": {
    "nome": "Marcos Aurélio Tavares Lima",
    "documento": "41788214055",
    "telefone": "11984327710",
    "endereco": "Rua Padre Estêvão Pernet, 128",
    "bairro": "Tatuapé",
    "cidade": "São Paulo",
    "cep": "03315000"
  }
}
GET/v1/cpf/{cpf}/completo4 cr

CPF PRO — dossiê completo

parâmetro

cpf — 11 dígitos, sem pontuação.

requisição

curl -sS "https://api.xblackapi.com/v1/cpf/41788214055/completo" \
  -H "Authorization: Bearer xbk_live_sua_chave" \
  -H "Accept: application/json"

resposta · 200

json
{
  "protocolo": "XB-CMSOYR8NP000L0WW8M0EVK1EI",
  "consultado_em": "2026-08-11T17:58:03.000Z",
  "custo_creditos": 4,
  "saldo_restante": 67,
  "latencia_ms": 2180,
  "encontrado": true,
  "cpf": "41788214055",
  "nome": "Marcos Aurélio Tavares Lima",
  "nascimento": "12/03/1981",
  "nome_mae": "Terezinha Tavares Lima",
  "nome_pai": "Aurélio Ferreira Lima",
  "sexo": "M",
  "estado_civil": "Casado",
  "obito": "não",
  "telefone": "11984327710",
  "email": "[email protected]",
  "endereco": {
    "logradouro": "Rua Padre Estêvão Pernet, 128",
    "bairro": "Tatuapé",
    "municipio": "São Paulo",
    "uf": "SP",
    "cep": "03315000"
  },
  "rg": "228147630",
  "titulo_eleitor": "104428820159",
  "renda_estimada": "9000-14000",
  "ocupacao": "2521-05",
  "veiculos": [
    { "placa": "RIO2A18", "veiculo": "Toyota Corolla XEi 2.0" },
    { "placa": "EJK4H72", "veiculo": "Honda Fit LX 1.4" }
  ]
}
GET/v1/telefone/{telefone}5 cr

Telefone — de quem é o número

parâmetro

telefone — DDD + número, só dígitos.

requisição

curl -sS "https://api.xblackapi.com/v1/telefone/16997096188" \
  -H "Authorization: Bearer xbk_live_sua_chave" \
  -H "Accept: application/json"

resposta · 200

json
{
  "protocolo": "XB-CMSOYR8NP000L0WW8M0EVK1EK",
  "consultado_em": "2026-08-11T17:58:11.000Z",
  "custo_creditos": 5,
  "saldo_restante": 60,
  "latencia_ms": 210,
  "encontrado": true,
  "telefone": "16997096188",
  "titulares": [
    {
      "nome": "Juliana Alves de Mattos",
      "cpf": "28444046850",
      "nascimento": "04/09/1988",
      "nome_mae": "Sandra Alves de Mattos",
      "municipio": "Ribeirão Preto",
      "uf": "SP"
    }
  ]
}
integração com ia

Prompt pronto

Cole em qualquer assistente e diga a linguagem. O prompt já carrega as regras que um código gerado no chute costuma errar — o 200 sem registro que mesmo assim cobra, e o 429 sem header de retry.

prompt
Você vai escrever um cliente para a API do xBlack.

BASE URL
https://api.xblackapi.com/v1

AUTENTICAÇÃO
Header `Authorization: Bearer <chave>`. A chave vem de variável de ambiente
XBLACK_API_KEY e nunca aparece em código de front-end.

ROTAS
- GET /v1/cpf/{cpf} — CPF — dados cadastrais Parâmetro: cpf (11 dígitos, sem pontuação.) Custo: 1 crédito(s).
- GET /v1/placa/{placa} — Placa — ficha do veículo Parâmetro: placa (7 caracteres, Mercosul ou padrão antigo.) Custo: 2 crédito(s).
- GET /v1/cpf/{cpf}/completo — CPF PRO — dossiê completo Parâmetro: cpf (11 dígitos, sem pontuação.) Custo: 4 crédito(s).
- GET /v1/telefone/{telefone} — Telefone — de quem é o número Parâmetro: telefone (DDD + número, só dígitos.) Custo: 5 crédito(s).

FORMA DA RESPOSTA
Todo 200 traz seis campos fixos, além dos campos da rota:
`protocolo`, `consultado_em`, `custo_creditos`, `saldo_restante`,
`latencia_ms` e `encontrado` (booleano).

Datas e booleanos vêm como STRING já formatada em pt-BR: nascimento é
"12/03/1981", não ISO; óbito é "não", não false. Não tente parsear como ISO.

Campo ausente é ausente, não nulo: quando a fonte não tem o dado, a chave não
aparece no JSON. Tipe tudo como opcional, menos os seis fixos.

REGRAS DE RESPOSTA (trate todas)
- 200: resposta da consulta. SEMPRE debita o custo da rota, inclusive quando
  `encontrado` é false — a busca rodou e a fonte respondeu. NÃO existe 204:
  para saber se veio registro, leia `encontrado`, nunca o status.
- 400: parâmetro fora do formato. Valide antes de chamar. Nada é debitado.
- 401: chave ausente, errada ou revogada.
- 402: saldo insuficiente. Não faça retry — precisa comprar crédito.
- 429: acima de 60 requisições por minuto na chave. NÃO há header
  Retry-After; a espera em segundos vem no texto da mensagem de erro. Use
  backoff próprio.
- 501: a rota existe mas o módulo está indisponível no momento. Nada é debitado.
- 502: provedor fora do ar. O crédito é estornado automaticamente; pode tentar
  de novo.

O QUE ENTREGAR
Um módulo com uma função por rota, tipagem dos campos de resposta, timeout de
30s, retry com backoff exponencial APENAS em 429 e 502, e o `protocolo` de
cada resposta registrado em log para conciliação com o extrato.

Linguagem: <diga aqui: TypeScript, Python, Go…>