Validacao Documental: API, Webhooks e ERP

A validacao documental integrada num ERP ou CRM reduz em 40 a 60% o tempo de processamento de dossiers em comparacao com ferramentas autonomas, segundo estimativas de projetos de integracao documentados. Quando um operador carrega manualmente ficheiros para uma ferramenta autonoma, copia os resultados para um CRM e depois atualiza um ERP, cada passo introduz atraso, risco de erro e rastos de auditoria quebrados. Para organizacoes que processam centenas de dossiers por mes, este fluxo manual torna-se um verdadeiro estrangulamento.

Este artigo detalha tres padroes de integracao que ligam a CheckFile diretamente ao seu sistema de informacao -- seja Salesforce, SAP, um CRM personalizado ou um motor de fluxos de trabalho interno. Encontrara diagramas de arquitetura, exemplos de codigo funcionais e boas praticas baseadas em implementacoes reais. Se procura primeiro a referencia dos endpoints, consulte o guia de API.

Porque a validacao documental nao pode permanecer uma ferramenta isolada

Uma ferramenta de validacao isolada cria tres problemas estruturais: disrupcao do fluxo de trabalho, rastos de auditoria quebrados e erros de transcricao. O Regulamento (UE) 2024/1624 (AMLR), aplicavel a partir de julho de 2027, exige explicitamente que as entidades obrigadas mantenham registos de diligencia devida integralmente ligados aos registos dos clientes nos sistemas internos.

O Banco de Portugal, na Instrucao n.o 8/2024, estabelece que as entidades financeiras devem reportar anualmente os seus procedimentos de prevencao do branqueamento de capitais, incluindo a descricao dos sistemas tecnologicos utilizados na verificacao documental -- uma exigencia que pressupoe integracao documentada entre sistemas (Banco de Portugal, Instrucao 8/2024).

Disrupcao do fluxo de trabalho. O operador abandona o seu ambiente primario (CRM, ERP, portal interno) para utilizar uma ferramenta separada. Cada ida e volta custa 2 a 5 minutos por dossier. A 500 dossiers por mes, isto soma 25 a 40 horas perdidas.

Rastos de auditoria quebrados. Os resultados de validacao nao estao ligados ao registo do cliente no sistema de referencia. Durante uma auditoria, a cadeia deve ser reconstruida manualmente.

Erros de transcricao. Quando um operador copia manualmente o estado de um documento do validador para o CRM, a taxa de erro situa-se entre 2 e 5 por cento. A 10.000 dossiers por ano, isto significa 200 a 500 registos com estado inconsistente.

A integracao direta elimina os tres problemas.

Tres padroes de integracao

Existem tres padroes de integracao principais, cada um adequado a um perfil de volume e latencia diferente. O padrao correto depende do volume de documentos, da latencia aceitavel e da maturidade tecnica da equipa.

O FATF, nas suas Recomendacoes de 2023 sobre abordagem baseada no risco, refere que a integracao de ferramentas de verificacao documental nos sistemas de gestao de clientes e um indicador de maturidade do programa de conformidade -- entidades com integracoes sistematizadas apresentam taxas de detecao de anomalias 35% superiores (FATF-GAFI, Recommendations 2023).

Padrao 1 -- Upload em lote

O upload em lote adequa-se quando a latencia nao e critica: migrar um arquivo documental, reprocessamento periodico, ou alimentacao noturna de data warehouse.

# Carregar um lote de 3 documentos
curl -X POST https://api.checkfile.ai/api/v1/files/batch \
  -H "X-API-Key: ck_live_your_key" \
  -F "files[]=@fatura_001.pdf" \
  -F "files[]=@certidao_permanente.pdf" \
  -F "files[]=@dados_bancarios.pdf" \
  -F "dossier_id=DOS-2026-0042" \
  -F "callback_url=https://your-app.com/webhooks/checkfile"

O servidor retorna um identificador de lote imediatamente:

{
  "batch_id": "bat_7f3a9c2e",
  "file_count": 3,
  "status": "queued",
  "estimated_completion": "2026-02-21T14:35:00Z"
}

Padrao 2 -- API em tempo real

O padrao mais comum para aplicacoes interativas: um utilizador carrega um documento, a sua aplicacao envia-o para a CheckFile, aguarda o resultado e apresenta-o. A referencia completa dos endpoints esta coberta no guia de API.

# Carregar um documento individual
curl -X POST https://api.checkfile.ai/api/v1/files \
  -H "X-API-Key: ck_live_your_key" \
  -H "Idempotency-Key: upload-dos042-certidao" \
  -F "file=@certidao_permanente.pdf" \
  -F "document_type=company_registration" \
  -F "rules=freshness_90d,company_number_match"

Padrao 3 -- Webhooks orientados a eventos

Os webhooks invertem o fluxo: em vez de consultar a API, a CheckFile notifica o seu sistema assim que o processamento termina. Este e o padrao recomendado para pipelines automatizados e integracoes ERP.

