# Reports

This guide explains how to receive notifications when a report file is ready and how to download it.

Monato generates report files automatically on a daily and monthly basis. The flow has two steps:

1. Monato generates the file → sends a **Report Webhook** to notify you.
2. You receive the notification → call the **Download endpoint** to get the file URL.


## End-to-End Flow


```mermaid
sequenceDiagram
    participant M as Monato
    participant Y as Your Server
    participant C as Your Client App

    M->>M: Generates report file<br/>(daily or monthly)

    M->>Y: POST {your-webhook-url}<br/>Report Webhook
    Note right of Y: {<br/>  "file_type": "TRANSACTIONS",<br/>  "period": "DAILY",<br/>  "file_name": "transactions_daily_20260224.csv",<br/>  "created_at": "2026-02-24T10:30:15Z"<br/>}

    Y-->>M: HTTP 200 OK

    Y->>M: POST /v1/reports/clients/{client_id}/report/download
    Note right of M: {<br/>  "report_type": "DAILY",<br/>  "operation_date": "2026-02-24"<br/>}

    M-->>Y: HTTP 200 OK
    Note right of Y: {<br/>  "file_name": "transactions_daily_20260224.csv",<br/>  "download_url": "https://..."<br/>}

    Y->>C: Deliver file / notify availability
```

## Register for Report Notifications

Before receiving the webhook, you must register the endpoint where Monato will send notifications.

**Endpoint**


```
POST /v1/clients/{client_id}/webhooks
```

**Request Headers**


```
Authorization: Bearer <token>
Content-Type: application/json
```

**Body**


```json
{
  "client_id": "{{clientId}}",
  "url": "https://example.com/report-webhook",
  "token": "secretToken0123",
  "webhook_type": "REPORT",
  "auth_type": "AUTH"
}
```

**Response** — Status Code: `200 OK`


```json
{
  "id": "29806117-2b15-4682-87f0-350e6695fe91",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "url": "https://example.com/report-webhook",
  "token": "secretToken0123",
  "webhookType": "REPORT",
  "webhookStatus": "ACTIVE",
  "createdAt": "2026-02-24T10:30:15Z",
  "updatedAt": "2026-02-24T10:30:15Z",
  "deletedAt": null,
  "blockedAt": null
}
```

> The request body uses `snake_case` (e.g. `webhook_type`) while the response uses `camelCase` (e.g. `webhookType`). This is expected and consistent across the API.


## Report Webhook

Once registered, Monato sends a `POST` request to your endpoint every time a new report file is available for download. This can correspond to **transaction reports** or **account statements**, in daily or monthly periods.

### Payload


```json
{
  "client_id": "9c6f6c8a-7c91-4b12-9a45-5cfdc78c22b1",
  "file_type": "TRANSACTIONS",
  "period": "DAILY",
  "file_name": "transactions_daily_20260224.csv",
  "created_at": "2026-02-24T10:30:15Z"
}
```

### Fields

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `client_id` | string | Yes | Unique identifier of the client. |
| `file_type` | string | Yes | Type of generated file. Values: `TRANSACTIONS`, `ACCOUNT_STATEMENT`. |
| `period` | string | Yes | Report period. Values: `DAILY`, `MONTHLY`. |
| `file_name` | string | Yes | Name of the generated file. |
| `created_at` | string (ISO 8601) | Yes | Date and time when the file was generated. |
| `account_id` | string | Conditional | Account identifier. Only present when `file_type = ACCOUNT_STATEMENT`. |


### Example — Transactions Report


```json
{
  "client_id": "9c6f6c8a-7c91-4b12-9a45-5cfdc78c22b1",
  "file_type": "TRANSACTIONS",
  "period": "DAILY",
  "file_name": "transactions_daily_20260224.csv",
  "created_at": "2026-02-24T10:30:15Z"
}
```

### Example — Account Statement


```json
{
  "client_id": "9c6f6c8a-7c91-4b12-9a45-5cfdc78c22b1",
  "file_type": "ACCOUNT_STATEMENT",
  "period": "MONTHLY",
  "file_name": "account_statement_1234567890_202602.csv",
  "created_at": "2026-03-01T02:10:00Z",
  "account_id": "1234567890"
}
```

> `account_id` is only included in the payload when `file_type = ACCOUNT_STATEMENT`. For `TRANSACTIONS` files, this field is omitted.


## Download a Report

Use this endpoint to retrieve the download URL for a report file. You can call it after receiving the webhook notification, or proactively to check if a file exists for a given date and type.

**Endpoint**


```
POST /v1/reports/clients/{client_id}/report/download
```

**Request Headers**


```
Authorization: Bearer <token>
Content-Type: application/json
```

**Path Parameters**

| Parameter | Description |
|  --- | --- |
| `client_id` | Unique identifier of the client (UUID). |


**Request Body**

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `report_type` | string | Yes | Type of report. See allowed values below. |
| `operation_date` | string | Yes | Date in `YYYY-MM-DD` format. |
| `clabe_number` | string | Conditional | Required for `DAILY_ACCOUNT_STATEMENT` and `MONTHLY_ACCOUNT_STATEMENT`. Must belong to the client. |


### `report_type` values

| Value | Description |
|  --- | --- |
| `DAILY` | Daily transactions report. |
| `MONTHLY` | Monthly transactions report. |
| `DAILY_ACCOUNT_STATEMENT` | Daily account statement. |
| `MONTHLY_ACCOUNT_STATEMENT` | Monthly account statement. |


### Date Normalization

For `MONTHLY` and `MONTHLY_ACCOUNT_STATEMENT`, the `operation_date` is automatically normalized to the **last day of the month**.

> Example: `2025-08-25` → `2025-08-31`


### Example Request — Daily account statement


```json
{
  "clabe_number": "123456789012345678",
  "report_type": "DAILY_ACCOUNT_STATEMENT",
  "operation_date": "2025-08-25"
}
```

### Example Request — Daily transactions report


```json
{
  "report_type": "DAILY",
  "operation_date": "2025-08-25"
}
```

**Response** — Status Code: `200 OK`


```json
{
  "file_name": "daily_account_statement_123456789012345678_20260224.csv",
  "download_url": "https://..."
}
```

> If no matching file is found, both `file_name` and `download_url` are returned **empty**.


### Error Scenarios — `400 Bad Request`

| Message | Cause |
|  --- | --- |
| `Invalid UUID format for client_id` | `client_id` is not a valid UUID. |
| `Invalid report_type: <value>` | `report_type` value is not one of the 4 allowed values. |
| `clabe_number is required for account statement reports` | `clabe_number` missing for account statement types. |
| `Invalid clabe number` | `clabe_number` does not belong to the client. |
| `operation_date must use format YYYY-MM-DD` | Date format is incorrect. |
| `operation_date must be a valid date with format YYYY-MM-DD` | Format is correct but the date itself is invalid. |