API de Validação Documental: Guia para Desenvolvedores

Este guia cobre tudo o que você precisa para integrar validação documental automatizada na sua aplicação — desde autenticação até tratamento de webhooks. Seja para construir um fluxo de onboarding de clientes, um pipeline de conformidade ou uma ferramenta de automação de back-office, a API CheckFile oferece acesso programático ao mesmo motor de validação alimentado por IA utilizado na plataforma. Você encontrará decisões de arquitetura, referência de endpoints, exemplos de código em Python e Node.js, payloads de webhooks, estratégias de tratamento de erros e padrões de integração que escalam do protótipo à produção.

Este artigo é fornecido apenas para fins informativos e não constitui aconselhamento jurídico, financeiro ou regulatório.

Visão Geral da Arquitetura

A API CheckFile segue um modelo de processamento assíncrono padrão REST, com uploads via POST /v1/files, processamento em fila e entrega de resultados por polling ou webhook. A Circular Bacen 3.978/2020, que dispõe sobre a política de prevenção à lavagem de dinheiro, exige que os sistemas de verificação documental utilizados por instituições reguladas produzam trilhas de auditoria determinísticas e auditáveis — um requisito nativo na arquitetura da CheckFile.

O Regulamento da IA da UE (Regulamento (UE) 2024/1689), aplicável a partir de agosto de 2026, classifica os sistemas de avaliação de risco documental como IA de risco limitado, impondo obrigações de transparência e documentação para fornecedores que integrem IA em fluxos de decisão (EUR-Lex, Regulamento IA). No Brasil, a Lei de IA (PL 2.338/2023) adota classificação similar. Os documentos são carregados via REST, colocados em fila para análise por IA, e os resultados são entregues por polling ou callbacks de webhook.

                                    +-------------------+
                                    |  API de Resultados|
                                    |  GET /files/{id}  |
                                    +--------^----------+
                                             |
App Cliente                                  | Poll ou fetch
    |                                        |
    |  POST /v1/files                +-------+--------+
    +------------------------------->| API de Upload  |
    |                                +-------+--------+
    |                                        |
    |                                        v
    |                               +--------+--------+
    |                               | Fila de         |
    |                               | Processamento   |
    |                               | (validação IA)  |
    |                               +--------+--------+
    |                                        |
    |         Callback de webhook            |
    |<---------------------------------------+
    |         POST seu-endpoint

Três decisões de design chave moldam esta arquitetura:

1. Assíncrono por padrão. A validação documental envolve OCR, detecção de fraude, cruzamento de referências e avaliação de regras. Essas operações levam de 2 a 15 segundos dependendo da complexidade do documento.

2. Entrega dual. Você pode consultar o endpoint de status ou registrar um webhook. O polling funciona para integrações simples; os webhooks são a abordagem recomendada para sistemas em produção.

3. Uploads idempotentes. Cada upload retorna um file_id único. Reenviar o mesmo documento com a mesma chave de idempotência retorna o resultado existente.

Autenticação e Segurança

A autenticação na API CheckFile suporta dois modelos: chave API para integrações servidor-a-servidor, e OAuth 2.0 para acesso com escopo de usuário em aplicações multi-tenant. Todo o tráfego é criptografado com TLS 1.3, e os documentos são criptografados em repouso com AES-256, em conformidade com a LGPD (Lei 13.709/2018, artigo 46).

O Banco Central do Brasil, na Circular 3.978/2020 sobre prevenção à lavagem de dinheiro, exige que os sistemas de verificação documental integrados em processos de onboarding garantam rastreabilidade completa de cada verificação, com carimbo temporal e identificação do operador.

Autenticação por Chave API

Para integrações servidor-a-servidor, passe a sua chave API no cabeçalho X-API-Key:

curl -H "X-API-Key: ck_live_abc123..." \
     https://api.checkfile.ai/v1/files

Chaves com prefixo ck_test_ acessam o ambiente sandbox; chaves com prefixo ck_live_ acessam produção.

OAuth 2.0 para Acesso com Escopo de Usuário

Se a sua aplicação atua em nome de usuários finais (ex.: um SaaS multi-tenant), utilize OAuth 2.0 com fluxo de código de autorização.

Limites de Taxa

Consulte os preços para detalhes dos planos.

Segurança de Transporte

Todo o tráfego é criptografado com TLS 1.3. Todos os documentos carregados são criptografados em repouso com AES-256 e eliminados automaticamente após o período de retenção configurado. Consulte as nossas práticas de segurança.

