# Fluxos: Modulo Finance - Sincronizacao

---

## 15.1 Executar Sincronizacao Manual

```
Usuario
  ↓
Finance → Dashboard ou Config → Botao "Sincronizar"
  ↓
POST /finance/sync_info (preview)
  ↓
SyncController@getSyncInfo
  ↓
ClientsSyncService::preview()
InvoiceCreationService::preview()
RecurrenceSyncService::preview()
PendingChargesGenerationService::preview()
ChargesSyncService::preview()
  ↓
JSON {pending_updates[], last_sync}
  ↓
Usuario visualiza preview → Confirma
  ↓
POST /finance/sync/apply
  ↓
SyncController@applySync
  ↓
Verifica janela de lock cron (07:55-08:05, 19:55-20:05) → 429 se bloqueado
Verifica sync ativa (30min) → retorna run existente (idempotente)
  ↓
FinanceSyncRun::create (status='pending')
RunManualFinanceSync::dispatch()
  ↓
JSON {run_id} (HTTP 202)
  ↓
Polling automatico:
POST /finance/sync/progress/{runId} (a cada poucos segundos)
  ↓
FinanceSyncRun (status, steps_done/total, steps_detail, error_message)
  ↓
JSON {progresso}
```

**Tela inicial:** Dashboard ou pagina de sync
**Acao do usuario:** Visualiza preview → confirma → acompanha progresso
**Requisicoes:**
1. `POST /finance/sync_info` (preview)
2. `POST /finance/sync/apply` (executa)
3. `POST /finance/sync/progress/{runId}` (polling)
**Controller:** `SyncController`
**Jobs disparados:** `RunManualFinanceSync`
**Tabelas alteradas:**
- `finance_sync_runs` (INSERT + UPDATE progresso)

**RunManualFinanceSync executa 5 steps em background:**
```
Step 1: ClientsSyncService
  → Asaas API (cria/atualiza/pareia clientes)
  → finance_clients, finance_client_contacts

Step 2: InvoiceCreationService
  → Spedy/Asaas API (emite NFS-e pendentes)
  → finance_charges (nfs_status, nfs_url, id_nfs)

Step 3: RecurrenceSyncService
  → Gera cobrancas de recorrencias ativas
  → finance_charges (INSERT), finance_recurrence (cycle update)

Step 4: PendingChargesGenerationService
  → Iugu/Asaas/Spedy API (emite boletos + NFS-e em lote)
  → finance_charges (bill_url, bill_status, nfs_url)

Step 5: ChargesSyncService
  → Iugu/Asaas API (verifica status de cobrancas)
  → finance_charges (bill_status, paid_at)
```

**APIs chamadas:**
- Asaas (clientes, pagamentos, NFS-e)
- Iugu (pagamentos)
- Spedy (NFS-e)
**Resultado esperado:** Todas as pendencias financeiras processadas
**Possiveis erros:**
- Janela de lock cron → 429
- Sync ja ativa → retorna run existente (nao duplica)
- Nada pendente → 200 sem dispatch
- Erro em step → registrado em finance_sync_runs + finance_logs