Validação documental: API, webhooks e ERP — guia

A validação documental integrada a um ERP ou CRM reduz em 40 a 60% o tempo de processamento de dossiês em comparação com ferramentas autônomas, segundo estimativas de projetos de integração documentados. Quando um operador faz upload manual de arquivos para uma ferramenta autônoma, copia os resultados para um CRM e depois atualiza um ERP, cada etapa introduz atraso, risco de erro e trilhas de auditoria quebradas. Para organizações que processam centenas de dossiês por mês, esse fluxo manual se torna um verdadeiro gargalo.

Este artigo detalha três padrões de integração que conectam a CheckFile diretamente ao seu sistema de informação — seja Salesforce, SAP, TOTVS, um CRM personalizado ou um motor de workflows interno. Você encontrará diagramas de arquitetura, exemplos de código funcionais e boas práticas baseadas em implementações reais. Se procura primeiro a referência dos endpoints, consulte o guia de API.

Por que a validação documental não pode continuar sendo uma ferramenta isolada

Uma ferramenta de validação isolada cria três problemas estruturais: disrupção do fluxo de trabalho, trilhas de auditoria quebradas e erros de transcrição. A Lei 9.613/1998, atualizada pela Lei 12.683/2012, exige que as entidades obrigadas mantenham registros de diligência devida integrados aos registros dos clientes nos sistemas internos.

O Bacen, na Circular 3.978/2020, estabelece que as instituições financeiras devem manter procedimentos documentados de PLD/FT, incluindo a descrição dos sistemas tecnológicos utilizados na verificação documental — uma exigência que pressupõe integração documentada entre sistemas.

Disrupção do fluxo de trabalho. O operador abandona seu ambiente primário (CRM, ERP, portal interno) para utilizar uma ferramenta separada. Cada ida e volta custa 2 a 5 minutos por dossiê. A 500 dossiês por mês, isso soma 25 a 40 horas perdidas.

Trilhas de auditoria quebradas. Os resultados de validação não estão vinculados ao registro do cliente no sistema de referência. Durante uma auditoria, a cadeia deve ser reconstruída manualmente.

Erros de transcrição. Quando um operador copia manualmente o status de um documento do validador para o CRM, a taxa de erro fica entre 2 e 5 por cento. A 10.000 dossiês por ano, isso significa 200 a 500 registros com status inconsistente.

A integração direta elimina os três problemas.

Três padrões de integração

Existem três padrões de integração principais, cada um adequado a um perfil de volume e latência diferente. O padrão correto depende do volume de documentos, da latência aceitável e da maturidade técnica da equipe.

O GAFI/FATF, nas suas Recomendações de 2023 sobre abordagem baseada no risco, aponta que a integração de ferramentas de verificação documental nos sistemas de gestão de clientes é um indicador de maturidade do programa de conformidade — entidades com integrações sistematizadas apresentam taxas de detecção de anomalias 35% superiores (FATF-GAFI, Recommendations 2023).

Padrão 1 — Upload em lote

O upload em lote é adequado quando a latência não é crítica: migrar um acervo documental, reprocessamento periódico ou alimentação noturna de data warehouse.

# Fazer upload de 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[]=@nota_fiscal_001.pdf" \
  -F "files[]=@certidao_simplificada.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"
}

Padrão 2 — API em tempo real

O padrão mais comum para aplicações interativas: um usuário faz upload de um documento, sua aplicação o envia para a CheckFile, aguarda o resultado e o apresenta. A referência completa dos endpoints está coberta no guia de API.

# Fazer upload de 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_simplificada.pdf" \
  -F "document_type=company_registration" \
  -F "rules=freshness_90d,company_number_match"

Padrão 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 é o padrão recomendado para pipelines automatizados e integrações ERP.

Arquitetura de webhooks em detalhe

Registrar 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 em todas as regras de validação, 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 Indústria Ltda",
      "company_number": "12.345.678/0001-99",
      "incorporation_date": "2019-03-15",
      "registered_address": "Av. Paulista, 1000 - Bela Vista, São Paulo - SP, 01310-100",
      "director": "Maria Santos",
      "document_date": "2026-01-28"
    },
    "rules_results": [
      {
        "rule": "freshness_90d",
        "status": "passed",
        "detail": "Documento datado de 28/01/2026, válido até 28/04/2026"
      },
      {
        "rule": "company_number_match",
        "status": "passed",
        "detail": "CNPJ 12.345.678/0001-99 corresponde ao registro do dossiê"
      }
    ],
    "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 inválida");
  }

  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 });
});

Padrões de integração ERP por plataforma

Salesforce

A integração 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 o injeta no SAP. Abordagem preferida pelas equipes SAP Basis.

Via middleware genérico. Um conector Python ou Node.js recebe o webhook e chama a API OData do SAP diretamente. Mais rápido de configurar.

TOTVS Protheus / TOTVS RAC

Para empresas brasileiras que utilizam TOTVS Protheus ou TOTVS RAC, a integração pode ser feita via API REST nativa do Protheus (endpoint /api/framework/v1) ou via TOTVS Fluig para orquestração de workflows documentais. O webhook da CheckFile alimenta diretamente o módulo de cadastro de fornecedores ou clientes.

CRM personalizado ou ferramenta interna

Para ferramentas internas, o webhook é o método mais direto. Seu backend recebe o payload, extrai campos relevantes e atualiza sua base de dados.

Autenticação e segurança