Arquitetura de webhooks em detalhe

Registar um endpoint de webhook

curl -X POST https://api.checkfile.ai/api/v1/webhooks \
  -H "X-API-Key: ck_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/checkfile",
    "events": ["file.validated", "file.rejected", "batch.completed"],
    "secret": "whsec_your_signing_secret"
  }'

Payload do webhook: documento validado

Quando um documento passa todas as regras de validacao, a CheckFile envia um POST para o seu endpoint com o seguinte payload:

{
  "event": "file.validated",
  "timestamp": "2026-02-21T14:22:18Z",
  "data": {
    "file_id": "fil_8b2c4d1e",
    "dossier_id": "DOS-2026-0042",
    "document_type": "company_registration",
    "status": "validated",
    "confidence_score": 0.97,
    "extracted_fields": {
      "company_name": "ACME Industria Lda",
      "company_number": "514123456",
      "incorporation_date": "2019-03-15",
      "registered_address": "Rua Augusta 42, 1100-053 Lisboa",
      "director": "Maria Santos",
      "document_date": "2026-01-28"
    },
    "rules_results": [
      {
        "rule": "freshness_90d",
        "status": "passed",
        "detail": "Documento datado de 28/01/2026, valido ate 28/04/2026"
      },
      {
        "rule": "company_number_match",
        "status": "passed",
        "detail": "NIPC 514123456 corresponde ao registo do dossier"
      }
    ],
    "processing_time_ms": 3420
  }
}

Tratar o webhook em Python

from flask import Flask, request, abort
import hmac
import hashlib

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_your_signing_secret"

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

@app.route("/webhooks/checkfile", methods=["POST"])
def handle_webhook():
    # 1. Verificar assinatura
    signature = request.headers.get("X-CheckFile-Signature", "")
    if not verify_signature(request.data, signature):
        abort(401)

    event = request.json
    event_type = event["event"]
    data = event["data"]

    # 2. Encaminhar por tipo de evento
    if event_type == "file.validated":
        update_crm_document_status(
            dossier_id=data["dossier_id"],
            document_type=data["document_type"],
            status="validated",
            extracted_fields=data["extracted_fields"]
        )
    elif event_type == "file.rejected":
        trigger_operator_alert(
            dossier_id=data["dossier_id"],
            reasons=data["rejection_reasons"]
        )
    elif event_type == "batch.completed":
        finalize_dossier(data["batch_id"])

    # 3. Responder 200 rapidamente
    return {"received": True}, 200

Tratar o webhook em Node.js

const express = require("express");
const crypto = require("crypto");

const app = express();
const WEBHOOK_SECRET = "whsec_your_signing_secret";

app.post("/webhooks/checkfile", express.raw({ type: "application/json" }), (req, res) => {
  // Verificar assinatura
  const signature = req.headers["x-checkfile-signature"] || "";
  const expected = `sha256=${crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex")}`;

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send("Assinatura invalida");
  }

  const event = JSON.parse(req.body);

  switch (event.event) {
    case "file.validated":
      updateCrmStatus(event.data);
      break;
    case "file.rejected":
      notifyOperator(event.data);
      break;
    case "batch.completed":
      finalizeDossier(event.data);
      break;
  }

  res.json({ received: true });
});

Padroes de integracao ERP por plataforma

Salesforce

A integracao Salesforce mais comum utiliza um Apex Trigger ou Flow acionado pelo webhook da CheckFile.

SAP

Para SAP S/4HANA ou SAP Business One, duas abordagens coexistem:

Via SAP Integration Suite. Um iFlow recebe o webhook, transforma o payload em IDoc ou entidade OData e injeta-o no SAP. Abordagem preferida pelas equipas SAP Basis.

Via middleware generico. Um conector Python ou Node.js recebe o webhook e chama a API OData do SAP diretamente. Mais rapido de configurar.

CRM personalizado ou ferramenta interna

Para ferramentas internas, o webhook e o metodo mais direto. O seu backend recebe o payload, extrai campos relevantes e atualiza a sua base de dados.

Autenticacao e seguranca

A seguranca das integracao API e um requisito regulamentar: o RGPD (Regulamento (UE) 2016/679, artigo 32.o) obriga as entidades a implementar medidas tecnicas adequadas para proteger dados pessoais em transito e em repouso. As chaves API devem ser geridas como segredos.

Boas praticas para chaves API

• Uma chave por ambiente. Desenvolvimento (ck_test_), staging, producao (ck_live_). Nunca partilhar uma chave entre ambientes.
• Rotacao regular. Rodar chaves a cada 90 dias. A API suporta duas chaves ativas simultaneamente para rotacao sem tempo de inatividade.
• Armazenamento seguro. Utilizar Vault (HashiCorp), AWS Secrets Manager ou Azure Key Vault. Nunca armazenar chaves em texto plano no codigo-fonte.

Verificacao de webhooks

Cada webhook e assinado com o seu segredo (whsec_...). Verificar sempre a assinatura HMAC-SHA256 antes de processar o payload.

