Estudo de Caso: Fluxo de Captura de Documentos

A captura de um documento é uma das funcionalidades mais importantes (e mais complexas) do E-Docs. Esta página acompanha o fluxo completo da captura, desde o momento em que o usuário faz upload de um PDF no navegador até a inclusão do documento na cadeia de integridade do sistema (E-Docs Chain).

Nota ao leitor

A leitura está organizada em quatro partes, cada uma narrando o que acontece em uma fase distinta da captura e descendo, em seguida, ao detalhamento técnico dos módulos envolvidos: operações realizadas, padrões de integração, estados resultantes e efeitos colaterais. Quem busca uma visão de alto nível pode acompanhar pelas aberturas narrativas; quem precisa da profundidade técnica encontra, dentro de cada parte, tudo o que está acontecendo nos bastidores.

Diagrama de referência:

Clique no diagrama para abrir em alta resolução em uma nova aba.

Visão geral

O fluxo de captura é orientado a eventos e composto por três fases temporais distintas, distribuídas ao longo das quatro partes desta página:

1. Fase de processamento. Compreende as etapas de Dispatch (END) e Process (ENP). O END valida os dados, cria um evento de processamento e devolve imediatamente ao navegador um token identificador do evento; o ENP consome esse evento e o processa de forma assíncrona, enquanto o navegador acompanha a evolução fazendo polling^* sobre o token. Em condições normais, a captura conclui em cerca de 3 segundos. (Partes 2 e 3.)
2. Pós-processamento assíncrono. Disparado pelo próprio ENP ao final da fase de processamento. Compreende três fluxos paralelos (indexação de metadados, notificação, análise de conteúdo) e uma indexação de conteúdo subsequente. O usuário não aguarda, o documento já está acessível ao capturador. (Parte 4.)
3. Tarefas agendadas. Independentes do fluxo de captura individual. Compreendem a geração periódica do E-Docs Chain, executada pelo ENT. (Parte 4.)

O fluxo envolve 6 módulos acionados diretamente e 6 sistemas auxiliares utilizados em pontos específicos. A arquitetura é desacoplada, cada módulo tem responsabilidade única e bem delimitada, e a comunicação entre eles acontece via fila (assíncrono), API (síncrono) ou job agendado, conforme o caso.

Os padrões de projeto que estruturam este fluxo, em especial o Dispatch/Process e o Outbox, além das demais decisões da nova arquitetura, são apresentados em E-Docs Next-Gen Architecture, o artigo de referência sobre os padrões de projeto, as feature flags e a estratégia de migração do E-Docs.

^* Polling: técnica em que o cliente consulta o servidor em intervalos curtos para verificar se algo mudou.

---

1. Iniciando o Processo de Captura

Você redigiu um documento em seu editor de texto favorito, o salvou em formato PDF, e agora deseja capturá-lo no E-Docs. Você acessa e-docs.es.gov.br, se autentica no Acesso Cidadão, clica em "Captura ou Elaboração", depois em "Upload de PDF" e seleciona o documento PDF em seu computador.

Neste momento, o E-Docs solicita ao seu servidor de arquivos (MinIO) uma url para upload, informando o tamanho do arquivo em bytes e sua extensão. O servidor responde com a url, e só aceitará o upload se o arquivo possuir exatamente as informações passadas, por questões de segurança. Seu navegador inicia o upload, e o arquivo é armazenado em uma área de arquivos temporários no servidor.

Você então é levado à tela de captura. O E-Docs exibe o arquivo recém-enviado para que você possa visualizá-lo e confirmar que subiu o arquivo certo. Você avança pelas opções apresentadas: seleciona um papel (cargo/lotação), informa que se trata de um Documento Eletrônico (feito no computador, e não escaneado) e que o tipo de assinatura será a do E-Docs (será assinado eletronicamente através do seu login, seguindo a legislação vigente).

Você avança no passo a passo. Ajusta o nome do documento, seleciona uma classe documental que condiz com o teor do seu documento, informa que só você assinará o documento e que ele não possui restrição de acesso prevista em lei (passando, assim, a ter nível de acesso Organizacional). Por fim, você lê o termo de responsabilidade, declara estar ciente e clica no botão CAPTURAR.