A segurança das integrações API é um requisito regulatório: a LGPD (Lei 13.709/2018) obriga as entidades a implementar medidas técnicas adequadas para proteger dados pessoais em trânsito e em repouso. As chaves API devem ser gerenciadas como segredos.

Boas práticas para chaves API

• Uma chave por ambiente. Desenvolvimento (ck_test_), staging, produção (ck_live_). Nunca compartilhar uma chave entre ambientes.
• Rotação regular. Trocar chaves a cada 90 dias. A API suporta duas chaves ativas simultaneamente para rotação sem tempo de inatividade.
• Armazenamento seguro. Utilizar Vault (HashiCorp), AWS Secrets Manager ou Azure Key Vault. Nunca armazenar chaves em texto plano no código-fonte.

Verificação de webhooks

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

Tratamento de erros e estratégias de retry

Erros transitórios (5xx, timeout)

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

Idempotência

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 idempotência.

Monitoramento e observabilidade

Métricas operacionais

• Taxa de sucesso de webhooks: porcentagem de webhooks recebidos e processados sem erro. Meta: > 99,5%.
• Latência de processamento: tempo entre upload e entrega do webhook. Meta: < 15 segundos para 95% dos documentos.
• Taxa de rejeição de documentos: se esta taxa excede 30%, sinaliza um problema de qualidade nos documentos submetidos a montante.

Caminho de migração: 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 aplicação. Os operadores não abandonam mais sua ferramenta principal.

Fase 3 — Webhooks (semanas 4-5). Ativar webhooks para receber resultados automaticamente. O CRM/ERP é atualizado sem intervenção humana.

Fase 4 — Pipeline totalmente automatizado (semanas 6-8). Documentos carregados automaticamente na recepção (parser de e-mail, portal de cliente, scanner). Webhooks alimentam o ERP. Operadores tratam apenas exceções.

Em cada fase, é possível medir as economias de tempo e a redução da taxa de erro para justificar o investimento na fase seguinte. Se está considerando construir sua própria solução de validação ou utilizar uma plataforma existente, leia a nossa análise construir vs. comprar.

Conclusão: integração como multiplicador de produtividade

A validação documental só entrega seu valor total quando é integrada ao fluxo de trabalho existente. Uma API REST bem projetada, webhooks confiáveis e padrões de integração adaptados ao seu ERP transformam uma ferramenta de verificação em um componente nativo do seu sistema de informação.

Pronto para conectar a validação documental ao seu sistema de TI? Explore a documentação API da CheckFile ou entre em contato com a nossa equipe técnica para orientação personalizada. Os preços incluem acesso API em todos os planos, com um ambiente sandbox para testar sua integração antes de entrar em produção.

Para uma visão completa, consulte nosso guia de automação de verificação documental.

Este artigo é fornecido apenas para fins informativos e não constitui aconselhamento jurídico, financeiro ou regulatório. Consulte um profissional qualificado para questões relativas à sua situação específica.

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

---

Perguntas frequentes

Por que é prejudicial manter a validação documental como uma ferramenta isolada do CRM ou ERP?

Uma ferramenta de validação isolada cria três problemas estruturais: o operador perde 2 a 5 minutos por dossiê cada vez que abandona seu ambiente primário para utilizar a ferramenta separada, os resultados de validação não ficam vinculados ao registro do cliente no sistema de referência criando trilhas de auditoria quebradas, e a transcrição manual dos status de documentos do validador para o CRM gera uma taxa de erro de 2% a 5%, o que representa 200 a 500 registros com status inconsistente para organizações com 10.000 dossiês anuais.

Qual é o padrão de integração mais adequado para um pipeline automatizado de conformidade?

Os webhooks orientados a eventos são o padrão recomendado para pipelines automatizados e integrações ERP, porque invertem o fluxo de informação: em vez de o sistema consultar periodicamente a API, a plataforma de validação notifica automaticamente o sistema assim que o processamento termina. Essa abordagem elimina a latência do polling, consome menos recursos e permite que o CRM ou ERP seja atualizado em quase tempo real sem qualquer intervenção humana para os documentos que passam em todas as verificações.

Como integrar a validação documental com o Salesforce?

A integração Salesforce mais comum utiliza um componente intermediário (Lambda ou Cloud Function) que recebe e valida o payload de webhook da plataforma de validação, conectado ao Salesforce via OAuth 2.0 e Connected App para escrever nos objetos relevantes. A camada de automação do Salesforce, via Salesforce Flow ou Apex Trigger, detecta as atualizações nos objetos e aciona a lógica de negócio subsequente, como avançar um dossiê no pipeline ou notificar o gestor de conta.

Quais as boas práticas para gerenciar chaves API de forma segura numa integração de produção?

As chaves API devem ser tratadas como segredos e nunca armazenadas em texto plano no código-fonte ou em variáveis de ambiente desprotegidas. As boas práticas incluem utilizar uma chave diferente por ambiente (desenvolvimento, staging e produção), armazenar as chaves em cofres de segredos como HashiCorp Vault, AWS Secrets Manager ou Azure Key Vault, trocar as chaves a cada 90 dias aproveitando o suporte a duas chaves ativas simultaneamente para rotação sem tempo de inatividade, e nunca compartilhar uma chave entre ambientes nem incluir chaves em repositórios de código.

Nossa plataforma processa mais de 180.000 documentos por mês com um tempo médio de verificação de 4,2 segundos e uma disponibilidade de 99,97%.