# Proposta Comercial

## Motor de Leitura e Sincronizacao de NFS-e por Municipio

Data: 17/06/2026

## 1. Objetivo

Desenvolver um motor de leitura automatizado para consultar documentos fiscais eletronicos de servico (NFS-e/DF-e) no Ambiente de Dados Nacional da NFS-e (ADN), por municipio, e popular novas tabelas em um banco de dados legado MySQL ja utilizado por uma aplicacao CodeIgniter.

O objetivo principal e permitir que a aplicacao existente passe a consultar registros de NFS-e sincronizados, sem necessidade de reescrever o sistema legado ou alterar sua tecnologia principal.

## 2. Proposta Tecnica

A solucao proposta consiste em um servico containerizado, independente da aplicacao CodeIgniter, responsavel por:

- Ler configuracoes de municipios habilitados.
- Utilizar certificados digitais A1 por municipio para autenticacao nas APIs da NFS-e.
- Consultar periodicamente a API de distribuicao do ADN por NSU.
- Armazenar os documentos retornados em novas tabelas no banco MySQL legado.
- Controlar o ultimo NSU sincronizado por municipio.
- Registrar logs, erros e status de sincronizacao.

## 3. Tecnologia Recomendada

### Motor de leitura

Tecnologia recomendada: Python 3.12.

Justificativa:

- Boa maturidade para rotinas batch e workers.
- Excelente suporte para XML, parsing e validacao.
- Boa compatibilidade com requisicoes HTTPS usando certificado digital.
- Baixo acoplamento com a aplicacao legado.
- Facilidade para execucao em container Docker.

### Banco de dados

Banco de dados: MySQL legado existente.

A proposta considera a criacao de novas tabelas especificas para NFS-e, sem alterar as tabelas atuais da aplicacao CodeIgniter, salvo necessidade aprovada previamente.

### Containerizacao

Tecnologia: Docker / Docker Compose.

O motor sera executado como um container separado, conectado ao mesmo banco MySQL utilizado pela aplicacao legado.

## 4. Arquitetura Proposta

```text
Aplicacao CodeIgniter legado
  -> consulta banco MySQL existente

Motor NFS-e Python
  -> executa em container Docker
  -> le certificados digitais em volume seguro
  -> consulta APIs ADN/NFS-e por municipio
  -> grava novas tabelas nfse_* no MySQL legado

Banco MySQL legado
  -> mantem tabelas atuais
  -> recebe novas tabelas de NFS-e
```

## 5. Estrutura de Certificados

Os certificados digitais nao devem ser gravados diretamente no banco de dados.

Modelo recomendado:

```text
certificados-digitais/
  3550308/
    certificado.pfx
  3304557/
    certificado.pfx
```

No banco ficarao apenas metadados:

- Codigo IBGE do municipio.
- Caminho do arquivo do certificado.
- Chave de ambiente para senha do certificado.
- Data de validade.
- Indicador de ativo/inativo.

As senhas dos certificados deverao ficar fora do banco, preferencialmente em variaveis de ambiente ou secret manager.

## 6. Tabelas Previstas

As tabelas podem ser ajustadas conforme o padrao do banco legado, mas a proposta inicial contempla:

- nfse_municipios
- nfse_certificados
- nfse_sync_state
- nfse_documentos
- nfse_eventos
- nfse_sync_logs

### nfse_documentos

Tabela principal para armazenamento dos documentos fiscais sincronizados.

Campos previstos:

- Codigo do municipio de contexto.
- NSU.
- Chave de acesso.
- Tipo do documento.
- Municipio emissor.
- Municipio de incidencia.
- CNPJ/CPF do prestador.
- CNPJ/CPF do tomador.
- Data de emissao.
- Status.
- XML bruto.
- Dados principais extraidos.
- Data/hora de recebimento.

## 7. Escopo Incluido

O escopo desta proposta contempla:

- Criacao da estrutura Docker do motor.
- Criacao das migrations SQL para novas tabelas no MySQL.
- Implementacao do cadastro/configuracao tecnica de municipios.
- Leitura de certificados digitais A1 em volume seguro.
- Implementacao da consulta por NSU.
- Controle de ultimo NSU por municipio.
- Persistencia dos XMLs brutos.
- Extracao dos principais campos para consulta.
- Registro de logs de sincronizacao.
- Tratamento basico de erros e retentativas.
- Documentacao de instalacao e operacao.
- Validacao em ambiente de homologacao/producao restrita, se houver certificado e acesso disponiveis.

## 8. Fora do Escopo

Nao estao incluidos nesta estimativa:

- Desenvolvimento de telas no CodeIgniter.
- Painel administrativo para upload/gestao de certificados.
- Normalizacao completa de todos os campos da NFS-e.
- Validacao XSD completa de todos os XMLs.
- Rotina avancada de auditoria fiscal.
- Integracao com cofres de segredo como Vault, AWS KMS ou similares.
- Migracao ou refatoracao da aplicacao legado.
- Obtencao, emissao ou renovacao dos certificados digitais dos municipios.
- Tratativas juridicas, convenios ou autorizacoes junto aos municipios.

Esses itens podem ser estimados separadamente.

## 9. Premissas

- O cliente fornecera acesso ao banco MySQL legado.
- O cliente fornecera os certificados digitais A1 dos municipios que serao sincronizados.
- O cliente fornecera as senhas dos certificados em canal seguro.
- O acesso a API da NFS-e/ADN estara liberado para os certificados utilizados.
- O ambiente permitira execucao de containers Docker.
- As novas tabelas poderao ser criadas no banco existente.
- A primeira versao priorizara XML bruto e campos principais para consulta.

## 10. Estimativa

Estimativa de esforco: 65 horas.

Valor hora: R$ 120,00.

Valor total estimado: R$ 7.800,00.

## 11. Prazo

Prazo estimado de execucao: 8 a 13 dias uteis, considerando disponibilidade de acesso ao banco, certificados e ambiente de testes.

## 12. Entregaveis

- Container do motor de leitura NFS-e.
- Scripts/migrations SQL das novas tabelas.
- Codigo fonte do worker de sincronizacao.
- Configuracao Docker/Docker Compose.
- Documentacao de instalacao.
- Documentacao operacional.
- Registro das premissas de seguranca para certificados.

## 13. Observacoes Importantes

O ADN nao deve ser tratado como uma fonte publica para captura irrestrita de todas as notas do Brasil. A distribuicao de documentos depende da identidade autenticada e do papel do interessado. Para operacao por municipio, a solucao depende de certificado/autorizacao correspondente a cada municipio atendido.

Por seguranca, os certificados digitais devem ser mantidos fora do banco de dados, em volume seguro, com permissao restrita de leitura para o container do motor.

## 14. Condicoes Comerciais

Valor total estimado: R$ 7.800,00.

Forma de pagamento sugerida:

- 50% no inicio do projeto.
- 50% na entrega do MVP funcional.

A estimativa podera ser revisada caso sejam identificadas restricoes de acesso, alteracoes relevantes de escopo ou necessidade de normalizacao fiscal mais profunda.