Até este momento, toda a interação se passou no navegador, exceto pelo upload do PDF (que viajou direto do seu computador para o servidor de arquivos, sem passar pelo back-end do E-Docs). O sistema ainda não capturou nada: o que existe é um arquivo aguardando em uma área temporária e um formulário de metadados pronto para ser submetido. É o clique em CAPTURAR que põe o E-Docs em ação, dando início à próxima parte do fluxo.

---

2. Preparação e Enfileiramento: END · Negócio Dispatch

Ao clicar em CAPTURAR, o navegador submete a requisição ao END (E-Docs Negócio Dispatch), levando consigo a referência ao PDF no bucket temporário e todos os metadados preenchidos no formulário. A tela exibe um indicador de progresso enquanto aguarda a resposta.

Padrão de integração: Síncrono (HTTP), recebe a requisição diretamente da interface do usuário.
Saída: Evento de captura criado e publicado na fila do ENP; token do evento devolvido ao navegador.
Estado resultante do evento: Criado

Função

O END é o ponto de entrada do fluxo de captura. Sua responsabilidade é validar os dados da captura recebidos do usuário e, se a validação for bem-sucedida, criar e enfileirar o evento de captura para processamento assíncrono pelo ENP, devolvendo ao navegador um token identificador do evento.

A separação entre Dispatch (END) e Process (ENP) é proposital: ela permite que o END responda rapidamente ao usuário (apenas validando, criando o evento e devolvendo o token), enquanto o trabalho pesado de processamento do documento acontece de forma assíncrona no ENP, com capacidade de absorver picos de carga e escalar horizontalmente.

Operações realizadas

1. Obtenção dos dados da captura. O END recebe via API a requisição de captura, contendo a referência ao arquivo PDF e os metadados associados (capturador, assinantes, classe documental, fundamento legal).
2. Validação dos dados. Verifica a consistência e completude dos dados recebidos:
   • O capturador é um usuário válido e tem permissão de captura?
   • A classe documental existe e está disponível ao capturador?
   • O fundamento legal é compatível com a classe documental?
   • Os assinantes (quando informados) são usuários válidos? Se forem papéis, estão ativos?
3. Criação do evento de captura. Se a validação for bem-sucedida, cria um evento de captura contendo todos os dados validados, em estado Criado.
4. Publicação na fila. Publica o evento na fila correspondente, deixando-o disponível para consumo pelo ENP. O estado permanece Criado neste ponto; a transição para Enfileirado é responsabilidade do consumidor de fila do ENP (ver Parte 3).
5. Devolução do token ao navegador. Responde à requisição HTTP com o token identificador do evento. O navegador passa, então, a fazer polling a cada 3 segundos (até 10 tentativas, ~30 segundos no total) sobre esse token, consultando a situação do evento até detectá-lo no estado Concluído, momento em que apresenta ao usuário a captura como concluída.

---

3. O Processamento da Captura: ENP · Negócio Process

Enquanto o navegador exibe a tela de espera e consulta a situação do evento a cada três segundos, o ENP (E-Docs Negócio Process) entra em cena. Ele recupera o evento enfileirado pelo END e executa as operações pesadas que transformam o PDF cru do usuário em um documento E-Docs juridicamente válido, com metadados, carimbo, assinatura digital e devida persistência nas camadas de armazenamento. Ao final, é também o ENP que enfileira as tarefas de pós-processamento e dispara a notificação aos assinantes.

Padrão de integração: Assíncrono (consumidor de fila e job fire-and-forget).
Saída: Documento final capturado, assinado, persistido e disponível ao capturador; tarefas de pós-processamento enfileiradas; notificação aos assinantes disparada.
Estado resultante do evento: Criado → Enfileirado → Processando → Concluído

Função

O ENP é o módulo responsável por executar a transformação efetiva do documento. Sua execução acontece em dois jobs sucessivos:

• Job consumidor de fila. Retira o evento da fila publicada pelo END, marca seu estado como Enfileirado e, em seguida, dispara em fire-and-forget um segundo job para realizar o processamento da captura propriamente dito.
• Job de processamento. Marca o evento como Processando e executa, em sequência, as operações descritas abaixo. Ao final, com tudo dando certo, marca o evento como Concluído.

A separação em dois jobs garante que o consumo da fila seja rápido e libere espaço para outras mensagens, enquanto o trabalho pesado de processamento roda de forma independente, com sua própria gestão de retentativas e isolamento de falhas.

Operações realizadas

O job de processamento executa as seguintes operações em sequência:

1. Recuperação dos dados do evento. O ENP consome o evento da fila e carrega os dados necessários (PDF original, metadados, capturador, assinantes, classe, fundamento legal).

2. Geração da página de metadados. Cria uma página HTML extra contendo os metadados do documento (capturador, assinantes, classe, fundamento legal, data/hora de captura, identificadores, etc.) e a converte para PDF.

3. Anexação da página de metadados. Insere a página de metadados gerada ao final do PDF original do usuário, formando o PDF combinado.

4. Aplicação do carimbo lateral. Adiciona o carimbo lateral azul característico do E-Docs em cada página do documento. Esse carimbo identifica visualmente o documento como capturado pelo E-Docs.

5. Assinatura digital ICP-Brasil. Aplica a assinatura digital do certificado ICP-Brasil de aplicação do E-Docs sobre o PDF final. Essa assinatura garante a integridade do documento de forma verificável mesmo fora do E-Docs (após download, envio por e-mail, etc.).

6. Gravação no MinIO. Persiste o PDF final no repositório de documentos (MinIO), gerando o identificador único do arquivo armazenado.

7. Persistência no banco de dados, credenciamento e enfileiramento das tarefas de pós-processamento (transação ACID). Em uma única transação no banco de dados transacional (SQL Server), o ENP executa:

   • Persistência do documento. Salva todas as informações do documento: identificador, hash, metadados, referência ao MinIO, capturador, assinantes, classe, fundamento legal, etc.
   • Credenciamento do capturador. Concede ao capturador as permissões de acesso ao documento.
   • Enfileiramento da indexação de metadados (EEI9). Grava, via Outbox Pattern, a mensagem que dispara a indexação dos metadados no Elasticsearch.
   • Enfileiramento da extração de conteúdo (EDA). Grava, via Outbox Pattern, a mensagem que dispara a extração do conteúdo textual do PDF.

   Se qualquer parte falhar, toda a transação é revertida, garantindo que o documento não fique persistido sem credenciamento ou sem o disparo do pós-processamento.

8. Disparo da notificação aos assinantes. Concluída a transação, o ENP chama o ENO via API para que ele componha e envie a notificação de captura aos assinantes do documento (quando houver). Por ser uma chamada HTTP, fica fora do escopo transacional do passo anterior.

Após a execução dessas operações, o job de processamento marca o evento como Concluído, o que significa que o documento já está acessível ao capturador, e pode ser usado em processos e encaminhamentos. A próxima chamada de polling do navegador detecta esse estado e apresenta ao usuário a captura como concluída. A fase de processamento do fluxo termina aqui.

Tempo de captura e cenário de espera estendida

Em condições normais, o processamento dura cerca de 3 segundos, e o navegador detecta o estado Concluído já na primeira ou segunda chamada de polling.

Se, por algum motivo, o processamento exceder os ~30 segundos da janela de polling, o navegador encerra a espera e exibe ao usuário a mensagem "a captura está demorando mais que o esperado", devolvendo-o à navegação normal do sistema. O processamento, contudo, não é interrompido: o evento permanece na fila ou no estado Processando e seguirá até Concluído assim que o ENP concluir o trabalho. Ao final, o usuário será notificado da conclusão por e-mail e sininho, sem necessidade de refazer a operação.

---

4. Bastidores: Pós-Processamento e Encadeamento

