API de Validacao Documental: Guia para Programadores

Este guia cobre tudo o que precisa para integrar validacao documental automatizada na sua aplicacao -- desde autenticacao ate tratamento de webhooks. Quer esteja a construir um fluxo de onboarding de clientes, um pipeline de conformidade, ou uma ferramenta de automatizacao de back-office, a API CheckFile da-lhe acesso programatico ao mesmo motor de validacao alimentado por IA utilizado na plataforma. Encontrara decisoes de arquitetura, referencia de endpoints, exemplos de codigo em Python e Node.js, payloads de webhooks, estrategias de tratamento de erros e padroes de integracao que escalam do prototipo a producao.

Visao Geral da Arquitetura

A API CheckFile segue um modelo de processamento assincrono padrao REST, com uploads via POST /v1/files, processamento em fila e entrega de resultados por polling ou webhook. O Regulamento (UE) 2024/1624 (AMLR), aplicavel a partir de julho de 2027, exige que os sistemas de verificacao documental utilizados por entidades obrigadas produzam rastos de auditoria deterministicos e auditaveis -- um requisito nativo na arquitetura da CheckFile.

O Regulamento da IA da UE (Regulamento (UE) 2024/1689), aplicavel a partir de agosto de 2026, classifica os sistemas de avaliacao de risco documental como IA de risco limitado, impondo obrigacoes de transparencia e documentacao para fornecedores que integrem IA em fluxos de decisao (EUR-Lex, Regulamento IA). Os documentos sao carregados via REST, colocados em fila para analise por IA, e os resultados sao 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   |
    |                               | (validacao IA)  |
    |                               +--------+--------+
    |                                        |
    |         Callback de webhook            |
    |<---------------------------------------+
    |         POST seu-endpoint

Tres decisoes de design chave moldam esta arquitetura:

1. Assincrono por defeito. A validacao documental envolve OCR, detecao de fraude, cruzamento de referencias e avaliacao de regras. Estas operacoes demoram 2-15 segundos dependendo da complexidade do documento.

2. Entrega dual. Pode consultar o endpoint de estado ou registar um webhook. O polling funciona para integracoes simples; os webhooks sao a abordagem recomendada para sistemas em producao.

3. Uploads idempotentes. Cada upload retorna um file_id unico. Recarregar o mesmo documento com a mesma chave de idempotencia retorna o resultado existente.

Autenticacao e Seguranca

A autenticacao na API CheckFile suporta dois modelos: chave API para integracoes servidor-a-servidor, e OAuth 2.0 para acesso com ambito de utilizador em aplicacoes multi-tenant. Todo o trafego e cifrado com TLS 1.3, e os documentos sao cifrados em repouso com AES-256, em conformidade com o RGPD (Regulamento (UE) 2016/679, artigo 32.o).

O Banco de Portugal, na Instrucao n.o 8/2024 sobre requisitos de reporte em materia de prevencao do branqueamento de capitais, exige que os sistemas de verificacao documental integrados em processos de onboarding garantam rastreabilidade completa de cada verificacao, com carimbo temporal e identificacao do operador (Banco de Portugal, Instrucao 8/2024).

Autenticacao por Chave API

Para integracoes servidor-a-servidor, passe a sua chave API no cabecalho X-API-Key:

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

Chaves com prefixo ck_test_ acedem ao ambiente sandbox; chaves com prefixo ck_live_ acedem a producao.

OAuth 2.0 para Acesso com Ambito de Utilizador

Se a sua aplicacao atua em nome de utilizadores finais (ex.: um SaaS multi-tenant), utilize OAuth 2.0 com fluxo de codigo de autorizacao.

Limites de Taxa

Consulte os precos para detalhes dos planos.

Seguranca de Transporte

Todo o trafego e cifrado com TLS 1.3. Todos os documentos carregados sao cifrados em repouso com AES-256 e purgados automaticamente apos o periodo de retencao configurado. Consulte as nossas praticas de seguranca.

Endpoints Principais

Carregar 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: Carregar lote de documentos como dossier
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"Dossier carregado: {file_id}")

# Passo 2: Consultar estado
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']} (confianca: {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: Carregar 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(`Dossier carregado: ${fileId}`);