Endpoints Principais

Enviar e Validar — Passo a Passo

Python (requests)

import requests
import time

API_KEY = "ck_live_abc123..."
BASE_URL = "https://api.checkfile.ai/v1"
HEADERS = {"X-API-Key": API_KEY}

# Passo 1: Enviar lote de documentos como dossiê
response = requests.post(
    f"{BASE_URL}/files/batch",
    headers=HEADERS,
    files=[
        ("files", ("contrato.pdf", open("contrato.pdf", "rb"), "application/pdf")),
        ("files", ("acordo.pdf", open("acordo.pdf", "rb"), "application/pdf")),
        ("files", ("certidao.pdf", open("certidao.pdf", "rb"), "application/pdf")),
    ],
    data={"rule_set": "equipment-leasing"}
)
response.raise_for_status()
file_id = response.json()["id"]
print(f"Dossiê enviado: {file_id}")

# Passo 2: Consultar status
while True:
    status_resp = requests.get(
        f"{BASE_URL}/files/{file_id}/status",
        headers=HEADERS
    )
    status = status_resp.json()["status"]
    if status in ("completed", "failed"):
        break
    time.sleep(2)

# Passo 3: Obter resultados
results = requests.get(
    f"{BASE_URL}/files/{file_id}/results",
    headers=HEADERS
).json()

for doc in results["documents"]:
    print(f"{doc['filename']}: {doc['verdict']} (confiança: {doc['confidence']})")
    if doc["alerts"]:
        for alert in doc["alerts"]:
            print(f"  - {alert['severity']}: {alert['message']}")

Node.js (fetch + FormData)

import fs from 'node:fs';

const API_KEY = process.env.CHECKFILE_API_KEY;
const BASE_URL = 'https://api.checkfile.ai/v1';

// Passo 1: Enviar lote de documentos
const form = new FormData();
form.append('files', new Blob([fs.readFileSync('contrato.pdf')]), 'contrato.pdf');
form.append('files', new Blob([fs.readFileSync('acordo.pdf')]), 'acordo.pdf');
form.append('files', new Blob([fs.readFileSync('certidao.pdf')]), 'certidao.pdf');
form.append('rule_set', 'equipment-leasing');

const uploadRes = await fetch(`${BASE_URL}/files/batch`, {
  method: 'POST',
  headers: { 'X-API-Key': API_KEY },
  body: form,
});
const { id: fileId } = await uploadRes.json();
console.log(`Dossiê enviado: ${fileId}`);

// Passo 2: Consultar status
let status = 'processing';
while (status !== 'completed' && status !== 'failed') {
  await new Promise((r) => setTimeout(r, 2000));
  const statusRes = await fetch(`${BASE_URL}/files/${fileId}/status`, {
    headers: { 'X-API-Key': API_KEY },
  });
  ({ status } = await statusRes.json());
}

// Passo 3: Obter resultados
const results = await fetch(`${BASE_URL}/files/${fileId}/results`, {
  headers: { 'X-API-Key': API_KEY },
}).then((r) => r.json());

for (const doc of results.documents) {
  console.log(`${doc.filename}: ${doc.verdict} (confiança: ${doc.confidence})`);
  for (const alert of doc.alerts) {
    console.log(`  - ${alert.severity}: ${alert.message}`);
  }
}

Payloads de Webhook

Evento de Validação Concluída

{
  "event": "validation.completed",
  "timestamp": "2026-02-09T14:32:08Z",
  "data": {
    "file_id": "dossier_8f3a2b1c",
    "rule_set": "equipment-leasing",
    "verdict": "approved",
    "processing_time_ms": 4280,
    "documents": [
      {
        "filename": "contrato.pdf",
        "type": "contract",
        "verdict": "valid",
        "confidence": 0.97,
        "alerts": []
      }
    ]
  }
}

Evento de Alerta Detectado

{
  "event": "validation.alert",
  "timestamp": "2026-02-09T14:32:06Z",
  "data": {
    "file_id": "dossier_8f3a2b1c",
    "document": {
      "filename": "certidao.pdf",
      "type": "company_registration"
    },
    "alert": {
      "code": "DOC_EXPIRED",
      "severity": "high",
      "message": "Certidão da Junta Comercial expirada em 2025-11-30",
      "field": "validity_date",
      "extracted_value": "2025-11-30",
      "expected": "Documento deve ter menos de 3 meses"
    }
  }
}