Sua tela já mostrou "captura concluída" e você seguiu sua vida: pode estar lendo um processo, capturando outro documento ou simplesmente ter fechado o navegador. Mas o E-Docs não terminou. Nos bastidores, ainda há trabalho importante a ser feito para que o documento se torne pesquisável, para que os assinantes sejam notificados e para que sua integridade seja selada na cadeia de confiança (E-Docs Chain) do sistema. Tudo isso acontece de forma assíncrona, sem prender o usuário a uma tela de espera.

Esta parte cobre cinco etapas: três fluxos paralelos disparados pelo próprio ENP ao final do processamento (indexação de metadados via EEI9, notificação via ENO e extração de conteúdo via EDA), uma indexação de conteúdo sequencial (EEI9, após o EDA) e, fora do fluxo individual de captura, um job agendado executado pelo ENT que gera periodicamente o E-Docs Chain.

4.1. Indexação de metadados: EEI9 · Elastic Index 9

Padrão de integração: Assíncrono (consumidor de fila).
Execução: Em paralelo com 4.2 (ENO) e 4.3 (EDA).
Saída: Metadados do documento indexados no Elasticsearch, disponíveis para busca.

Função

O EEI9 (E-Docs Elastic Index 9) é o módulo de indexação textual que prepara os documentos capturados para busca no Elasticsearch. Esta primeira invocação do EEI9 cuida da indexação dos metadados do documento (registro, nome do documento, capturador, classe, data de captura, assinantes, etc.), o que torna o documento encontrável por filtros e atributos imediatamente após o pós-processamento.

Operações realizadas

1. Recuperação dos dados do evento de indexação. Consome o evento de indexação de metadados enfileirado pelo ENP.
2. Obtenção dos metadados. Recupera os metadados do documento da camada de persistência.
3. Indexação no Elasticsearch. Estrutura e envia os metadados ao Elasticsearch, em índice apropriado, viabilizando a busca textual e filtragem por atributos.

A partir deste momento, o documento é encontrável por metadados via busca no E-Docs.

4.2. Notificação aos assinantes: ENO · Notificação Composer

Padrão de integração: Síncrono (API), invocado pelo ENP.
Execução: Em paralelo com 4.1 (EEI9 metadados) e 4.3 (EDA).
Saída: Notificação enviada aos assinantes do documento por e-mail e sininho.

Função

O ENO (E-Docs Notificação Composer) é o módulo responsável por compor e disparar notificações relacionadas a eventos do E-Docs. No fluxo de captura, sua função é notificar os assinantes do documento de que a captura foi finalizada.

Operações realizadas

1. Obtenção dos dados dos assinantes. Carrega os dados dos assinantes do documento, incluindo, especialmente, os e-mails e identificadores necessários para envio de notificação.
2. Composição e envio da notificação. Compõe a mensagem de notificação correspondente ("o documento que você assinou foi capturado e está disponível") e a envia via Notifica ES, que cuida da entrega tanto pelo canal de e-mail quanto pelo sininho dentro dos sistemas integrados ao Acesso Cidadão.

A notificação chega ao assinante tipicamente em alguns minutos após a captura.

4.3. Extração de conteúdo: EDA · Document Analyzer

Padrão de integração: Assíncrono (consumidor de fila).
Execução: Em paralelo com 4.1 (EEI9 metadados) e 4.2 (ENO).
Saída: Texto extraído do documento salvo no MinIO. Evento de indexação de conteúdo disparado para o EEI9.

Função

O EDA (E-Docs Document Analyzer) é o módulo responsável por extrair o conteúdo textual dos documentos capturados, viabilizando a posterior busca textual pelo conteúdo (não apenas pelos metadados). É o único módulo do pós-processamento paralelo que produz uma saída para outro módulo subsequente, o EEI9 (subseção 4.4).

Operações realizadas

1. Recuperação dos dados do evento de extração. Consome o evento de extração enfileirado pelo ENP.
2. Extração do texto nativo. Carrega o PDF do MinIO e extrai o conteúdo textual nativo das páginas que possuem texto selecionável.
3. OCR em imagens. Para páginas que contêm imagens (ou que são integralmente imagens, caso comum de documentos digitalizados), aplica reconhecimento óptico de caracteres (OCR) para extrair o texto presente nas imagens.
4. Persistência do conteúdo extraído. Salva o texto extraído no MinIO, em local específico associado ao documento original.
5. Criação do evento de indexação de conteúdo. Cria um evento na fila do EEI9 solicitando a indexação do conteúdo extraído.

