Importação de Documentos

Visão Geral

A API de Importação de Documentos do Flexdoc permite que sistemas externos enviem lotes de documentos para processamento automático de análise, classificação, validação documental e biometria.

Fluxo Simples

Apenas 2 etapas: Autenticação + Importação

Processamento Automático

OCR, classificação e validação sem intervenção manual

Resultado via Webhook

Receba os resultados automaticamente em sua URL

Multi-documento

Envie múltiplos documentos em um único lote

Fluxo de Integração

Autenticação OAuth 2.0

Obtenha um token de acesso JWT via Keycloak usando suas credenciais

Preparar Metadados

Monte o arquivo JSON com informações do lote e documentos

Importar Documentos

Envie JSON + arquivos via requisição multipart/form-data

Receber BatchID

Armazene o ID do lote retornado para rastreamento

Aguardar Webhook

Receba o resultado completo da análise em sua URL de callback

1. Autenticação OAuth 2.0

Credenciais de Acesso

Você receberá as credenciais de acesso por email. Exemplo de ambiente de desenvolvimento:

Parâmetro	Valor
CLIENT_ID	`teste-api`
CLIENT_SECRET	`vveMLSHnasVxzKWchN0DpeEawG4UlXSxs`

As credenciais acima são de uso exclusivo para ambiente de desenvolvimento (DES). Credenciais de produção serão fornecidas separadamente pelo time de integração.

Endpoint de Autenticação

POST https://auth-des.flexdoc-apis.com.br/realms/fleximage/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=teste-api&client_secret=vveMLSHnasVxzKWchN0DasdawG4UlXxs

Resposta de Sucesso

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "profile email"
}

access_token

string

required

Token JWT para autenticação nas APIs. Use no header Authorization: Bearer <token>

token_type

string

Sempre "Bearer"

expires_in

integer

Tempo de validade em segundos (padrão: 3600 = 1 hora)

scope

string

Escopos concedidos ao token

O token expira em 1 hora (3600 segundos). Quando expirar, execute a autenticação novamente para obter um novo token.

2. Importação de Documentos

Use o playground “Try It” à direita para testar a API diretamente na documentação! →

Authentication

Authorization

string

required

Bearer token obtido via OAuth 2.0Formato: Bearer {access_token}Exemplo: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Request Body

jsonData

file

required

Arquivo JSON contendo metadados do lote e dos documentos.Tipo: JSON fileEstrutura detalhada: Ver seção 3 abaixoContent-Type: application/json

files

file[]

required

Array de arquivos (PDF, PNG, JPG, JPEG) dos documentos a serem processados.Formatos aceitos: PDF, PNG, JPG, JPEGTamanho máximo: 5MB por arquivoValidação: Nomes devem corresponder aos especificados no campo fileName do JSON

Response

batchId

integer

required

Identificador único do lote criado no sistema. Use este ID para rastrear o processamento.Exemplo: 4697

{
  "batchId": 4697
}

3. Estrutura do JSON (jsonData)

Template Completo

{
  "workflowAlias": "poc_onboarding",
  "batchExternalId": "LOTE-2026-001",
  "batchOrigin": "1",
  "keys": [
    {
      "key": "webhook_uri",
      "value": "https://seu-sistema.com/api/webhook/flexdoc"
    },
    {
      "key": "cpf",
      "value": "12345678900"
    },
    {
      "key": "origin_system",
      "value": "portal_cliente"
    }
  ],
  "docs": [
    {
      "fileName": "rg_completo.pdf",
      "contentType": "pdf",
      "typeAlias": "nao_identificado",
      "keys": [
        {
          "key": "cpf",
          "value": "12345678900"
        }
      ]
    },
    {
      "fileName": "selfie_cliente.png",
      "contentType": "png",
      "typeAlias": "selfie",
      "keys": [
        {
          "key": "cpf",
          "value": "12345678900"
        }
      ]
    }
  ]
}

Campos do Lote

workflowAlias

string

required

Determina o fluxo de processamento aplicado ao lote:

Valor	Descrição
`poc_onboarding`	Fluxo padrão com intervenção manual (análise humana)
`poc_auto_face`	Processamento 100% automático com validação biométrica facial
`poc_auto`	Processamento 100% automático sem validação biométrica

Use poc_auto_face para onboarding digital com selfie.

batchExternalId

string

required

Identificador externo do lote para rastreamento no seu sistema.Exemplo: "LOTE-2026-001", "PF-12345-20260414"

batchOrigin

string

required

Código da origem do lote. Geralmente "1" (consulte com o time de integração).

keys

