Integre relatórios de background check aos seus sistemas

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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. 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.

curl -X POST 'https://bgc.xtrategyai.com.br/v1/checks' \
  -H 'X-Billing-Token: bgt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "cpf": "22009982878"
  }'

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",
  "test_mode": false
}

curl 'https://bgc.xtrategyai.com.br/v1/checks/b3f1a2c4-...-9e21/report' \
  -H 'X-Billing-Token: bgt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

{
  "check_request_id": "b3f1a2c4-...-9e21",
  "status": "processando",
  "test_mode": false,
  "report": null
}

{
  "check_request_id": "b3f1a2c4-...-9e21",
  "status": "concluido",
  "test_mode": false,
  "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 ... */ ]
  }
}

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. Testando sem consumir crédito

Envie "test_mode": true no corpo do POST — a resposta já vem pronta na hora, com dado simulado, sem consultar nenhuma fonte real e sem descontar crédito. Use para validar sua integração de ponta a ponta antes de ir para produção.

5. 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.