EEI9 (subseção 4.4) consome o evento de indexação de conteúdo. Esta é a única transição sequencial dentro do pós-processamento, o EEI9 só pode indexar o conteúdo depois que o EDA o extraiu.

4.4. Indexação de conteúdo: EEI9 · Elastic Index 9

Padrão de integração: Assíncrono (consumidor de fila).
Execução: Sequencial, após 4.3 (EDA).
Saída: Conteúdo textual do documento indexado no Elasticsearch, disponível para busca.

Função

Esta é a segunda invocação do EEI9 no fluxo, agora dedicada à indexação do conteúdo textual do documento (e não apenas dos metadados, como em 4.1). Após esta etapa, o documento se torna pesquisável também por seu texto, e não apenas por seus atributos.

Operações realizadas

1. Recuperação dos dados do evento. Consome o evento de indexação de conteúdo criado pelo EDA.
2. Obtenção do conteúdo extraído. Recupera o texto extraído pelo EDA, armazenado no MinIO.
3. Indexação no Elasticsearch. Estrutura e envia o conteúdo ao Elasticsearch, em índice apropriado, viabilizando a busca full-text dentro do conteúdo do documento.

Após a conclusão desta etapa, o pós-processamento do documento está integralmente finalizado, e o documento é encontrável tanto por metadados quanto por conteúdo.

Visibilidade na busca: metadados vs. conteúdo

Embora a busca passe a operar sobre as duas dimensões, elas têm regras de visibilidade distintas, e essa diferença é uma decisão deliberada de segurança do E-Docs:

• Metadados são sempre públicos. Qualquer usuário do E-Docs (servidor público ou cidadão) pode encontrar o documento na busca avançada usando seus metadados (registro, nome, capturador, classe, data de captura, assinantes, etc.), independentemente do nível de acesso do documento.
• Conteúdo é restrito pelo nível de acesso. A busca textual sobre o conteúdo do PDF só retorna resultados para usuários que efetivamente têm permissão de ler o documento. Para os demais, o conteúdo é invisível ao mecanismo de busca, mesmo quando os metadados aparecem.

4.5. Cadeia de integridade: ENT · Negócio Tasks (job agendado)

Padrão de integração: Job agendado, executado periodicamente.
Execução: Independente do fluxo de captura individual.
Saída: Documento-Elo gerado e capturado, encadeado ao Documento-Elo anterior.

Função

O ENT (E-Docs Negócio Tasks) atua no fluxo de captura exclusivamente como executor de uma tarefa agendada. Sua função é gerar periodicamente os Documentos-Elo que compõem o E-Docs Chain, a cadeia de confiança que garante a integridade verificável de todos os documentos capturados pelo sistema.

Cada execução do job recolhe os documentos capturados no último intervalo, calcula seus hashes e os agrupa em um novo Documento-Elo, que também referencia o hash do Documento-Elo anterior. O Documento-Elo é capturado pelo próprio fluxo descrito nas partes 2, 3 e nas subseções anteriores desta parte, e possui nível de acesso público.

Para o funcionamento detalhado, as operações executadas pelo job e a fundamentação legal da solução, consulte a documentação dedicada do E-Docs Chain.

---

Conceitos transversais

Os conceitos abaixo se aplicam ao fluxo como um todo e são referenciados ao longo das quatro partes.

Atores

O fluxo envolve três grupos de atores distintos (todos representados no diagrama no topo desta página), cada um com sua própria jornada temporal:

• Capturador. Usuário que executa a captura. Usa a interface do E-Docs para fazer upload do PDF e preencher os dados de captura (Parte 1).
• Assinantes. Usuários que assinaram o documento previamente, em algum momento anterior à captura. Não interagem durante o fluxo de captura, recebem a notificação de forma passiva, via e-mail e sininho, alguns minutos após a conclusão da captura.
• Qualquer usuário. Qualquer usuário do sistema com permissão de acesso ao documento. Pode buscá-lo por metadados assim que a indexação de metadados (4.1) terminar, ou por conteúdo assim que a indexação de conteúdo (4.4) terminar. A busca é feita via interface do E-Docs, que exibe os resultados conforme as permissões do usuário.

