🧾 Processamento de Notas Fiscais com AWS Textract, NLP e LLM

Uma API REST em Python para processamento de notas fiscais utilizando AWS S3, Textract, NLP e LLM.

🎯 Objetivo

Desenvolver uma API que recebe imagens de notas fiscais, extrai dados estruturados via AWS Textract, aplica técnicas de NLP (Spacy/NLTK) e refina a saída com uma LLM. Os resultados são armazenados em bucket S3, organizados por tipo de pagamento, e monitorados via CloudWatch.

📍 Rotas

POST /api/v1/invoice

• Processamento:

  • Extração de texto e informações com AWS Textract;
  • Identificação de campos (CNPJ, valor total, forma de pagamento, etc.);
  • Refinamento dos dados com LLM (Nova Micro);
  • Armazenamento de imagem em bucket S3: notas com pagamento em dinheiro/pix → pasta /dinheiro, demais → /outros.

• Entrada: Não há conteúdo em body. Envie o próprio arquivo na requisição ou o faça por meio de um formulário.

• Saída:

  {
     "nome_emissor": "nome do emissor",
     "CNPJ_emissor": "CNPJ do emissor",
     "endereco_emissor": "endereço do emissor",
     "CNPJ_CPF_consumidor": "CNPJ ou CPF do consumidor",
     "data_emissao": "DD/MM/YYYY",
     "numero_nota_fiscal": "número de nota fiscal",
     "serie_nota_fiscal": "série de nota fiscal",
     "valor_total": "valor total",
     "forma_pgto": "dinheiropix | outro"
  }

  Obs.: Métricas e logs referentes às execuções podem ser encontrados no CloudWatch ou com Grafana.

  Obs.2: Valores desconhecidos serão preenchidos com "None".

• Ferramentas Utilizadas:

  • S3, Textract, CloudWatch, Lambda, API Gateway, Step Functions;
  • NLTK e LLM

GET /

• Descrição:

  • Página web para uso da API.

• Entrada: Não há.

• Saída: Arquivo HTML (text/html).

⚙️ Como Executar?

Pré-requisitos

• Conta AWS com permissões para os recursos gerados/utilizados;
• Python 3.12 e venv ;
• Credenciais AWS configuradas (via AWS CLI ou por variáveis de ambiente);
• AWS CLI e SAM CLI.

Passo-a-Passo

1. Clone o repositório:

   git clone git@github.com:guirque/receipt-processing.git
   cd receipt-processing

2. Configure o ambiente virtual:

   # Crie o ambiente (nomeado 'python')
   python -m venv python
   
   # Entre no ambiente
   source python/bin/activate  # Linux
   python/Scripts/activate # Windows

3. Instale as dependências:

   pip install -r requirements.txt

4. Configure as credenciais AWS.

5. Faça o deploy da aplicação:

   sam build
   sam deploy --guided

   • Responda às perguntas de sam deploy --guided para fazer o deploy para a AWS.

🚀 Como Utilizar?

Há duas formas principais de utilizar esta API:

Pela página web (em /)

Basta digitar a URL no navegador para acessá-la.

Com isso, pode-se utilizar o botão "choose files" para escolha da imagem da nota fiscal a processar. Depois, é só clicar em "Enviar Imagem" e aguardar uma resposta! Os resultados serão dispostos em uma tabela.

Obs.: há um limite de tamanho de imagem suportado.

Por acesso direto à API (/api/v1/invoice)

Requisições com a imagem podem ser feitas pela ferramenta desejada, com a URL.

Uma forma é por meio de curl:

curl --location --request POST 'https://jazu39no26.execute-api.us-east-1.amazonaws.com/prod/api/v1/invoice' \
--form 'file=@"/caminho/para/nota_fiscal.png"'

Outra é por meio de Postman:

• Com form-data:

• Enviando o arquivo diretamente:

📝 Como testar (para desenvolvimento)?

Para testes locais, certifique-se de ter as seguintes variáveis de ambiente criadas e condizentes com o que for criado: BUCKET_NAME e STATE_MACHINE_ARN. Esses valores devem ser coerentes com o que for gerado pelo sam deploy.

