# PES2B Contábil Parser API

Versão documentada: **1.1.0**  
URL de produção sugerida: `https://contabil-parser.pes2b.com`

## Visão geral

A PES2B Contábil Parser API processa planilhas contábeis XLSX/XLS de grande volume sem transportar centenas de milhares de linhas pelo n8n. O serviço concentra leitura, validação, diagnóstico, persistência e reimportação no backend.

## Autenticação

Todos os endpoints `/v1/*` exigem:

```http
X-API-Key: SUA_CHAVE
```

O endpoint `GET /health` é público.

## Endpoints

### GET /health

Retorna disponibilidade do serviço.

### POST /v1/analyze

Analisa o arquivo sem gravar no banco. Recebe `multipart/form-data` com:

- `file` obrigatório — XLSX ou XLS;
- `batch_size` opcional — 100 a 10000, padrão 1000.

Retorna SHA-256, quantidade de linhas, totais de débito/crédito, diferença, datas, tipos, quantidade de `id_movim_finan`, linhas com débito e crédito simultâneos e quantidade de lotes desbalanceados.

### POST /v1/diagnose-unbalanced

Analisa sem gravar e retorna somente os grupos `id_movim_finan` desbalanceados, com as linhas originais de cada grupo.

Exemplo de resposta resumida:

```json
{
  "success": true,
  "diagnostico": "ARQUIVO_DESBALANCEADO",
  "nome_arquivo": "comercio2026.xlsx",
  "resumo": {
    "total_linhas": 253933,
    "total_movimentos_financeiros": 84820,
    "total_debito": 8480733.30,
    "total_credito": 8676943.30,
    "diferenca": -196210.00,
    "quantidade_grupos_desbalanceados": 10
  },
  "grupos_desbalanceados": []
}
```

### POST /v1/process

Processa e grava a importação no PostgreSQL.

Campos multipart:

- `codigo_dominio` obrigatório;
- `modo_importacao`: `NORMAL` ou `REIMPORTAR`;
- `batch_size` opcional, padrão 1000;
- `file` obrigatório.

Regras:

- o arquivo precisa estar globalmente balanceado;
- `NORMAL` rejeita o mesmo hash quando já existe importação ativa;
- `REIMPORTAR` cria a nova carga e só marca a anterior como `SUBSTITUIDO` depois que a nova importação for totalmente gravada e validada;
- o retorno inclui `importacao_id`, `inserted_rows`, totais e status.

## Exemplos cURL

### Analyze

```bash
curl -X POST 'https://contabil-parser.pes2b.com/v1/analyze' \
  -H 'X-API-Key: SUA_CHAVE' \
  -F 'file=@comercio2026.xlsx' \
  -F 'batch_size=1000'
```

### Diagnose unbalanced

```bash
curl -X POST 'https://contabil-parser.pes2b.com/v1/diagnose-unbalanced' \
  -H 'X-API-Key: SUA_CHAVE' \
  -F 'file=@comercio2026.xlsx'
```

### Process

```bash
curl -X POST 'https://contabil-parser.pes2b.com/v1/process' \
  -H 'X-API-Key: SUA_CHAVE' \
  -F 'codigo_dominio=469' \
  -F 'modo_importacao=NORMAL' \
  -F 'batch_size=1000' \
  -F 'file=@comercio2024.xlsx'
```

## Códigos de erro principais

| HTTP | Situação |
|---:|---|
| 400 | Formato inválido, `batch_size` fora do intervalo ou modo de importação inválido |
| 401 | API key inválida ou ausente |
| 404 | Empresa não cadastrada |
| 409 | Empresa inativa ou arquivo já possui importação ativa |
| 413 | Arquivo acima do limite configurado |
| 422 | Arquivo desbalanceado ou validação de requisição |
| 500 | Falha interna do serviço |

## Segurança

- Nunca publique a API Key no GitHub.
- Use credenciais do n8n ou variáveis de ambiente.
- O parser não deve expor credenciais PostgreSQL ao cliente.
- O endpoint de diagnóstico é somente leitura e não grava no banco.

## Swagger

A especificação OpenAPI está em `openapi.json` e a documentação interativa em `/swagger/` no site de documentação.