# Fluxo de Pagamento via Link (Asaas)

- Painel: Financeiro → Bancos → aba "Asaas" — seção "Gerar Link de Pagamento (Venda)".
- APIs:
- `POST /api/addons/asaas/payment-links` — gera link e cria cobrança.
- `GET /api/addons/asaas/payment-links/{id}` — consulta link gerado.
- `POST /api/addons/asaas/orders/{id}/payment-link` — gera link diretamente por pedido (usa `valor_total` e `cliente_id`).
- Permissões: `addons.asaas.manage` (gerar), `addons.asaas.read` (consultar).

## Pré-requisitos
 - Configurar credenciais: na UI (Financeiro → Bancos → aba Asaas) ou via API `POST /api/addons/asaas/config` com `environment` (`sandbox` ou `production`), `api_key` e opcionalmente `base_url`.
- Autenticação: `POST /api/auth/login` e usar `Authorization: Bearer <token>` e `x-tenant-id`.

## Geração do Link
1. Garante o cliente no Asaas (cria via `customers` se não houver mapeamento).
2. Cria a cobrança (`payments`) com `status` inicial "PENDING".
3. Cria o link (`paymentLinks`) ou usa `invoiceUrl/bankSlipUrl` como fallback.
4. Persiste em `asaas_payment_links` com `status` "aguardando compensação".

### Corpo de requisição
```json
{
  "sale_id": "VENDA-123",
  "client_id": 42,
  "amount_cents": 19990,
  "due_date": "2025-11-30",
  "billing_type": "BOLETO"
}
```

### Via Pedido (POST /api/addons/asaas/orders/{id}/payment-link)
```json
{
  "due_date": "2025-11-30",
  "billing_type": "BOLETO"
}
```
Usa automaticamente `numero` do pedido como `externalReference`, `cliente_id` e `valor_total` do pedido.

### Resposta (201)
```json
{
  "data": {
    "id": 10,
    "sale_id": "VENDA-123",
    "asaas_payment_id": "pay_...",
    "asaas_link_id": "plink_...",
    "link_url": "https://...",
    "status": "aguardando compensação"
  }
}
```

## Logs e Auditoria
- Tabela `asaas_logs` registra endpoint, método, status, payload e resposta.
- `AuditLogger` grava eventos: `save_config`, `create_payment`, `generate_payment_link`.

## Modo Mock para Testes
- Defina `ASAAS_MOCK=true` no ambiente do servidor.
- Endpoints comuns retornam respostas simuladas para testes sem credenciais reais.

## Tratamento de Erros
- `400` configuração ausente.
- `422` campos obrigatórios ausentes.
- `502` erro na API do Asaas (detalhe `status`/`response`).
- `500` erro de banco.