array

required

Lista de chaves lógicas do lote. 3 chaves obrigatórias:

webhook_uri (obrigatório)

URL de callback para receber o resultado da análise após o processamento.Formato: URL completa (https://)Exemplo: "https://seu-sistema.com/api/webhook/flexdoc"

🔒 Se a URL de webhook exigir autenticação (token, Basic Auth ou header personalizado), informe previamente à equipe Flexdoc para configuração segura no sistema.

cpf (obrigatório)

CPF do titular do documento (somente números, sem formatação).Formato: 11 dígitosExemplo: "12345678900"

origin_system (obrigatório)

Nome do cliente, sistema ou projeto de origem. Utilizado para agrupamento e controle de registros.Exemplo: "portal_cliente", "app_mobile", "trustic_web"

Campos dos Documentos

docs

array

required

Lista de documentos a serem importados. Cada documento possui:

fileName (obrigatório)

Nome do arquivo que deve corresponder exatamente ao arquivo enviado no campo files.Case-sensitive: "RG.pdf" ≠ "rg.pdf"Exemplo: "rg_completo.pdf", "selfie_cliente.png"

contentType (obrigatório)

Formato do arquivo. Valores aceitos:

"pdf" - Documentos PDF
"jpg" ou "jpeg" - Imagens JPEG
"png" - Imagens PNG

Tamanho máximo recomendado: 5MB por arquivo

typeAlias (opcional)

Tipo do documento. Se omitido, classificação automática via deep learning é aplicada.

Valor	Descrição
`nao_identificado`	Documento não identificado → classificação automática
`selfie`	Fotografia de rosto (obrigatório para validação biométrica)
`rg_frente`	Frente do RG
`rg_verso`	Verso do RG
`cnh`	CNH (carteira de motorista)

⚠️ Importante: Documentos de identidade frente e verso devem ser enviados como um único arquivo combinado (merge). Arquivos separados de frente e verso não são aceitos.

keys (opcional)

Lista de chaves associadas ao documento específico (ex.: CPF do titular).Estrutura:

[
  {
    "key": "cpf",
    "value": "12345678900"
  }
]

4. Exemplo Completo de Requisição

curl -X POST "https://flex-des.flexdoc-apis.com.br/import/import-doc/create" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -F "jsonData=@lote.json" \
  -F "files=@rg_completo.pdf" \
  -F "files=@selfie_cliente.png"

5. Resposta da Importação

Sucesso (200 OK ou 201 Created)

{
  "batchId": 4697
}

batchId

integer

required

Identificador único do lote processado. Armazene este ID para rastreamento e consultas futuras.

Lote criado com sucesso! O processamento iniciou automaticamente. Aguarde o webhook com o resultado completo da análise.

Códigos de Status HTTP

Sucesso (2xx)

Código	Status	Descrição
`200`	OK	Operação realizada com sucesso
`201`	Created	Lote criado com sucesso
`204`	No Content	Nenhum registro encontrado

Erro do Cliente (4xx)

Código	Status	Descrição
`400`	Bad Request	Erro na requisição. Verifique os parâmetros enviados
`401`	Unauthorized	Token inválido ou expirado. Solicite um novo token
`403`	Forbidden	Acesso negado. Verifique as permissões da credencial
`404`	Not Found	Serviço não encontrado. Verifique a URL
`413`	Payload Too Large	Arquivo muito grande (máx 10MB)

Erro do Servidor (5xx)

Código	Status	Descrição
`500`	Internal Server Error	Erro interno no servidor. Entre em contato com o suporte
`503`	Service Unavailable	Serviço indisponível temporariamente

6. Webhook - Retorno da Validação

Após o processamento, o sistema envia automaticamente um POST para a URL configurada em webhook_uri com o resultado completo da análise.

Estrutura do Response (ResponseDto)

{
  "dataInicio": "14/04/2026 10:30:15",
  "dataFinal": "14/04/2026 10:32:47",
  "codigoControle": 145900,
  "result": 0,
  "inconclusivo": false,
  "indiceAvaliacaoAutenticidade": 98,
  "indiceFacematch": 95,
  "tipoDocumento": "CNH",
  "cpf": "12345678900",
  "origin": "document-analysis",
  "originKey": "3116063c-a61f-467a-83e5-5e3b07b66e2d",
  "customerId": "trustic",
  "externalId": "LOTE-2026-001",
  "penalidades": [],
  "codigoRejeicao": [],
  "docs": [
    {
      "docName": "Documento de Identidade",
      "docId": 215170,
      "docType": "doc_identidade",
      "type": "cnh",
      "keys": [
        { "keyAlias": "nome", "keyName": "Nome", "value": "JOÃO DA SILVA" },
        { "keyAlias": "cpf", "keyName": "CPF", "value": "12345678900" },
        { "keyAlias": "data_nascimento", "keyName": "Data Nascimento", "value": "15/03/1990" },
        { "keyAlias": "num_registro", "keyName": "Número Registro", "value": "12345678901" }
      ]
    }
  ]
}

Campos Principais

Informações de Processamento

dataInicio

string

Data e hora de início do processamento (formato: DD/MM/YYYY HH:MM:SS)

dataFinal

string

Data e hora de finalização do processamento

codigoControle

integer

Código único de controle da transação

Resultado da Análise

result

integer

Código do resultado da validação:

Código	Status	Significado
`0`	Aprovado	Documento validado com sucesso
`1`	Pendente	Análise inconclusiva, rejeições por qualidade de imagem
`2`	Rejeitado	Documento rejeitado por inconsistências (penalidades) abaixo do mínimo permitido

inconclusivo

boolean

Indica se a análise foi inconclusiva

Índices de Confiança

indiceAvaliacaoAutenticidade

integer

Índice percentual de autenticidade do documento (0-100)

90-100: Excelente
70-89: Bom
50-69: Regular
0-49: Baixo

indiceFacematch

integer

Índice percentual de correspondência facial (0-100)

95-100: Match muito alto
85-94: Match alto
70-84: Match moderado
0-69: Match baixo (rejeitar)

Disponível apenas quando workflowAlias = "poc_auto_face" e selfie foi enviada.

Dados do Titular

tipoDocumento

string

Tipo do documento principal analisado (RG, CNH, CPF, etc)

cpf

string

CPF do titular do documento (apenas números)

Rastreabilidade

origin

string

Origem da análise

originKey

string

Chave identificadora da origem (UUID)

customerId

string

Identificador do cliente

externalId

string

Identificador externo da transação (seu batchExternalId)

Penalidades (PenalidadeDto)

Array de objetos contendo irregularidades encontradas durante a análise formalística.

penalidades

array

Lista de penalidades detectadas (vazio se aprovado sem ressalvas)Estrutura:

{
  "data": "14/04/2026 11:16:45",
  "valor": "MARIA",
  "descricao": "(OCR_02) Nome obtido no documento divergente do nome na RF",
  "regra": "ocr_02",
  "rulesType": 1
}

Campos:

data (string): Data e hora da detecção
valor (string): Valor associado (quando aplicável)
descricao (string): Descrição detalhada da penalidade
regra (string): Código da regra que gerou a penalidade
rulesType (integer): Tipo da regra
- 1 = Automática (crítico - divergências com bases oficiais)
- 2 = Manual
- 3 = Híbrido (alerta - características suspeitas)

Códigos de Penalidade Comuns

RG (Registro Geral)

Código	Descrição
`rg_05`	Existe letra “E” entre a Filiação
`rg_11`	Assinatura do Diretor divergente
`rg_17`	Doc Origem alinhado incorretamente com 3ª letra do Titular
`rg_37`	Formato do RG divergente
`rg_40`	Nome da Mãe antes do Nome do Pai

OCR (Validação de Dados)

Código	Descrição
`ocr_02`	Nome obtido no documento divergente do nome na RF (Receita Federal)
`ocr_03`	Data de Nascimento divergente da RF
`ocr_13`	Primeiro nome do titular divergente da RF

CNH (Carteira Nacional de Habilitação)

Código	Descrição
`cnh_08`	Campo Data Emissão Divergente no Datavalid
`cnh_15`	CNH vencida
`cnh_22`	Número de registro divergente

Códigos de Rejeição (CodigoRejeicaoDto)

Array de objetos contendo motivos de rejeição automática por problemas de qualidade.

codigoRejeicao

array

Lista de códigos de rejeição (vazio se qualidade OK)Estrutura:

{
  "tipo": "RG",
  "codigo": "doc001",
  "motivo": "Documento ilegível",
  "docId": 215172
}

Campos:

tipo (string): Tipo do documento rejeitado
codigo (string): Código do erro
motivo (string): Descrição do motivo
docId (integer): ID do documento rejeitado

Códigos de Rejeição Comuns

Código	Descrição
`doc001`	Documento ilegível (baixa qualidade, desfocado)
`doc002`	Documento incompleto (faltando frente ou verso)
`doc003`	Documento danificado (rasgado, manchado)
`doc004`	Documento expirado
`doc005`	Arquivo corrompido ou inválido

Documentos Analisados (DocumentoDto)

docs

array

Lista de documentos analisados com dados extraídos via OCREstrutura:

{
  "docName": "Documento de Identidade",
  "docId": 215170,
  "docType": "doc_identidade",
  "type": "cnh",
  "keys": [
    {
      "keyAlias": "nome",
      "keyName": "Nome",
      "value": "JOÃO DA SILVA"
    }
  ]
}

Campos:

docName (string): Nome descritivo do documento
docId (integer): Identificador único do documento
docType (string): Tipo técnico do documento
type (string): Categoria do documento (rg, cnh, cpf, etc)
keys (array): Campos extraídos pelo OCR

Campos Extraídos (KeyDto)

CNH - Carteira Nacional de Habilitação

keyAlias	keyName	Descrição
`nome`	Nome	Nome completo do titular
`cpf`	CPF	Número do CPF
`doc_identidade_numero`	Número RG	Número do RG
`doc_identidade_orgao`	Órgão Expedidor RG	Órgão emissor do RG
`doc_identidade_uf`	UF Órgão Expedidor RG	UF do órgão emissor
`data_nascimento`	Data Nascimento	Data de nascimento (DD/MM/YYYY)
`filiacao_pai`	Filiação Pai	Nome do pai
`filiacao_mae`	Filiação Mãe	Nome da mãe
`num_registro`	Número Registro	Número de registro da CNH
`data_validade`	Data Validade	Data de validade da CNH
`data_habilitacao`	Data Habilitação	Data da primeira habilitação
`data_emissao`	Data Emissão	Data de emissão da CNH
`orgao_emissor`	Órgão Emissor	Órgão emissor (DETRAN)
`detran_uf`	Detran UF	UF do DETRAN
`security_code_1`	Número Segurança	Código de segurança 1
`security_code_2`	Renach	Código Renach
`num_espelho`	Número Espelho	Número espelho da CNH

RG - Registro Geral

keyAlias	keyName	Descrição
`nome`	Nome	Nome completo do titular
`cpf`	CPF	Número do CPF
`doc_identidade_numero`	Número Documento	Número do RG
`doc_identidade_orgao`	Órgão Expedidor	Órgão emissor
`doc_identidade_uf`	UF Órgão Expedidor	UF do órgão emissor
`data_nascimento`	Data Nascimento	Data de nascimento
`data_expedicao`	Data Expedição	Data de expedição
`filiacao_pai`	Filiação Pai	Nome do pai
`filiacao_mae`	Filiação Mãe	Nome da mãe
`naturalidade_cidade`	Naturalidade Cidade	Cidade de nascimento
`naturalidade_uf`	Naturalidade UF	UF de nascimento

7. Fluxo de Interpretação do Webhook

1. Verificar result

if (result === 0) {
  // Aprovado - Prosseguir com o processo
} else if (result === 1) {
  // Pendente - Verificar codigoRejeicao Reenviar documentos com melhor qualidade
} else if (result === 2) {
  // Rejeitado -  Verificar penalidades
}

2. Analisar codigoRejeicao

Se não vazio, contém motivos de rejeição automática (documento ilegível, incompleto ou danificado).

3. Examinar penalidades

4. Consultar docs

Acessar dados extraídos dos documentos via OCR.

5. Verificar índices de confiança

indiceAvaliacaoAutenticidade: 0-100 (quanto maior, melhor)
indiceFacematch: 0-100 (> 70 recomendado)

8. Boas Práticas

Segurança

Nunca exponha client_secret em repositórios públicos
Use variáveis de ambiente para armazenar credenciais
Implemente autenticação no webhook (token, Basic Auth)
Use HTTPS em produção
Rotacione secrets periodicamente (a cada 90 dias)
Valide a origem das requisições do webhook (whitelist de IPs)

Performance

Limite lotes a 10-20 documentos por requisição para melhor performance
Otimize imagens antes do envio (resolução 300 DPI recomendada)
Use compressão de PDFs quando possível
Para grandes volumes, processe em lotes paralelos (máx 5 simultâneos)
Monitore o tamanho total do request (limite: 50MB recomendado)
Cache tokens válidos (expire em 55 minutos para margem de segurança)

Qualidade de Imagem

Resolução mínima: 300 DPI
Formato preferencial: PDF para documentos, PNG para selfies
Iluminação: Boa iluminação natural ou artificial uniforme
Foco: Imagens nítidas, sem desfoque
Enquadramento: Documento completo, sem cortes
Sem reflexos: Evite flash direto em documentos plastificados
Merge RG: Combine frente e verso em um único PDF

Rastreabilidade

Sempre preencha batchExternalId com identificador único
Use padrão consistente: {origem}-{cliente}-{timestamp}
Exemplo: "PORTAL-12345-20260414103015"
Armazene batchId retornado para consultas futuras
Mantenha log de todas as importações (request + response)
Implemente monitoramento de webhooks (alertas se não receber em X minutos)

Tratamento de Erros

Implemente retry com backoff exponencial para erros 5xx
- 1ª tentativa: aguardar 1s
- 2ª tentativa: aguardar 2s
- 3ª tentativa: aguardar 4s
- Máximo de 3 tentativas
Para erro 400, não reprocesse - corrija os dados
Para erro 401, renove o token e tente novamente
Monitore logs para identificar padrões de falha
Configure alertas para taxa de erro > 5%
Mantenha auditoria de tentativas de importação

Webhook - Implementação

Responda rapidamente: Retorne HTTP 200 em < 3 segundos
Processe assincronamente: Salve dados e processe em background
Implemente idempotência: Webhook pode ser reenviado
Valide assinatura: Se configurado, valide header de autenticação
Log completo: Registre payload recebido para debugging
Retry do webhook: Sistema tenta reenviar 3x em caso de falha

9. Ambientes

Desenvolvimento (DEV)
Produção (PROD)

URLs

API Import: https://flex-des.flexdoc-apis.com.br/import
SSO (Keycloak): https://auth-des.flexdoc-apis.com.br
Realm: fleximage

Credenciais (Exemplo)

CLIENT_ID: trustic-api
CLIENT_SECRET: vveMLSHnasVxzKWchN0DpeEawG4UlXxs

Credenciais de desenvolvimento são fornecidas no email de boas-vindas.

URLs

API Import: https://fcvs-flexdoc-apis.com.br/import
SSO (Keycloak): https://auth.flexdoc-apis.com.br
Realm: fleximage

Credenciais

🔒 Credenciais de produção são fornecidas separadamente pelo time de integração após homologação completa.

Processo de Go-Live

Homologação Completa

Teste todos os fluxos em ambiente DEV

Solicitar Credenciais PROD

Envie email para integracao@flexdoc.com.br

Configurar Webhook PROD

Forneça URL de produção e método de autenticação

Testes Piloto

Execute testes limitados em PROD

Go-Live

Libere para uso geral

Primeiros Passos

Onboarding

Bureau

Liveness

Assinatura Digital

ID Check

BPO

​Visão Geral

Fluxo Simples

Processamento Automático

Resultado via Webhook

Multi-documento

​Fluxo de Integração

​1. Autenticação OAuth 2.0

​Credenciais de Acesso

​Endpoint de Autenticação

​Resposta de Sucesso

​2. Importação de Documentos

​Authentication

​Request Body

​Response

​3. Estrutura do JSON (jsonData)

​Template Completo

​Campos do Lote

​Campos dos Documentos

​4. Exemplo Completo de Requisição

​5. Resposta da Importação

​Sucesso (200 OK ou 201 Created)

​Códigos de Status HTTP

​6. Webhook - Retorno da Validação

​Estrutura do Response (ResponseDto)

​Campos Principais

​Penalidades (PenalidadeDto)

​Códigos de Rejeição (CodigoRejeicaoDto)

​Documentos Analisados (DocumentoDto)

​Campos Extraídos (KeyDto)

​7. Fluxo de Interpretação do Webhook

​8. Boas Práticas

​9. Ambientes

​URLs

​Credenciais (Exemplo)

​URLs

​Credenciais

​Processo de Go-Live

Visão Geral

Fluxo de Integração

1. Autenticação OAuth 2.0

Credenciais de Acesso

Endpoint de Autenticação

Resposta de Sucesso

2. Importação de Documentos

Authentication

Request Body

Response

3. Estrutura do JSON (jsonData)

Template Completo

Campos do Lote

Campos dos Documentos

4. Exemplo Completo de Requisição

5. Resposta da Importação

Sucesso (200 OK ou 201 Created)

Códigos de Status HTTP

6. Webhook - Retorno da Validação

Estrutura do Response (ResponseDto)

Campos Principais

Penalidades (PenalidadeDto)

Códigos de Rejeição (CodigoRejeicaoDto)

Documentos Analisados (DocumentoDto)

Campos Extraídos (KeyDto)

7. Fluxo de Interpretação do Webhook

8. Boas Práticas

9. Ambientes

URLs

Credenciais (Exemplo)

URLs

Credenciais

Processo de Go-Live