Testando uma função lambda

Execute-a com:

   sam local invoke "<NomeFuncao>"

Caso haja um payload a que se queira enviar à função em sua invocação, faça:

   sam local invoke "<NomeFuncao>" -e <caminhoArquivoJSON>

Testando a API

Execute localmente com:

   sam local start-api

Isso disponibilizará caminhos (urls) para realização de requisições. Caso faça mudanças em uma lambda e deseje que essas alterações sejam refletidas na API, faça sam build em terminal à parte, antes de realizar uma nova requisição.

Obs.: alguns recursos não são executados localmente (aqueles ativados por boto3), mesmo após execução dos comandos citados.
Dessa forma, certifique-se que as variáveis de ambiente (BUCKET_NAME e STATE_MACHINE_ARN) estão de acordo com o desejado.
É recomendado que funções sejam testadas separadamente, com sam local invoke, passando payloads (JSON) pré-prontos, a fim de evitar execuções desnecessárias e possíveis custos adicionais.

Atualizando conteúdo na AWS

Para isso, use o comando:

   sam sync

Ele vai atualizar os recursos na AWS conforme o desenvolvimento local.

🛠️ Infraestrutura AWS

Serviços

• AWS SAM:
  • Infrastructure as Code. Por meio do SAM, recursos podem ser testados localmente e o desenvolvimento pode ser facilmente sincronizado com a nuvem. O deploy é fácil de se fazer, permitindo que uma stack seja criada na nuvem, a partir dos recursos e configurações apontadas em template.yaml. Stacks podem ser facilmente apagadas e criadas. Com isso, o desenvolvimento em equipe também é facilitado, podendo cada integrante ter a aplicação rodando em conta própria.
• API Gateway:
  • responsável pela comunicação do cliente (usuário) com as funções lambda correspondentes a cada rota.
• Bucket S3:
  • armazena arquivos enviados por usuários em pastas correspondentes à forma de pagamento (dinheiro/, outros/). Também utiliza de uma pasta com arquivos temporários (temp/) para guardar momentaneamente imagens ainda não classificadas.
• CloudWatch:
  • utilizado para monitoramento de atividades, como execuções de funções lambda e da state machine.
• State Machine (Step Functions):
  • realiza a orquestração das funções lambda, para a formulação da rota api/v1/invoice.
• Grafana:
  • disponibiliza um dashboard para fácil monitoramento de recursos.

Funções Lambda

• MainPage

  • Fornece a página web (arquivo HTML).

• InvoiceProxy

  • Recebe a requisição de POST /api/v1/invoice, realizando sua decodificação, armazenando o arquivo enviado em /temp/ no bucket S3 e chamando a PostInvoiceStateMachine (state machine que engloba ExtractInfo, RefineData e ResultHandler). Após ter sua resposta, retorna-a à API Gateway.

• ExtractInfo

  • Utiliza do Textract para extração de informações da nota fiscal armazenada em /temp/, no Bucket S3. Organiza os dados extraídos e os encaminha a RefineData.

• RefineData

  • Utiliza de NLTK para tokenização do texto, o qual é encaminhado a uma LLM (Nova Micro) para buscar informações no texto extraído e gerar o JSON desejado. Os resultados da LLM são misturados com resultados do Textract para formar o JSON que será encaminhado ao usuário.

• ResultHandler

  • Com o caminho da imagem em /temp/, encaminha o arquivo à pasta correspondente, de acordo com a forma de pagamento identificada. Também retorna o resultado de RefineData, a ser enviado ao usuário.

📂 Estrutura do Projeto

