API de verificação documental: guia de integração completo

Uma API de verificação documental é uma interface programática que permite aos desenvolvedores enviar documentos de identidade, notas fiscais, certificados ou comprovantes de endereço e receber resultados de verificação estruturados — controles de autenticidade, extração de dados, sinais de fraude — sem construir os modelos de IA subjacentes. A API da CheckFile processa um documento em 4,2 segundos em média, alcança 98,7% de precisão OCR em 24 idiomas e suporta mais de 3.200 tipos de documentos em 32 jurisdições, incluindo CPF, CNH, CNPJ e certidões brasileiras.

O Regulamento Europeu de IA (Regulamento (UE) 2024/1689, art. 6 e anexo III) classifica os sistemas de IA utilizados para verificação de documentos de identidade nos serviços financeiros como de alto risco. No Brasil, a Lei de IA (PL 2.338/2023), em tramitação, adota classificação similar. Qualquer API que você integre deve cumprir essas obrigações — caso contrário, herda a lacuna de conformidade.

Este guia abrange autenticação, endpoints principais, configuração de webhooks, gestão de erros, opções de SDK e preços. Destina-se a desenvolvedores backend, equipes DevOps e responsáveis técnicos que avaliam APIs de verificação documental para integração em produção.

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

Autenticação e segurança

A API da CheckFile utiliza OAuth 2.0 client credentials para autenticação máquina a máquina, em conformidade com o RFC 6749, Seção 4.4. Você troca o client_id e client_secret por um token bearer de duração limitada (validade de 60 minutos), que é incluído no header Authorization de cada requisição subsequente.

Todo o tráfego da API é criptografado com TLS 1.3. Os documentos são criptografados em repouso com AES-256 e os dados pessoais são automaticamente removidos dos logs, em conformidade com o artigo 46 da LGPD sobre medidas de segurança técnicas adequadas (LGPD — Lei 13.709/2018).

# Obter token de acesso
curl -X POST https://api.checkfile.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=SEU_ID&client_secret=SEU_SECRET"

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

Funcionalidades de segurança principais:

• Lista de IPs permitidos — restringir o acesso à API a IPs de servidor conhecidos
• Limitação de taxa — configurável por plano (ver seção de preços)
• Assinaturas de webhook — verificação HMAC-SHA256 em cada callback
• Registro de auditoria — cada chamada à API é registrada com carimbo de data/hora, ID do cliente, tipo de documento e resultado

Scopes e permissões

Endpoints principais

A API segue convenções RESTful com payloads JSON. URL base: https://api.checkfile.ai/v1.

Envio de documento

POST /v1/documents/verify
Content-Type: multipart/form-data
Authorization: Bearer {token}

# Campos:
# file (obrigatório) — imagem ou PDF do documento (máx. 20 MB)
# document_type (opcional) — "passport", "id_card", "invoice", "proof_of_address"
# country (opcional) — código ISO 3166-1 alfa-2 (ex: "BR")
# webhook_url (opcional) — URL de callback para resultados assíncronos
# reference_id (opcional) — sua referência interna para correlação

Resposta (HTTP 202 Accepted):

{
  "document_id": "doc_8f3a2b1c",
  "status": "processing",
  "estimated_completion_seconds": 4,
  "created_at": "2026-03-24T10:15:00Z"
}

Quando document_type é omitido, a API utiliza seu motor de classificação IA — que alcança 96,1% de precisão no nosso benchmark de mais de 3.200 tipos de documentos — para detectar o tipo automaticamente. Isso inclui documentos brasileiros como CPF, CNH, CNPJ, certidões de nascimento/casamento e comprovantes de endereço.

Obtenção de resultados

GET /v1/documents/{document_id}
Authorization: Bearer {token}

Resposta (HTTP 200):

{
  "document_id": "doc_8f3a2b1c",
  "status": "completed",
  "document_type": "cnh",
  "country": "BR",
  "verification": {
    "authentic": true,
    "confidence": 0.97,
    "fraud_signals": [],
    "checks": {
      "mrz_valid": true,
      "photo_tamper": false,
      "expiry_valid": true,
      "data_consistency": true
    }
  },
  "extracted_data": {
    "full_name": "Maria Silva Santos",
    "date_of_birth": "1990-05-12",
    "document_number": "12345678901",
    "expiry_date": "2031-05-11",
    "cpf": "123.456.789-01"
  },
  "processing_time_ms": 3840,
  "created_at": "2026-03-24T10:15:00Z",
  "completed_at": "2026-03-24T10:15:03.840Z"
}

O objeto extracted_data alcança 94,3% de precisão na extração de campos no nosso benchmark interno, cobrindo campos estruturados de todos os tipos de documentos suportados.

Verificação em lote

Para integrações de alto volume, o endpoint batch aceita até 50 documentos por requisição:

POST /v1/documents/verify/batch
Content-Type: multipart/form-data
Authorization: Bearer {token}

# files[] — array de arquivos de documentos
# options — objeto JSON com configurações compartilhadas

As requisições batch retornam um batch_id e entregam resultados via webhook à medida que cada documento é processado.

Configuração de webhooks

As arquiteturas orientadas a eventos evitam a sobrecarga do polling. Registre um endpoint webhook para receber notificações em tempo real quando as verificações forem concluídas.

POST /v1/webhooks
Authorization: Bearer {token}
Content-Type: application/json

{
  "url": "https://sua-app.com.br/webhooks/checkfile",
  "events": ["document.completed", "document.failed", "document.review_required"],
  "secret": "whsec_sua_chave_secreta"
}

Cada entrega de webhook inclui um header X-CheckFile-Signature com um hash HMAC-SHA256 do payload. Verifique-o antes de processar:

import hmac
import hashlib

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

Política de retry do webhook: 3 tentativas com backoff exponencial (5s, 30s, 300s). Após 3 falhas, o webhook é desativado e sua equipe recebe um alerta por email.

SDKs e opções de integração

A API REST funciona a partir de qualquer linguagem, mas os SDKs oficiais reduzem o tempo de integração de dias para horas.

SDKs disponíveis

Exemplo de integração em Python

from checkfile import CheckFileClient

client = CheckFileClient(
    client_id="SEU_CLIENT_ID",
    client_secret="SEU_CLIENT_SECRET"
)

# Verificação síncrona
result = client.documents.verify(
    file=open("cnh.pdf", "rb"),
    document_type="id_card",
    country="BR"
)

print(f"Autêntico: {result.verification.authentic}")
print(f"Nome: {result.extracted_data.full_name}")
print(f"Tempo de processamento: {result.processing_time_ms}ms")

Exemplo de integração em Node.js

import { CheckFileClient } from '@checkfile/sdk';
import { readFileSync } from 'fs';

const client = new CheckFileClient({
  clientId: process.env.CHECKFILE_CLIENT_ID,
  clientSecret: process.env.CHECKFILE_CLIENT_SECRET,
});

const result = await client.documents.verify({
  file: readFileSync('cnh.pdf'),
  documentType: 'id_card',
  country: 'BR',
});

console.log(`Autêntico: ${result.verification.authentic}`);
console.log(`Confiança: ${result.verification.confidence}`);

Os SDKs gerenciam a renovação de tokens, os retries com backoff exponencial e a verificação de assinaturas de webhook automaticamente. Nossa análise mostra que as integrações baseadas em SDK reduzem o tempo mediano de colocação em produção de 8 dias (REST direto) para 2 dias.

Gestão de erros e limites de taxa

A API utiliza códigos HTTP padrão com corpos de erro estruturados:

{
  "error": {
    "code": "DOCUMENT_UNREADABLE",
    "message": "O arquivo enviado não pôde ser analisado. Certifique-se de que DPI >= 300.",
    "details": { "min_dpi": 300, "detected_dpi": 72 },
    "request_id": "req_9f2c4d1e"
  }
}

Códigos de erro comuns

Limites de taxa por plano

Os headers de limite de taxa (X-RateLimit-Remaining, X-RateLimit-Reset) são incluídos em cada resposta. Construa sua lógica de retry com base nesses headers em vez de codificar delays fixos.

Conformidade e tratamento de dados

A verificação documental envolve dados pessoais em múltiplas jurisdições. A API é concebida com a conformidade como requisito de primeira ordem.

A LGPD (Lei 13.709/2018, art. 46) exige que os agentes de tratamento adotem medidas de segurança, técnicas e administrativas aptas a proteger os dados pessoais. O artigo 26 exige que o compartilhamento de dados pelo poder público atenda a finalidades específicas de políticas públicas. A CheckFile atua como operador de dados, com um contrato de tratamento de dados (DPA) incluído em todos os planos Business e Enterprise.

Em conformidade com as exigências do Banco Central do Brasil (Bacen) e da CVM (Comissão de Valores Mobiliários) para entidades sujeitas à Lei 9.613/1998 de prevenção à lavagem de dinheiro, a API fornece:

• Retenção: os documentos são eliminados após processamento, salvo solicitação explícita de armazenamento (configurável de 0 a 365 dias)
• Residência de dados: processamento na UE por padrão; regiões US e LATAM disponíveis nos planos Enterprise
• Trilha de auditoria: cada chamada à API gera um registro imutável com hash do documento, carimbo de data/hora, resultado e ID do cliente
• Certificação SOC 2 Type II cobrindo a infraestrutura da API
• Conformidade PCI DSS para o tratamento de documentos financeiros

