# IntegraReceitas — Documentação do Projeto

## 1. O que é o Sistema

O **IntegraReceitas** é um sistema desenvolvido para automatizar o processo de recepção, tratamento, validação, armazenamento e integração de receitas arrecadadas pelos agentes arrecadadores junto ao **SIAFIC** (Sistema Único e Integrado de Execução Orçamentária, Administração Financeira e Controle).

O sistema possibilita:
- Importação de arquivos PDF de arrecadação
- Identificação automática das receitas
- Vinculação aos agentes arrecadadores
- Parametrização dos relacionamentos exigidos pelo SIAFIC
- Envio eletrônico dos dados

---

## 2. Objetivos

- Automatizar a importação de arrecadações
- Eliminar digitação manual de receitas
- Padronizar os códigos de receitas
- Controlar agentes arrecadadores
- Controlar bancos e agências
- Controlar fontes de recursos
- Gerenciar integrações com o SIAFIC
- Manter histórico de envios
- Controlar status das integrações
- Garantir rastreabilidade dos lançamentos

---

## 3. Módulos do Sistema

### 3.1 Painel
Tela inicial com indicadores gerenciais:
- Quantidade de recebimentos cadastrados
- Quantidade de integrações realizadas
- Quantidade de integrações pendentes
- Quantidade de erros
- Valores arrecadados

### 3.2 Módulo de Recebimentos
Responsável pelo registro das receitas arrecadadas.

**Funcionalidades:**
- Filtros por Data Inicial, Data Final, Agente Arrecadador, Banco e Código de Receita
- Seleção do agente arrecadador e banco
- Importação de PDF: upload, leitura automática, identificação de data, receitas e valores
- Tratamento das receitas: visualizar, alterar, excluir individualmente ou em lote
- Totalização automática
- Gravação do recebimento

### 3.3 Módulo de Envio ao SIAFIC
Responsável pela integração dos recebimentos.

**Status possíveis:**
- `PENDENTE` — aguardando envio
- `ENVIADO` — integrado com sucesso
- `ERRO` — falha na integração

**Funcionalidades:**
- Listagem de recebimentos
- Visualização completa (dados, receitas, valores, documentos)
- Envio manual individual
- Tratamento de erros (401, 404, 500, respostas HTML inválidas)
- Exclusão de recebimentos não integrados

### 3.4 Módulo de Agentes Arrecadadores
Cadastro dos agentes responsáveis pela arrecadação.
- Campos: Nome, Código do Agente, Banco vinculado, Agência vinculada
- Funcionalidades: Incluir, Editar, Excluir, Consultar

### 3.5 Módulo de Bancos
Cadastro dos bancos arrecadadores.
- Campos: Nome, Código do Banco
- Funcionalidades: Incluir, Editar, Excluir, Consultar

### 3.6 Módulo de Agências Bancárias
Controle das agências vinculadas aos bancos.
- Campos: Banco, Número da Agência
- Funcionalidades: Incluir, Editar, Excluir, Consultar

### 3.7 Módulo de Códigos de Receita
Cadastro das receitas arrecadadas.
- Campos: Código, Descrição
- Máscara automática de formatação (ex: `1.2.3.4.56.7.8.90.12`)
- Funcionalidades: Incluir, Editar, Excluir, Consultar

### 3.8 Módulo de Relacionamentos SIAFIC

**Relacionamento de Bancos:**
- Banco Interno → Conta SIAFIC
- Campos: Banco, Código do Banco, Conta SIAFIC

**Relacionamento de Credores:**
- Agente Arrecadador → Credor SIAFIC
- Campos: Agente, Código do Agente, Código Credor SIAFIC

### 3.9 Módulo de Fontes de Recursos
Associação da receita à fonte de recursos.
- Campos: Exercício, Receita, Fonte

### 3.10 Módulo de Configuração SIAFIC
- Configuração da Conexão: URL, Token, Usuário, Senha
- Dados do Órgão: Código, Nome, Exercício
- Ambiente: Homologação ou Produção
- Tipo de Integração: API REST ou Arquivo TXT/XML

### 3.11 Módulo De-Para
Mapeamento de campos do sistema para os campos exigidos pelo SIAFIC.

**Campos obrigatórios:**
- `CD_ORGAO`
- `NUM_PLANO_CONTAS`
- `DS_PLANO_CONTAS`
- `NUM_FONTE_RECURSO`
- `DT_CREDITO`
- `VALOR`
- `CD_BANCO`
- `CD_AGENCIA`
- `CONTA_RECEBEDORA`

**Campos opcionais:**
- `HISTORICO`

