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

Uma API de verificação documental é uma interface programática que permite aos desenvolvedores submeter documentos de identidade, faturas, certificados ou comprovativos de morada e receber resultados de verificação estruturados — controlos 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, atinge 98,7 % de precisão OCR em 24 línguas e suporta mais de 3 200 tipos de documentos em 32 jurisdições.

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, exigindo que os fornecedores mantenham documentação técnica, um sistema de gestão de riscos e capacidades de supervisão humana. Qualquer API que integre deve cumprir estas 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, equipas 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 regulamentar.

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, Secção 4.4. Troca-se o client_id e client_secret por um token bearer de duração limitada (validade de 60 minutos), que é incluído no cabeçalho Authorization de cada pedido subsequente.

Todo o tráfego da API é encriptado com TLS 1.3. Os documentos são encriptados em repouso com AES-256 e os dados pessoais são automaticamente removidos dos registos, em conformidade com o artigo 32.o do RGPD sobre medidas técnicas adequadas (RGPD, art. 32).

 # 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 secção de preços)
• Assinaturas de webhook — verificação HMAC-SHA256 em cada callback
• Registo de auditoria — cada chamada à API é registada com carimbo temporal, 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.

Submissão 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
 # webhook_url (opcional) — URL de callback para resultados assíncronos
 # reference_id (opcional) — a 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-19T10:15:00Z"
}

Quando document_type é omitido, a API utiliza o seu motor de classificação IA — que atinge 96,1 % de precisão no nosso benchmark de mais de 3 200 tipos de documentos — para detetar o tipo automaticamente.

Obtenção de resultados

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

Resposta (HTTP 200):

{
  "document_id": "doc_8f3a2b1c",
  "status": "completed",
  "document_type": "cartao_cidadao",
  "country": "PT",
  "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": "12345678",
    "expiry_date": "2031-05-11",
    "nationality": "PRT"
  },
  "processing_time_ms": 3840,
  "created_at": "2026-03-19T10:15:00Z",
  "completed_at": "2026-03-19T10:15:03.840Z"
}

O objeto extracted_data atinge 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 pedido:

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

 # files[] — array de ficheiros de documentos
 # options — objeto JSON com definições partilhadas

Os pedidos batch devolvem um batch_id e entregam resultados por webhook à medida que cada documento é processado.

Configuração de webhooks

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

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

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

Cada entrega de webhook inclui um cabeçalho 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 repetição do webhook: 3 tentativas com backoff exponencial (5s, 30s, 300s). Após 3 falhas, o webhook é desativado e a sua equipa 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("cartao_cidadao.pdf", "rb"),
    document_type="id_card",
    country="PT"
)

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('cartao_cidadao.pdf'),
  documentType: 'id_card',
  country: 'PT',
});

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

Os SDKs gerem a renovação de tokens, as repetições com backoff exponencial e a verificação de assinaturas de webhook automaticamente. A 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 ficheiro carregado 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 cabeçalhos de limite de taxa (X-RateLimit-Remaining, X-RateLimit-Reset) são incluídos em cada resposta. Construa a sua lógica de repetição com base nestes cabeçalhos em vez de codificar atrasos 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.

Desde março de 2026, o RGPD (Regulamento (UE) 2016/679, art. 28) exige que os responsáveis pelo tratamento recorram apenas a subcontratantes que apresentem garantias suficientes de medidas técnicas e organizativas adequadas. A CheckFile atua como subcontratante, com um contrato de subcontratação (DPA) incluído em todos os planos Business e Enterprise.

Em conformidade com as exigências do Banco de Portugal e da CMVM (Comissão do Mercado de Valores Mobiliários) para entidades sujeitas à Lei n.o 83/2017 de prevenção do branqueamento de capitais, a API fornece:

• Retenção: os documentos são eliminados após processamento salvo pedido explícito de armazenamento (configurável de 0 a 365 dias)
• Residência de dados: processamento na UE por defeito; regiões US e APAC disponíveis nos planos Enterprise
• Trilho de auditoria: cada chamada à API gera um registo imutável com hash do documento, carimbo temporal, resultado e ID do cliente
• Certificação SOC 2 Type II que cobre a infraestrutura da API
• Conformidade PCI DSS para o tratamento de documentos financeiros

Para integrações sujeitas às orientações do Banco de Portugal sobre externalização de serviços, 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 registos de auditoria.

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

A nossa análise de plataforma mostra que as organizações que transitam da verificação manual de documentos para a verificação por 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 pedidos/min), submeter 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 utilizador aguarda a verificação.

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

Para cargas de trabalho em produção, submeter e receber resultados por webhook:

Cliente → POST /v1/documents/verify (com webhook_url) → 202 Accepted
CheckFile → POST webhook_url (payload assinado) → O seu handler processa o resultado

Desacopla a submissão do processamento. Escala linearmente com o volume.

Padrão 3: pipeline em lote

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

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

A nossa plataforma processa mais de 180.000 documentos por mês utilizando estes 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 faturação)
3. Integrar utilizando o SDK ou chamadas REST diretas, começando pelo padrão síncrono
4. Passar a produção — mudar 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 equipas que constroem fluxos automatizados de verificação documental, a API integra-se diretamente com os padrões descritos no nosso guia de configuração de workflows. Se está a avaliar soluções de verificação de forma mais abrangente, o 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, cartões de cidadão, cartas de condução, faturas, extratos bancários, comprovativos de morada, notas de liquidação de IRS, recibos de vencimento e certidões de registo comercial. 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 demora 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. As submissões 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 é conforme ao RGPD?

Sim. A CheckFile atua como subcontratante nos termos do artigo 28.o do RGPD 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 registos. As certificações SOC 2 Type II e ISO 27001 cobrem a infraestrutura da API.

Posso testar a API antes de subscrever 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 estado review_required e encaminhados para a 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. Isto garante que nenhum documento fica sem processamento.