// Passo 2: Consultar estado
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} (confianca: ${doc.confidence})`);
  for (const alert of doc.alerts) {
    console.log(`  - ${alert.severity}: ${alert.message}`);
  }
}

Payloads de Webhook

Evento de Validacao Concluida

{
  "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 Detetado

{
  "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": "Certidao permanente expirada em 2025-11-30",
      "field": "validity_date",
      "extracted_value": "2025-11-30",
      "expected": "Documento deve ter menos de 3 meses"
    }
  }
}

Verificacao 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 codigos de erro da API CheckFile seguem o padrao HTTP RFC 9110. O tratamento robusto de erros e obrigatorio em sistemas de conformidade, onde cada tentativa falhada deve ser registada para efeitos de auditoria ao abrigo do RGPD (artigo 5.o, n.o 2).

O FATF, nas suas orientacoes de 2024 sobre abordagem baseada no risco para entidades obrigadas, recomenda que os sistemas automatizados de verificacao documental mantenham logs de auditoria completos, incluindo tentativas falhadas, por um periodo minimo de 5 anos (FATF, Risk-Based Approach Guidance).

Benchmarks de Desempenho

Comecar

O caminho mais rapido para uma integracao funcional:

1. Criar uma conta e gerar uma chave API de teste (ck_test_) no dashboard.
2. Carregar um documento de teste utilizando os exemplos curl ou os exemplos de codigo deste guia.
3. Registar um webhook para receber resultados assincronamente.
4. Configurar um conjunto de regras adequado aos seus requisitos de negocio.
5. Mudar para producao substituindo a chave de teste por uma chave de producao (ck_live_).

Documentacao completa dos endpoints, SDKs (Python, Node.js, Go) e explorador interativo da API estao disponiveis em docs.checkfile.ai. Se tem duvidas sobre que plano se adequa ao seu volume, consulte os precos.

Leitura relacionada: Para padroes de integracao especificos para ERP incluindo Salesforce e SAP, consulte o nosso guia de integracao API, webhooks e ERP. Se esta a avaliar se deve construir validacao internamente ou utilizar uma API como esta, a nossa analise construir vs. comprar fornece uma comparacao detalhada de custos a 3 anos.

Perguntas Frequentes

Como funciona a autenticacao na API de validacao documental?

A API suporta dois modelos de autenticacao: chave API para integracoes servidor-a-servidor, passada no cabecalho X-API-Key, e OAuth 2.0 com fluxo de codigo de autorizacao para aplicacoes multi-tenant que atuam em nome de utilizadores finais. As chaves com prefixo ck_test_ acedem ao ambiente sandbox para desenvolvimento e testes, enquanto as chaves ck_live_ acedem ao ambiente de producao, e todo o trafego e cifrado com TLS 1.3 independentemente do modelo utilizado.

Qual a diferenca entre polling e webhooks para receber resultados de validacao?

O polling consiste em consultar periodicamente o endpoint de estado do documento ate o processamento estar completo, adequando-se a integracoes simples ou prototipos, mas introduzindo latencia 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, e representam a abordagem recomendada para sistemas em producao e pipelines automatizados de conformidade.

Quanto tempo demora a processar um dossier completo via API?

O tempo de processamento depende da complexidade do dossier: um documento de identidade unico processa em 2,1 segundos no mediano (4,8s no P95), um dossier padrao de 8 a 12 documentos com o conjunto de regras de leasing de equipamentos demora 12 segundos no mediano (28s no P95), e um lote de 100 dossiers completos (800 a 1.200 documentos) processa em cerca de 8 minutos. Estes tempos incluem OCR, classificacao, verificacao cruzada e aplicacao das regras de conformidade configuradas.

Como deve ser feito o tratamento de erros numa integracao de producao?

O tratamento robusto de erros e obrigatorio em sistemas de conformidade porque cada tentativa falhada deve ser registada para efeitos de auditoria ao abrigo do RGPD. Os erros transitories (codigos 5xx e timeouts) devem ser retentados com backoff exponencial, os erros 429 de limite de taxa devem ser geridos respeitando o cabecalho 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 idempotencia para evitar processar o mesmo resultado duas vezes.