---

## 4. Regras de Integração

- Validação prévia das informações antes do envio
- Possibilidade de envio automático após gravação
- Texto padrão de observações enviado ao SIAFIC
- Teste de conexão para validar URL, Token e disponibilidade da API

---

## 5. Segurança

- Ocultação de Token e URL
- Controle por perfil administrativo
- Validação de dados obrigatórios
- Tratamento de erros de API
- Controle de tentativas de envio

---

## 6. Ajustes Pendentes Informados pelo Cliente

1. **Campo "Tipo de Documento"**: incluir na tela de recebimento o campo tipo de documento (valor fixo: `DOC`), e adicioná-lo também na tela de configuração SIAFIC no De-Para da API. O número do documento já existe na tela de recebimento.

2. **Bug no valor total**: ao fazer upload de PDF, às vezes o valor total não aparece.

3. **Relacionamento de agentes**: bloquear para que um mesmo agente não possa ser relacionado a mais de um banco. Deve ser possível mudar o banco relacionado, mas nunca duplicar o vínculo.

---

## 7. Credenciais e Acesso Recebidos

| Item | Valor |
|---|---|
| URL do Sistema | `http://52.67.155.80:8079/2727/` |
| Token JWT | Fornecido pelo cliente (arquivo `url_e_chave.docx`) |
| Documentação da API | [Postman — Fator Sistemas SIAFIC](https://www.postman.com/fatorsistemas/fator-sistemas-siafic/request/urlnv5k/arrecadao?sideView=agentMode) |

---

## 8. Arquivos Recebidos do Cliente

| Arquivo | Tamanho | Conteúdo |
|---|---|---|
| `url_e_chave.docx` | 12,8 KB | URL, Token JWT e link da documentação Postman |
| `DESCRITIVO_FUNCIONAL_DO_SISTEMA_INTEGRARECEITAS.docx` | 29,1 KB | Descritivo funcional completo do sistema |
| `IntegraReceitas2.rar` | 76,29 MB | Arquivo compactado (provável código-fonte do sistema) |
| `BacBanco_integrareceitas2kup_1` | 35,9 KB | Arquivo binário (provável backup do banco de dados) |
| `itau_2_.pdf` | 14,4 KB | Modelo de PDF do Itaú Unibanco |
| `Bradesco_2_.pdf` | 14,4 KB | Modelo de PDF do Bradesco |
| `foccus_2_.pdf` | 14,1 KB | Modelo de PDF do Foccus |
| `Banco_do_Brasil.pdf` | 14,4 KB | Modelo de PDF do Banco do Brasil |

---

## 9. Modelos de PDF Recebidos (Boletins de Arrecadação)

Os PDFs recebidos são **Boletins Diários de Arrecadação** do SAAE Valença (CNPJ 16.176.067/0001-11), gerados pelo sistema da Fator Sistemas.

### Bancos e valores do dia 12/06/2026 (exemplo)

| Banco | Código | Total Arrecadado |
|---|---|---|
| Banco do Brasil | 1 | R$ 93.906,91 |
| Bradesco | 237 | R$ 18.936,08 |
| Itaú Unibanco | 341 | R$ 10.841,82 |
| Foccus | 836 | R$ 873,15 |

### Estrutura dos PDFs

Todos os PDFs seguem o mesmo layout com os seguintes campos:
- **Cabeçalho:** Nome do órgão, CNPJ, endereço, banco, período de crédito
- **Linhas de receita:** Valor + Status + Código + Descrição
- **Totalizadores:** Total Arrecadado, Total Convênio, Total Líquido, Tarifa Bancária

**Exemplo de linha de receita:**
```
7.975,14   Lançada - 169950110100  Serviços de Cap. e Abast. de Água
```

### Códigos de receita presentes nos modelos

| Código | Descrição |
|---|---|
| 169950110100 | Serviços de Cap. e Abast. de Água |
| 169950110900 | Outras Receitas Diversas da Água |
| 169950120000 | Multas e Juros por Pgto. em Atraso |
| 169950130000 | Dívida Ativa Não Tributária |
| 169950140000 | Multas e Juros s/ Dív Ativa Não Tri |
| 169950210100 | Serviços de Coleta, Trat. de Esgoto |
| 169950910100 | Serviços de Manut. de Ramal de Água |
| 169950910200 | Serviços de Religamento de Água |
| 169950910600 | Serviços de Manut. de Ramal de Esgo |
| 169999010100 | Serviços de Expediente Administrativo |

---

*Documento gerado com base exclusivamente nos arquivos e informações fornecidos pelo cliente.*