# Liquidacao

Endpoint para disparar o processamento de arquivos de liquidacao (ACMP615) da Nuclea.

## Ciclos de Liquidacao

A Nuclea processa liquidacoes em dois ciclos diarios:

| Ciclo    | Horario | Descricao                                    |
|----------|---------|----------------------------------------------|
| Manha    | 08:30   | Processa pagamentos do dia anterior (tarde)  |
| Tarde    | 16:30   | Processa pagamentos do dia atual (manha)     |

::: info Processamento Automatico
O sistema processa automaticamente os arquivos ACMP615 apos cada ciclo (08:35 e 16:35). Use este endpoint apenas para reprocessamento manual ou testes.
:::

## Disparar Processamento

Agenda um job para baixar e processar os arquivos de liquidacao do FTP da Nuclea.

```
POST /settlements/trigger
```

### Corpo da Requisicao

Todos os campos sao opcionais. Se nao informados, serao usados os valores padrao.

| Campo   | Tipo    | Padrao       | Descricao                              |
|---------|---------|--------------|----------------------------------------|
| `cycle` | integer | ciclo atual  | Ciclo de liquidacao: `1` (manha) ou `2` (tarde) |
| `date`  | string  | data atual   | Data para buscar arquivos (YYYY-MM-DD) |

### Exemplo de Requisicao

::: code-group

```bash [cURL]
curl -X POST "https://api.monetarie_npc.com.br/api/v1/central/settlements/trigger" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "cycle": 1,
    "date": "2026-02-15"
  }'
```

```javascript [JavaScript]
const response = await fetch(
  "https://api.monetarie_npc.com.br/api/v1/central/settlements/trigger",
  {
    method: "POST",
    headers: {
      "X-API-Key": "pk_live_abc123def456",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      cycle: 1,
      date: "2026-02-15"
    }),
  }
);

const data = await response.json();
console.log(data);
```

```python [Python]
import requests

url = "https://api.monetarie_npc.com.br/api/v1/central/settlements/trigger"
headers = {
    "X-API-Key": "pk_live_abc123def456",
    "Content-Type": "application/json"
}
payload = {
    "cycle": 1,
    "date": "2026-02-15"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

:::

### Resposta de Sucesso

**Status:** `202 Accepted`

```json
{
  "success": true,
  "data": {
    "job_id": 12345,
    "date": "2026-02-15",
    "cycle": 1,
    "status": "queued"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

::: tip Processamento Assincrono
O endpoint retorna imediatamente com status `202 Accepted` e um `job_id`. O processamento ocorre em segundo plano. Use webhooks para ser notificado quando o processamento for concluido.
:::

### Erros Possiveis

| Codigo | Erro                  | Descricao                                      |
|--------|----------------------|------------------------------------------------|
| `500`  | `JOB_QUEUE_FAILED`   | Falha ao enfileirar o job de processamento     |

---

## Fluxo de Liquidacao

O diagrama abaixo ilustra o fluxo completo de processamento de liquidacao:

```
┌─────────────────────────────────────────────────────────────────┐
│                    Fluxo de Liquidacao                         │
└─────────────────────────────────────────────────────────────────┘

  ┌──────────┐         ┌──────────┐         ┌──────────┐
  │  API     │         │  Oban    │         │  FTP     │
  │ Request  │─────────│   Job    │─────────│  Nuclea  │
  └──────────┘         └──────────┘         └──────────┘
       │                    │                    │
       │  POST /trigger     │                    │
       │───────────────────▶│                    │
       │                    │                    │
       │  202 Accepted      │  Download ACMP615  │
       │◀───────────────────│───────────────────▶│
       │  (job_id: 12345)   │                    │
       │                    │◀───────────────────│
       │                    │   (arquivo .txt)   │
       │                    │                    │
       │              ┌─────┴─────┐              │
       │              │  Parser   │              │
       │              │  ACMP615  │              │
       │              └─────┬─────┘              │
       │                    │                    │
       │              ┌─────┴─────┐              │
       │              │ Reconcilia│              │
       │              │  Boletos  │              │
       │              └─────┬─────┘              │
       │                    │                    │
       │              ┌─────┴─────┐              │
       │              │  Webhook  │              │
       │              │  boleto.  │              │
       │              │  settled  │              │
       │              └───────────┘              │
```

## Arquivo ACMP615

O arquivo ACMP615 e o arquivo de liquidacao da Nuclea que contem os pagamentos processados.

### Estrutura do Arquivo

| Tipo de Registro | Descricao                          |
|------------------|-----------------------------------|
| `00`             | Header do arquivo                  |
| `20`             | Registro de pagamento              |
| `99`             | Trailer do arquivo                 |

### Campos do Registro de Pagamento (Tipo 20)

| Posicao  | Campo              | Descricao                    |
|----------|-------------------|------------------------------|
| 1-2      | tipo_registro     | Sempre "20"                  |
| 3-13     | nosso_numero      | Referencia do boleto         |
| 14-30    | valor_pago        | Valor pago em centavos       |
| 31-38    | data_pagamento    | Data do pagamento (YYYYMMDD) |
| 39-46    | hora_pagamento    | Hora do pagamento (HHMMSS)   |

## Webhooks Relacionados

Apos o processamento de liquidacao, os seguintes webhooks podem ser disparados:

| Evento            | Descricao                                    |
|-------------------|---------------------------------------------|
| `boleto.settled`  | Boleto liquidado - fundos transferidos       |
| `cycle.completed` | Ciclo de liquidacao concluido                |

Para mais detalhes, consulte a documentacao de [Webhooks](/webhooks/).

## Proximos Passos

- [Health Check](/api/health) - Verificar configuracao do FTP
- [Fluxo de Liquidacao](/guides/settlement-flow) - Guia completo do processo
- [Webhooks](/webhooks/) - Configurar notificacoes