# ClientFlow v4.9.2 — External API Sync for Reconciliation

Esta versão liga a área de Reconciliação às APIs externas, de forma conservadora.

## Objetivo

Preparar informação solta que existe fora do ClientFlow para ser analisada pelo operador:

- documentos Jasmin sem oportunidade;
- faturas/pro-formas/orçamentos criados manualmente;
- vendas/encomendas Odoo sem oportunidade;
- envios Packlink sem oportunidade;
- comprovativos e pedidos externos já suportados na v4.9.1.

## Regra de segurança

A sincronização externa **não cria oportunidades automaticamente** e **não confirma pagamentos**.

Fluxo:

```text
API externa
  ↓
item de reconciliação
  ↓
operador decide:
  - ligar a oportunidade existente
  - criar oportunidade
  - ignorar
```

## Novos componentes

```text
app/external_reconciliation_sync.py
scripts/sync_external_reconciliation.py
```

A página `/reconciliation` recebeu botões para:

```text
Sincronizar Jasmin
Sincronizar Odoo
Sincronizar Packlink
Sincronizar APIs externas
```

## Script

```bash
cd /mnt/ssd/home/plx/clientflow_backend
source .venv/bin/activate 2>/dev/null || true

PYTHONPATH=. python scripts/sync_external_reconciliation.py --all
PYTHONPATH=. python scripts/sync_external_reconciliation.py --jasmin --limit 100
PYTHONPATH=. python scripts/sync_external_reconciliation.py --odoo --days 90
PYTHONPATH=. python scripts/sync_external_reconciliation.py --packlink
```

## Configuração

A sincronização respeita os flags existentes:

```env
JASMIN_ENABLED=true
ODOO_ENABLED=true
PACKLINK_ENABLED=true
```

Se um sistema estiver desativado, o script reporta `skipped` e não falha.

## Frequência sugerida

```text
Jasmin documentos       15 min
Odoo vendas             15-30 min
Packlink envios         30 min
Reconciliação completa  1 vez por dia
```

Exemplo systemd timer para execução geral:

```ini
[Unit]
Description=ClientFlow external reconciliation sync

[Service]
Type=oneshot
WorkingDirectory=/mnt/ssd/home/plx/clientflow_backend
Environment=PYTHONPATH=.
ExecStart=/mnt/ssd/home/plx/clientflow_backend/.venv/bin/python scripts/sync_external_reconciliation.py --all
```

Timer:

```ini
[Unit]
Description=Run ClientFlow external reconciliation sync every 15 minutes

[Timer]
OnBootSec=2min
OnUnitActiveSec=15min
Persistent=true

[Install]
WantedBy=timers.target
```

## O que não faz

```text
Não apaga documentos.
Não substitui orçamentos.
Não emite faturas.
Não confirma pagamentos.
Não fecha oportunidades.
Não cria oportunidades automaticamente.
```

## Validação

Depois do deploy:

```bash
PYTHONPATH=. python -m compileall app scripts tests
PYTHONPATH=. pytest -q
PYTHONPATH=. python scripts/sync_external_reconciliation.py --all
```

Depois abrir `/reconciliation` e confirmar os candidatos.