Para integrações sujeitas às exigências de terceirização do Bacen (Resolução CMN 4.893/2021), a CheckFile fornece a documentação de garantias de terceiros exigida, resultados de testes de continuidade de negócio e condições de estratégia de saída.

Estrutura de preços

A CheckFile utiliza um modelo de preço por documento com descontos por volume. Todos os planos incluem acesso completo à API, webhooks e registros de auditoria.

Consulte a página de preços para detalhes sobre faixas de volume, descontos anuais e condições SLA Enterprise.

Nossa análise de plataforma mostra que as organizações que migram da verificação manual de documentos para a verificação via API reduzem o custo por processo em 67% e o tempo de processamento em 83%. O período médio de retorno do investimento para clientes Business é inferior a 3 meses ao processar mais de 500 documentos por mês.

Padrões de arquitetura de integração

Padrão 1: síncrono (simples)

Para integrações de baixo volume (< 60 requisições/min), enviar e consultar:

Cliente -> POST /v1/documents/verify -> 202 Accepted
Cliente -> GET /v1/documents/{id} (polling a cada 2s) -> 200 com resultados

Adequado para fluxos de onboarding onde o usuário aguarda a verificação.

Padrão 2: assíncrono com webhooks (recomendado)

Para cargas de trabalho em produção, enviar e receber resultados via webhook:

Cliente -> POST /v1/documents/verify (com webhook_url) -> 202 Accepted
CheckFile -> POST webhook_url (payload assinado) -> Seu handler processa o resultado

Desacopla o envio do processamento. Escala linearmente com o volume.

Padrão 3: pipeline em lote

Para processamento de back-office (revisões KYC noturnas, verificações de conformidade em massa):

Cliente -> POST /v1/documents/verify/batch (até 50 arquivos) -> batch_id
CheckFile -> POST webhook_url por documento à medida que é concluído
CheckFile -> POST webhook_url com resumo batch.completed

Nossa plataforma processa mais de 180.000 documentos por mês utilizando esses padrões. O padrão assíncrono com webhooks cobre 94% das integrações em produção.

Primeiros passos

A integração segue quatro etapas:

1. Criar uma conta em checkfile.ai e gerar credenciais API a partir do painel
2. Testar em sandbox — o ambiente sandbox replica a produção com documentos sintéticos (sem cobrança)
3. Integrar utilizando o SDK ou chamadas REST diretas, começando pelo padrão síncrono
4. Ir para produção — trocar para credenciais de produção e configurar webhooks

A documentação da API inclui um playground interativo para testar endpoints, e a página de preços detalha as opções de plano para o seu volume previsto.

Para equipes que constroem fluxos automatizados de verificação documental, a API se integra diretamente com os padrões descritos no nosso guia de configuração de workflows. Se você está avaliando soluções de verificação de forma mais abrangente, nosso guia de automatização da verificação cobre todo o panorama das abordagens de verificação documental.

Perguntas frequentes

Que tipos de documentos a API suporta?

A API da CheckFile suporta mais de 3.200 tipos de documentos em 32 jurisdições: passaportes, CNH (Carteira Nacional de Habilitação), RG, CPF, CNPJ, notas fiscais eletrônicas (NF-e), extratos bancários, comprovantes de endereço, certidões da Junta Comercial e declarações de Imposto de Renda. O motor de classificação IA identifica automaticamente o tipo de documento com 96,1% de precisão quando o parâmetro document_type é omitido.

Quanto tempo leva a verificação?

O tempo médio de processamento é de 4,2 segundos por documento. A latência P95 é inferior a 12 segundos para tipos de documentos padrão. Os envios em lote processam documentos em paralelo — um lote de 50 documentos é tipicamente concluído em 30 a 60 segundos, dependendo da complexidade do documento.

A API está em conformidade com a LGPD?

Sim. A CheckFile atua como operador nos termos do artigo 5º, VII da LGPD com DPA assinado, infraestrutura de processamento na UE, retenção de dados configurável (0 a 365 dias) e remoção automática de dados pessoais dos logs. As certificações SOC 2 Type II e ISO 27001 cobrem a infraestrutura da API. A API também atende aos requisitos do Bacen para terceirização de serviços de tecnologia.

Posso testar a API antes de contratar um plano pago?

O plano Starter inclui 100 verificações gratuitas por mês, e o ambiente sandbox permite testes ilimitados com documentos sintéticos sem custos. Não é necessário cartão de crédito para começar.

O que acontece se a API não conseguir verificar um documento?

Os documentos que ficam abaixo do limiar de confiança são sinalizados com o status review_required e encaminhados para sua fila de revisão humana via webhook. A resposta inclui o resultado parcial com a pontuação de confiança, os dados extraídos e os sinais de fraude específicos que acionaram a sinalização. Isso garante que nenhum documento fique sem processamento.