Verificação de Assinaturas de Webhook

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Tratamento de Erros

Os códigos de erro da API CheckFile seguem o padrão HTTP RFC 9110. O tratamento robusto de erros é obrigatório em sistemas de conformidade, onde cada tentativa falhada deve ser registrada para efeitos de auditoria ao abrigo da LGPD (artigo 37).

O FATF, nas suas orientações de 2024 sobre abordagem baseada no risco para entidades obrigadas, recomenda que os sistemas automatizados de verificação documental mantenham logs de auditoria completos, incluindo tentativas falhadas, por um período mínimo de 5 anos (FATF, Risk-Based Approach Guidance).

Benchmarks de Desempenho

Começar

O caminho mais rápido para uma integração funcional:

1. Criar uma conta e gerar uma chave API de teste (ck_test_) no dashboard.
2. Enviar um documento de teste utilizando os exemplos curl ou os exemplos de código deste guia.
3. Registrar um webhook para receber resultados de forma assíncrona.
4. Configurar um conjunto de regras adequado aos seus requisitos de negócio.
5. Migrar para produção substituindo a chave de teste por uma chave de produção (ck_live_).

Documentação completa dos endpoints, SDKs (Python, Node.js, Go) e explorador interativo da API estão disponíveis em docs.checkfile.ai. Se você tem dúvidas sobre qual plano se adequa ao seu volume, consulte os preços.

Leitura relacionada: Para padrões de integração específicos para ERP incluindo Salesforce e SAP, consulte o nosso guia de integração API, webhooks e ERP. Se está avaliando se deve construir validação internamente ou utilizar uma API como esta, a nossa análise construir vs. comprar fornece uma comparação detalhada de custos a 3 anos.

Para uma visão completa, consulte nosso guia completo verificação documentos.

Perguntas Frequentes

Como funciona a autenticação na API de validação documental?

A API suporta dois modelos de autenticação: chave API para integrações servidor-a-servidor, passada no cabeçalho X-API-Key, e OAuth 2.0 com fluxo de código de autorização para aplicações multi-tenant que atuam em nome de usuários finais. As chaves com prefixo ck_test_ acessam o ambiente sandbox para desenvolvimento e testes, enquanto as chaves ck_live_ acessam o ambiente de produção, e todo o tráfego é criptografado com TLS 1.3 independentemente do modelo utilizado.

Qual a diferença entre polling e webhooks para receber resultados de validação?

O polling consiste em consultar periodicamente o endpoint de status do documento até o processamento estar completo, sendo adequado para integrações simples ou protótipos, mas introduzindo latência e consumindo limites de taxa. Os webhooks invertem o fluxo: a API notifica automaticamente o sistema configurado assim que o processamento termina, entregando os resultados em quase tempo real sem consultas ativas, representando a abordagem recomendada para sistemas em produção e pipelines automatizados de conformidade.

Quanto tempo demora para processar um dossiê completo via API?

O tempo de processamento depende da complexidade do dossiê: um documento de identidade único processa em 2,1 segundos na mediana (4,8s no P95), um dossiê padrão de 8 a 12 documentos com o conjunto de regras de leasing de equipamentos leva 12 segundos na mediana (28s no P95), e um lote de 100 dossiês completos (800 a 1.200 documentos) processa em cerca de 8 minutos. Esses tempos incluem OCR, classificação, verificação cruzada e aplicação das regras de conformidade configuradas.

Como deve ser feito o tratamento de erros numa integração de produção?

O tratamento robusto de erros é obrigatório em sistemas de conformidade porque cada tentativa falhada deve ser registrada para efeitos de auditoria ao abrigo da LGPD. Os erros transitórios (códigos 5xx e timeouts) devem ser retentados com backoff exponencial, os erros 429 de limite de taxa devem ser gerenciados respeitando o cabeçalho Retry-After, e os endpoints de webhook devem ser idempotentes pois a API pode reenviar o mesmo evento em caso de timeout de rede, utilizando o campo file_id como chave de idempotência para evitar processar o mesmo resultado duas vezes.

Nossos dados de mais de 180.000 documentos processados mensalmente confirmam um tempo médio de verificação de 4,2 segundos e uma disponibilidade de 99,97%.

---

Passe à ação

O CheckFile verifica 180.000 documentos por mês com 98,7% de precisão OCR. Teste a plataforma com os seus próprios documentos — resultados em 48h.

Solicitar um piloto gratuito