Padrões de integração

A integração entre módulos no fluxo de captura segue três padrões distintos, identificados no diagrama por ícones específicos:

• FILA (assíncrono). Comunicação via fila de mensagens. O módulo emissor publica um evento na fila e segue seu fluxo; o módulo consumidor recupera o evento e processa quando estiver disponível. Permite retentativa, isolamento de falhas e escala horizontal. Todas as filas do E-Docs adotam o Outbox Pattern.
• API (síncrono). Comunicação síncrona via chamada de API HTTP. O módulo emissor aguarda a resposta do consumidor.
• Job Agendado. Tarefa executada periodicamente, em intervalo predeterminado, independente de gatilhos do fluxo de captura.

Estados do evento de captura

O evento de captura percorre quatro estados durante a fase de processamento:

1. Criado. O evento foi criado pelo END com os dados da captura e publicado na fila do ENP, mas ainda não foi consumido.
2. Enfileirado. O job consumidor de fila do ENP retirou o evento da fila e o marcou como Enfileirado. Em seguida, dispara, em fire-and-forget, o job de processamento que fará a captura propriamente dita.
3. Processando. O job de processamento iniciou o trabalho efetivo de captura (geração da página de metadados, carimbo, assinatura digital, persistência, credenciamento, enfileiramento das tarefas de pós-processamento e disparo da notificação).
4. Concluído. O job de processamento finalizou com sucesso. O documento já foi salvo, assinado e está acessível ao capturador; as tarefas de pós-processamento foram enfileiradas e a notificação aos assinantes foi disparada. Este é o estado final do evento de captura.

Camadas de armazenamento

O fluxo utiliza três motores de armazenamento, cada um com responsabilidade específica:

• Microsoft SQL Server. Banco de dados transacional. Persiste metadados de documentos, dados de capturadores e assinantes, estado dos eventos e demais dados estruturados do sistema.
• MinIO. Servidor de arquivos compatível com S3. Armazena os PDFs finais capturados (com metadados, carimbo e assinatura) e os textos extraídos pelo EDA.
• Elasticsearch. Motor de busca. Indexa metadados e conteúdo extraído dos documentos, viabilizando busca textual e filtragem por atributos.

---

Sistemas auxiliares

Os sistemas auxiliares são módulos do ecossistema E-Docs que não fazem parte direta do fluxo de captura, mas são acionados em pontos específicos para fornecer funcionalidades de apoio. A tabela abaixo lista cada um deles com sua sigla, nome e o papel que desempenha no fluxo.

Sigla	Nome do sistema	O que está fazendo no fluxo
ENB	Negócio Base	Fornece a lista de papéis permitidos para captura, validando se o capturador informado no END possui permissão para a ação. Usado em END.
EAQ	Agente Query	Possui a consulta de agentes ativos, essencial para obter dados do capturador e dos assinantes. Usado em END.
EUM	Usuário Manager	Usado pelo ENO para obter as configurações de preferência de envio de e-mail de notificação do tipo Captura de Documento dos usuários.
EMM	MinIO Manager	Abriga toda a lógica de obtenção de urls de download e upload para os vários buckets do Minio (seja os temporários ou o definitivo). Usado em END, ENP e EDA.
DOC-M	Document Models	Gera a versão HTML da folha de metadado que vai ao final da captura. Usado em ENP.
P-PDF	Processador PDF	No END realiza validações no arquivo, verificando se já existe carimbo do E-Docs, assinatura digital, presença de assinatura do E-docs e restrições de leitura/escrita. Já no ENP, faz conversão da folha de metadado de HTML para PDF, merge do pdf original com a folha de metadado, carimbo lateral e inclusão de assinatura ICP-Brasil de aplicação.

---

Documentação técnica do fluxo de captura. Mantida pela equipe de arquitetura do E-Docs (PRODEST).