Tratamento de erros e estrategias de retry

Erros transitorios (5xx, timeout)

A CheckFile retenta automaticamente webhooks em caso de falha. O calendario de retry segue backoff exponencial:

Idempotencia

O seu endpoint de webhook deve ser idempotente. A CheckFile pode reenviar o mesmo evento em caso de timeout de rede. Utilizar o campo file_id como chave de idempotencia.

Monitorizacao e observabilidade

Metricas operacionais

• Taxa de sucesso de webhooks: percentagem de webhooks recebidos e processados sem erro. Alvo: > 99,5%.
• Latencia de processamento: tempo entre upload e entrega do webhook. Alvo: < 15 segundos para 95% dos documentos.
• Taxa de rejeicao de documentos: se esta taxa excede 30%, sinaliza um problema de qualidade nos documentos submetidos a montante.

Percurso de migracao: de upload manual a pipeline totalmente automatizado

Fase 1 -- Interface web (semana 1). Utilizar o dashboard da CheckFile para validar os primeiros documentos manualmente.

Fase 2 -- API em tempo real (semanas 2-3). Integrar a API de upload na sua aplicacao. Os operadores ja nao abandonam a sua ferramenta principal.

Fase 3 -- Webhooks (semanas 4-5). Ativar webhooks para receber resultados automaticamente. O CRM/ERP e atualizado sem intervencao humana.

Fase 4 -- Pipeline totalmente automatizado (semanas 6-8). Documentos carregados automaticamente na rececao (parser de email, portal de cliente, scanner). Webhooks alimentam o ERP. Operadores tratam apenas excecoes.

Em cada fase, pode medir as poupancas de tempo e a reducao da taxa de erro para justificar o investimento na fase seguinte. Se esta a ponderar construir a sua propria solucao de validacao ou utilizar uma plataforma existente, leia a nossa analise construir vs. comprar.

Conclusao: integracao como multiplicador de produtividade

A validacao documental so entrega o seu valor total quando e integrada no fluxo de trabalho existente. Uma API REST bem concebida, webhooks fiaveis e padroes de integracao adaptados ao seu ERP transformam uma ferramenta de verificacao numa componente nativa do seu sistema de informacao.

Pronto para ligar a validacao documental ao seu sistema de TI? Explore a documentacao API da CheckFile ou contacte a nossa equipa tecnica para orientacao personalizada. Os precos incluem acesso API em todos os planos, com um ambiente sandbox para testar a sua integracao antes de entrar em producao.

Perguntas Frequentes

Por que razao e prejudicial manter a validacao documental como uma ferramenta isolada do CRM ou ERP?

Uma ferramenta de validacao isolada cria tres problemas estruturais: o operador perde 2 a 5 minutos por dossier cada vez que abandona o seu ambiente primario para utilizar a ferramenta separada, os resultados de validacao nao ficam ligados ao registo do cliente no sistema de referencia criando rastos de auditoria quebrados, e a transcricao manual dos estados de documentos do validador para o CRM gera uma taxa de erro de 2% a 5%, o que representa 200 a 500 registos com estado inconsistente para organizacoes com 10.000 dossiers anuais.

Qual e o padrao de integracao mais adequado para um pipeline automatizado de conformidade?

Os webhooks orientados a eventos sao o padrao recomendado para pipelines automatizados e integracoes ERP, porque invertem o fluxo de informacao: em vez de o sistema consultar periodicamente a API, a plataforma de validacao notifica automaticamente o sistema assim que o processamento termina. Esta abordagem elimina a latencia do polling, consome menos recursos, e permite que o CRM ou ERP seja atualizado em quase tempo real sem qualquer intervencao humana para os documentos que passam todas as verificacoes.

Como integrar a validacao documental com o Salesforce?

A integracao Salesforce mais comum utiliza um componente intermediario (Lambda ou Cloud Function) que recebe e valida o payload de webhook da plataforma de validacao, ligado ao Salesforce via OAuth 2.0 e Connected App para escrever nos objetos relevantes. A camada de automacao do Salesforce, via Salesforce Flow ou Apex Trigger, deteta as atualizacoes nos objetos e aciona a logica de negocio subsequente, como avancar um dossier no pipeline ou notificar o gestor de conta.

Quais as boas praticas para gerir chaves API de forma segura numa integracao de producao?

As chaves API devem ser tratadas como segredos e nunca armazenadas em texto plano no codigo-fonte ou em variaveis de ambiente nao protegidas. As boas praticas incluem utilizar uma chave diferente por ambiente (desenvolvimento, staging e producao), armazenar as chaves em cofres de segredos como HashiCorp Vault, AWS Secrets Manager ou Azure Key Vault, rodar as chaves a cada 90 dias aproveitando o suporte a duas chaves ativas simultaneamente para rotacao sem tempo de inatividade, e nunca partilhar uma chave entre ambientes nem incluir chaves em repositorios de codigo.