Integre a Brodslab ao seu sistema

Visão geral

Base URL local: http://localhost:8080 — em produção, o domínio da Brodslab (atrás de Cloudflare/TLS).

O fluxo é assíncrono: você cria uma transação (POST, resposta 202 imediata) e busca o resultado por polling ou recebe um webhook quando terminar. Toda resposta de análise segue o mesmo formato base, independente do produto:

Convenção: as chaves do JSON são em inglês (boa prática de API); o conteúdo — motivos, alertas, rótulos — é em português, porque é o que o usuário final brasileiro lê.

Autenticação

A integração de máquina usa OAuth2 client_credentials. Troque suas credenciais por um access token (Bearer, expira em 1 hora) e envie-o em todas as chamadas.

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Nas chamadas seguintes: Authorization: Bearer <access_token>. O Testar ▶ executa a chamada de verdade contra este servidor — o token obtido fica guardado na página e é usado automaticamente nos testes dos outros endpoints abaixo.

Validador de boleto Disponível

Confronta o valor impresso no documento (OCR) com o valor embutido no código de barras, na linha digitável, no QR Pix e no Pix copia-e-cola — até 5 fontes independentes. Divergência entre qualquer uma delas reprova.

{
  "transaction_id": "1cd31d77-b52d-4095-984c-4d8acd42b593",
  "status": "processando",
  "href": "/transactions/1cd31d77-b52d-4095-984c-4d8acd42b593"
}

Resultado completo, escopado ao client_id que criou a transação. Faça polling até status sair de processando — ou use webhook e busque só quando avisado. Vale pros dois produtos (boleto e Pix).

{
  "schema_version": "2.1",
  "verdict": {
    "status": "APPROVED",
    "approved": true,
    "summary": "Valores conferem.",
    "reasons": ["Valores conferem."]
  },
  "document_classification": {
    "detected_type": "boleto_bancario",
    "matches_expected": true,
    "confidence": "alta"
  },
  "security": { "alerts": [] }
}

Validador de comprovante Pix Disponível

Confronta o EndToEndId — o ID da transação no formato oficial do Bacen, que embute a instituição (ISPB) e a data/hora do processamento — com o que está impresso no comprovante. Um print editado raramente corrige esse ID junto. Aceita imagem (JPG/PNG) por ora.

Mesmos campos de /transactions (acima): file, source_url, source_base64 e callback_url opcional.

{
  "transaction_id": "13228636-20ce-46a4-b1f9-13c6b8b3c0ae",
  "status": "processando",
  "href": "/transactions/13228636-20ce-46a4-b1f9-13c6b8b3c0ae"
}

O resultado sai no mesmo GET /transactions/{id} do boleto — o servidor identifica o produto pela transação.

{
  "products": {
    "pix_receipt_validator": {
      "e2e_id": {
        "value": "E18236120202607042146S08DC7FFB82",
        "format_valid": true,
        "institution": "Nu Pagamentos (Nubank)",
        "embedded_datetime_brt": "04/07/2026, 18:46"
      },
      "checks": {
        "datetime_check": { "matches": true, "difference_minutes": 0 },
        "institution_check": { "matches": true }
      }
    }
  }
}

Forense de PDF API em breve

Detecta sinais de adulteração na estrutura de um PDF: metadados suspeitos, fonte tipográfica trocada, texto invisível sobreposto, atualizações incrementais (histórico de edições), datas impossíveis.

OCR centralizado

Os três produtos usam o mesmo motor de OCR (PaddleOCR) internamente. Ele nunca é vendido separadamente nem exposto publicamente — mas é ele quem roda a tipificação de documentos sobre o texto que lê, e por isso está documentado aqui.

• Faz: extrai texto de imagens e páginas escaneadas; sugere o tipo do documento a partir de sinais estruturais (linha digitável, EndToEndId, marcadores Pix).
• Não faz: não confirma autenticidade (papel do forense); não decide se um valor está certo (papel do boleto/Pix). A classificação que ele sugere é um indício — a validação final é sempre de cada produto.

Webhooks

Em vez de polling, envie callback_url ao criar a transação. A Brodslab dispara 2 webhooks assinados por transação:

O corpo é magro de propósito — nenhum dado sensível trafega no webhook. O resultado completo você busca com um GET autenticado no href:

{
  "event": "transaction.completed",
  "transaction_id": "uuid",
  "status": "concluido",
  "created_at": "2026-07-07T12:00:00.000Z",
  "completed_at": "2026-07-07T12:00:09.000Z",
  "sent_at": "2026-07-07T12:00:09.100Z",
  "app_version": "v40",
  "schema_version": "2.1",
  "href": "/transactions/uuid"
}

Verificando a assinatura

Cada entrega traz os headers X-Brodslab-Event, X-Brodslab-Delivery, X-Brodslab-Timestamp e X-Brodslab-Signature: sha256=<hmac>. Antes de confiar no payload, calcule HMAC-SHA256(corpo_cru, WEBHOOK_SECRET) e compare com a assinatura.

Tipificação de documentos

O campo document_classification está presente em todo retorno de análise. Ele identifica que tipo de documento foi enviado, se bate com o que o produto espera, e declara o escopo — o que é validado e o que (ainda) não é, com o motivo.

{
  "expected_type": ["comprovante_pix"],
  "detected_type": "comprovante_pix",
  "matches_expected": true,
  "confidence": "alta",
  "signals": ["EndToEndId com formato Bacen encontrado"],
  "capabilities": {
    "validated": [
      "Formato do EndToEndId (norma do Bacen)",
      "Instituição embutida no ID × impressa",
      "Data/hora embutida no ID × impressa"
    ],
    "not_validated": [
      {
        "item": "Titular real da chave Pix",
        "reason": "exigiria consulta ao DICT (Bacen) — roadmap"
      }
    ]
  }
}

Quando matches_expected é false, o detected_type mostra o que o documento parece ser de verdade — enviar um boleto ao validador de Pix retorna "detected_type": "boleto_bancario" com explicação clara, em vez de um erro genérico.

Downloads

O openapi.yaml é a descrição formal desta API — é a partir de um arquivo assim que plataformas de documentação geram páginas interativas como esta (e como a de outras empresas do setor). Importe no Postman ou Insomnia pra ganhar todos os endpoints prontos, ou use pra gerar SDKs automaticamente.

A collection já traz o fluxo completo — token → criar transação (boleto ou Pix) → consultar resultado — com as variáveis encadeadas automaticamente pelos scripts de teste do Postman.