# Automação de Coleta de Dados — SPED Fiscal

Este documento especifica a automação de coleta, os critérios técnicos, fluxo operacional e instruções para usuários e manutenção.

## Objetivos
- Extrair dados automaticamente dos endpoints do SPED Fiscal e consolidar saídas em formatos acessíveis (TXT, JSON, HTML).
- Permitir entrada de dados em diferentes formatos, com fallback para CSV.
- Garantir validação integrada e segurança no acesso à API.

## Fluxo da Automação

```
[Fonte de dados] --> [Normalização (CSV/JSON)] --> [Payload SPED]
       |                                  |                
       v                                  v                
  (CSV: D100/K230/K235)          (JSON opcional)          
                      \            /                     
                       \          /                      
                        [Cliente HTTP]                   
                              |                          
                   +----------+-----------+              
                   |   /api/fiscal/sped   |              
                   |  generate   check    |              
                   +----------+-----------+              
                              |                          
               [TXT gerado]  [Relatório Issues]          
                      |              |                   
                      v              v                   
           storage/sped/default   HTML/JSON              
```

## Critérios Técnicos

### Frequência de coleta
- Agendada via CLI com `--interval` (minutos). Recomenda-se:
  - Ambiente de homologação: `--interval=60` (hora em hora).
  - Produção com dados estáveis: `--interval=360` (a cada 6 horas). Ajustar conforme volume.

### Validação e tratamento de erros
- Validação no servidor via `POST /api/fiscal/sped/check` com `SpedValidator` (inclui checagem de `C190`, `D190`, `E110`, entre outras).
- No cliente (CLI e UI):
  - Validação de JSON em tempo real na UI.
  - Conversão de CSV com cabeçalhos esperados; linhas inválidas são normalizadas quando possível e reportadas no relatório.
- Tratamento de erros HTTP (timeouts, status não 2xx) com registro em JSON e backoff simples.

### Apresentação alternativa dos dados
- Geração de `TXT` oficial do SPED.
- Saída `JSON` com o corpo retornado pela API.
- Relatório `HTML` com issues de validação e status.
- Na UI: badge dinâmico indicando blocos ativos conforme dados fornecidos.

### Protocolos de segurança
- Recomendado uso de chave de API (`X-API-Key`) por tenant/ambiente, com verificação no middleware.
- HTTPS em produção (TLS), mesmo em rede interna.
- Rate limiting por IP/chave de API.
- Logs de auditoria (endpoint, parâmetros essenciais, resultado) sem armazenar dados sensíveis desnecessariamente.
- Sanitização de entrada (CSV/JSON) e limite de tamanho por requisição.

### Chave de API (SPED_API_KEY)
- Configuração: defina `SPED_API_KEY` via variável de ambiente ou no `.env`.
- Cabeçalho: utilize `X-API-Key` junto de `X-Tenant-Id` nas requisições.
- Escopo: permitido nos endpoints `POST /api/fiscal/sped/validate`, `POST /api/fiscal/sped/generate` e `POST /api/fiscal/sped/check`.
- Restrição: `POST /api/fiscal/sped/auto` não aceita `X-API-Key` — requer autenticação normal com token (`Authorization: Bearer ...`) e permissão `fiscal.sped.manage`.
- Exemplo (cURL):
  - `curl -X POST http://localhost:8000/api/fiscal/sped/validate -H 'X-Tenant-Id: default' -H 'X-API-Key: TEST-SPED-KEY'`
  - `curl -X POST http://localhost:8000/api/fiscal/sped/generate -H 'X-Tenant-Id: default' -H 'X-API-Key: TEST-SPED-KEY' -d '{"year":2025,"month":11,"perfil":"A","ind_ativ":1,"cod_fin":0,"cod_ver":"017"}'`
- Em testes/integrações PHP, é possível definir: `putenv('SPED_API_KEY=TEST-SPED-KEY'); $_ENV['SPED_API_KEY'] = 'TEST-SPED-KEY';`.

## Implementação

### Script CLI de coleta
- Arquivo: `scripts/sped_collect.php`
- Parâmetros principais:
  - `--year=AAAA`, `--month=MM` (obrigatórios)
  - `--generate` ou `--check` (default: generate)
  - `--d100-csv=path`, `--k230-csv=path`, `--k235-csv=path`
  - `--icms_rate`, `--pis_rate`, `--cofins_rate`, `--ipi_rate`, `--icms_st_rate` (percentual)
  - `--output-dir=path` (default `storage/sped/default`)
  - `--api-key=XYZ` (opcional)
  - `--interval=MIN` (opcional; loop contínuo)
- Saídas:
  - `sped_collect_<timestamp>.json` (resposta da API)
  - `sped_collect_<timestamp>.txt` (quando disponível)
  - `sped_check_<timestamp>.html` (relatório de validação)

### Interface SPED
- Importação CSV para D100, K230 e K235 através de inputs de arquivo, com mapeamento automático para JSON.
- Remoção de rótulos de teste e exemplos visuais; comunicação focada e profissional.
- Validação de JSON e atualização de badge de blocos ativos.

## Qualidade dos Dados
- Datas em formatos aceitos (`YYYY-MM-DD`, `DD/MM/YYYY`, timestamp) — normalizadas internamente.
- Cabeçalhos CSV obrigatórios conforme seção da interface.
- Valores numéricos não negativos em consolidações (`D190`).
- Coerência entre bases e alíquotas (checadas pelo validador).

## Instruções para Usuários Finais
- Na interface `/fiscal/sped`:
  - Preencha competência, taxas e, se necessário, importe CSV para D100/K230/K235.
  - Use “Gerar prévia” para obter o TXT e “Validar SPED gerado” para relatório.
- No CLI:
  - Exemplo: `php scripts/sped_collect.php --year=2025 --month=11 --check --d100-csv=storage/sped/default/d100.csv --output-dir=storage/sped/default`
  - Em execução contínua: `php scripts/sped_collect.php --year=2025 --month=11 --generate --interval=360`

## Manutenção
- Verificar periodicamente o diretório de saída e o relatório de validação.
- Atualizar mapeamentos CSV caso os modelos de dados mudem.
- Revisar chaves de API, limites de taxa e certificados TLS.
- Monitorar logs de auditoria e tratar alertas de inconsistência.