Integre relatórios de background check aos seus sistemas
A API é sempre assíncrona: você solicita uma checagem, recebe um identificador na hora e busca o relatório quando ele terminar — por consulta (polling) ou por webhook. Esta página explica o fluxo; a referência técnica completa de cada campo fica no Swagger, sempre atualizado.
1. Autenticação
Toda chamada leva um token de cobrança no header X-Billing-Token, entregue pelo nosso time na hora de fechar a integração — identifica a empresa contratante e a operação que vai consumir o crédito de cada checagem. Se sua empresa tiver mais de uma operação cadastrada, informe qual delas no header opcional X-Operacao-Codigo.
X-Billing-Token: bgt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx2. Solicitar um relatório (assíncrono)
O relatório completo consulta várias fontes com tempos de resposta bem diferentes — algumas respondem em menos de 1 segundo, outras (certidões que dependem de captcha) levam dezenas de segundos. Por isso o fluxo é sempre em duas etapas.
Passo 1 — criar a checagem
Responde na hora com 202 e um check_request_id — o processamento continua em segundo plano.
curl -X POST 'https://bgc.xtrategyai.com.br/v1/checks' \
-H 'X-Billing-Token: bgt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-H 'Content-Type: application/json' \
-d '{
"cpf": "22009982878"
}'Para pessoa jurídica, envie cnpj no lugar de cpf — nunca os dois campos juntos. O relatório de PJ é solicitado da mesma forma, pelo mesmo endpoint.
curl -X POST 'https://bgc.xtrategyai.com.br/v1/checks' \
-H 'X-Billing-Token: bgt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-H 'Content-Type: application/json' \
-d '{
"cnpj": "05386606000120"
}'{
"check_request_id": "b3f1a2c4-...-9e21",
"status": "pendente",
"credits_charged": "1.00"
}Passo 2 — buscar o resultado (polling)
Sempre responde 200. Enquanto não termina, report vem nulo — não é erro, é o estado normal de quem está aguardando. Consulte de novo em alguns segundos.
curl 'https://bgc.xtrategyai.com.br/v1/checks/b3f1a2c4-...-9e21/report' \
-H 'X-Billing-Token: bgt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'{
"check_request_id": "b3f1a2c4-...-9e21",
"status": "processando",
"report": null
}{
"check_request_id": "b3f1a2c4-...-9e21",
"status": "concluido",
"report": {
"verdict": "verde",
"verdict_label": "Regular",
"document_number": "DUE-2026-000123",
"control_code": "A1B2C3D4",
"pdf_url": "https://bgc.xtrategyai.com.br/v1/checks/b3f1a2c4-.../report?format=pdf",
"source_results": [ /* ... 1 item por fonte consultada ... */ ],
"rule_firings": [ /* ... trilha de decisão das regras ... */ ]
}
}Status possíveis
| Status | Significado |
|---|---|
| pendente | Aceito, aguardando um worker livre para processar. |
| processando | Fontes sendo consultadas agora. |
| concluido | Relatório pronto — campo report preenchido. |
| erro | Falha inesperada no processamento — não consumiu crédito indevidamente; fale com o suporte informando o check_request_id. |
3. Alternativa ao polling: webhook
Em vez de consultar repetidamente, informe callback_url ao criar a checagem — assim que ela terminar (sucesso ou erro), enviamos um POST pra essa URL com um resumo do resultado.
{
"cpf": "22009982878",
"callback_url": "https://seusistema.exemplo.com/webhooks/background-check"
}O corpo vem assinado no header X-Background-Signature, um HMAC-SHA256 do corpo bruto calculado com o segredo da sua empresa (entregue junto com o token de cobrança). Valide antes de confiar no conteúdo — evita que alguém forje uma notificação de "relatório pronto" pra sua URL.
import hmac, hashlib
def valido(corpo_bruto: bytes, assinatura_recebida: str, segredo: str) -> bool:
esperado = hmac.new(segredo.encode(), corpo_bruto, hashlib.sha256).hexdigest()
return hmac.compare_digest(f"sha256={esperado}", assinatura_recebida)Entrega best-effort: uma única tentativa, timeout de 10s. Se seu endpoint estiver fora do ar no momento exato, a checagem continua concluída normalmente — busque o resultado por polling nesse caso.
4. Validação pública do PDF
Todo relatório emitido traz um número de documento, um código de controle e um QR code. Quem recebe o PDF (não precisa de token) pode confirmar que ele é autêntico e não foi alterado:
curl 'https://bgc.xtrategyai.com.br/checks/validate?document_number=DUE-2026-000123&control_code=A1B2C3D4'Essa URL não muda com a versão da API — fica estável mesmo em PDFs emitidos há muito tempo, porque já está impressa no documento.
Referência técnica completa
Todo campo, todo tipo de dado e cada checagem individual — de pessoa física (situação do CPF, processos criminais e trabalhistas, pendências financeiras, mandados de prisão e mais) e de pessoa jurídica (situação do CNPJ, QSA, sanções, FGTS, CNDs estaduais e mais) — tem sua própria rota documentada no Swagger, sempre a versão exata do que está em produção.
Abrir https://bgc.xtrategyai.com.br/docsPerguntas frequentes
POST /v1/batches aceita um arquivo (.csv/.xlsx/.txt) ou uma lista separada por vírgula. Cada CPF do lote vira uma checagem, processada pelo mesmo mecanismo — só com prioridade menor que checagens sob demanda.?format=pdf quando o status já é "concluido" — devolve o arquivo direto, com o header Content-Disposition apontando o nome do arquivo.