sprints-4-5-6-pb-aws-janeiro/
├── assets/
│   └── ...
├── dataset/
│   └── NFs.zip
├── Docs/
│   └── Diagram.excalidraw
├── events/
│   └── ...
├── functions/
│   ├── ExtractInfo/
│   │   ├── __init__.py
│   │   ├── ExtractInfo.py
│   │   └── requirements.txt
│   ├── InvoiceProxy/
│   │   ├── __init__.py
│   │   ├── InvoiceProxy.py
│   │   ├── StoreInBucket.py
│   │   └── requirements.txt
│   ├── MainPage/
│   │   ├── __init__.py
│   │   ├── MainPage.py
│   │   ├── Index.html
│   │   ├── requirements.txt
│   ├── RefineData/
│   │   ├── __init__.py
│   │   ├── RefineData.py
│   │   └── requirements.txt
│   ├── ResultHandler/
│   │   ├── __init__.py
│   │   ├── ResultHandler.py
│   │   └── requirements.txt
├── layers/
│   └── nltk-dependencies.zip
├── PostInvoiceStateMachine/
│   └── PostInvoiceStateMachine.asl.json
├── .gitignore
├── README.md
├── requirements.txt
├── run-local-api.sh
├── samconfig.toml
└── template.yaml

✍️ Organização da Equipe

As tarefas foram organizadas em cards, por meio da ferramenta Trello.

Diariamente, reuniões foram realizadas com o objetivo de alinhar objetivos, trocar ideias e solucionar problemas.

🚧 Desafios e Soluções

Abaixo, uma tabela com alguns desafios e soluções encontradas.

Contexto	Desafio	Solução	Exemplos de Referências Usadas
Queria-se montar uma estrutura com conexão direta entre APi Gateway e Step Functions	CRealizar essa conexão	Habilitar conexão com serviço de Step Functions e usar Mapping Templates para passar ARN de State Machine em requisição.	Stack Overflow
Foi montada uma estrutura com conexão direta entre APi Gateway e Step Functions	Dificuldade de lidar com Mapping Templates para lidar com conteúdo binário.	Uso de InvoiceProxy como intermédio entre API Gateway e Step Functions	Reunião com instrutor
InvoiceProxy: necessitava-se de processamento de Multipart, para pegar arquivos de formulários e interpretá-los corretamente.	Como realizar essa decodificação.	Uso do pacote requests-toolbelt	PyPi requests-toolbelt, Stack Overflow. Jie Jenn - AWS Tutotiral Z How To Add External Python Libraries to An AWS...
Importação de requests-toolbelt. Para tal, buscou-se criar uma layer.	A importação falhava.	A versão de python utilizada com pip era diferente do ambiente de execução da lambda.	Stack Overflow, Docs - AWS, Reunião com Instrutor
Realização da integração com Step Functions.	Como realizar essa integração.	Uso de Boto3 e StartSyncExecution.	Docs - Boto3, Docs - Boto3 (StartSyncExecution)
Desenvolvimento de lambdas.	Dificuldade de testar as funções e falta de um ambiente separado para desenvolvimento.	Uso do AWS SAM.	Reddit (Testing Lambdas Locally), Docs - AWS (SAM), Reddit (Developing Locally)
Realização de requisições à API.	Velocidade de requisição/resposta excessivamente longa. A depender da imagem enviada, havia ocorrência de Timeout.	Alteração do modelo de IA utilizado.	Experimentos com o catálogo de modelos de Bedrock

👥 Autores

Nome	GitHub	LinkedIn
Dawson Oliveira	@dwsoliv73	Perfil
Eduardo Augusto	@EduAugustoM	Perfil
Guilherme Rodrigues	@guirque	Perfil
Moisés Ximenes	@moises-creator	Perfil

---

🔗 Algumas Outras Referências

• AWS Textract - Documentação
• Processamento de Faturas com Textract
• Fine-tuning LLMs para JSON
• Docs - AWS - Analyzing Document Expense
• Docs - AWS - Textract: AnalyzeExpense
• Srce Cde - How to analyze expense related documents using Analyze Expense - Amazon Textract tutorial p8
• Gregory Sánches - Move and Rename objects within an S3 Bucket using Boto 3
• Boto3 - Docs - Copy
• Docs - AWS - Create RESTful APIs on AWS with OpenAPI Specification (With No Coding)
• Docs - AWS - Working with Lambda environment variables