# Settlements

Endpoint to trigger the processing of settlement files (ACMP615) from Nuclea.

## Settlement Cycles

Nuclea processes settlements in two daily cycles:

| Cycle     | Time  | Description                                  |
|-----------|-------|----------------------------------------------|
| Morning   | 08:30 | Processes payments from previous day (afternoon) |
| Afternoon | 16:30 | Processes payments from current day (morning)    |

::: info Automatic Processing
The system automatically processes ACMP615 files after each cycle (08:35 and 16:35). Use this endpoint only for manual reprocessing or testing.
:::

## Trigger Processing

Schedules a job to download and process settlement files from Nuclea's FTP.

```
POST /settlements/trigger
```

### Request Body

All fields are optional. If not provided, default values will be used.

| Field   | Type    | Default       | Description                            |
|---------|---------|---------------|----------------------------------------|
| `cycle` | integer | current cycle | Settlement cycle: `1` (morning) or `2` (afternoon) |
| `date`  | string  | current date  | Date to fetch files (YYYY-MM-DD)       |

### Request Example

::: 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())
```

:::

### Success Response

**Status:** `202 Accepted`

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

::: tip Asynchronous Processing
The endpoint returns immediately with status `202 Accepted` and a `job_id`. Processing occurs in the background. Use webhooks to be notified when processing is complete.
:::

### Possible Errors

| Code   | Error                 | Description                                    |
|--------|----------------------|------------------------------------------------|
| `500`  | `JOB_QUEUE_FAILED`   | Failed to queue the processing job             |

---

## Settlement Flow

The diagram below illustrates the complete settlement processing flow:

```
+------------------------------------------------------------------+
|                    Settlement Flow                                |
+------------------------------------------------------------------+

  +----------+         +----------+         +----------+
  |   API    |         |  Oban    |         |   FTP    |
  | Request  |---------|   Job    |---------|  Nuclea  |
  +----------+         +----------+         +----------+
       |                    |                    |
       |  POST /trigger     |                    |
       |------------------->|                    |
       |                    |                    |
       |  202 Accepted      |  Download ACMP615  |
       |<-------------------|------------------>|
       |  (job_id: 12345)   |                    |
       |                    |<-------------------|
       |                    |   (.txt file)      |
       |                    |                    |
       |              +-----+-----+              |
       |              |  Parser   |              |
       |              |  ACMP615  |              |
       |              +-----+-----+              |
       |                    |                    |
       |              +-----+-----+              |
       |              | Reconcile |              |
       |              |  Boletos  |              |
       |              +-----+-----+              |
       |                    |                    |
       |              +-----+-----+              |
       |              |  Webhook  |              |
       |              |  boleto.  |              |
       |              |  settled  |              |
       |              +-----------+              |
```

## ACMP615 File

The ACMP615 file is Nuclea's settlement file that contains processed payments.

### File Structure

| Record Type | Description                        |
|-------------|-----------------------------------|
| `00`        | File header                        |
| `20`        | Payment record                     |
| `99`        | File trailer                       |

### Payment Record Fields (Type 20)

| Position | Field             | Description                  |
|----------|-------------------|------------------------------|
| 1-2      | tipo_registro     | Always "20"                  |
| 3-13     | nosso_numero      | Boleto reference             |
| 14-30    | valor_pago        | Amount paid in cents         |
| 31-38    | data_pagamento    | Payment date (YYYYMMDD)      |
| 39-46    | hora_pagamento    | Payment time (HHMMSS)        |

## Related Webhooks

After settlement processing, the following webhooks may be triggered:

| Event             | Description                                  |
|-------------------|---------------------------------------------|
| `boleto.settled`  | Boleto settled - funds transferred          |
| `cycle.completed` | Settlement cycle completed                   |

For more details, see the [Webhooks](/en/webhooks/) documentation.

## Next Steps

- [Health Check](/en/api/health) - Verify FTP configuration
- [Settlement Flow](/en/guides/settlement-flow) - Complete process guide
- [Webhooks](/en/webhooks/) - Configure notifications