# API Overview

The FluxiQ NPC API allows you to integrate your application with Nuclea's boleto infrastructure (PCR/CMP/SILOC).

## Base URL

| Environment | Base URL                                           |
|-------------|---------------------------------------------------|
| Local       | `http://localhost:4000/api/v1/central`            |
| Sandbox     | `https://sandbox.monetarie_npc.com.br/api/v1/central`|
| Production  | `https://api.monetarie_npc.com.br/api/v1/central`    |

## Authentication

All requests must include the `X-API-Key` header with your access key:

```bash
curl -X GET "https://api.monetarie_npc.com.br/api/v1/central/health" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json"
```

::: info API Key Prefixes
- `pk_test_` - Sandbox keys for testing
- `pk_live_` - Production keys
:::

For more details, see the [Authentication](/en/authentication) page.

## Response Format

### Success Response

All success responses follow the standard format:

```json
{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

### Error Response

Errors follow this format:

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Error description",
    "details": {
      // Additional details when available
    }
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

::: tip Request ID
The `meta.request_id` field is included in all responses. Use this value when contacting support to facilitate problem investigation.
:::

## Available Endpoints

| Method   | Endpoint                           | Description                          |
|----------|------------------------------------|------------------------------------|
| `GET`    | `/health`                          | Service health check               |
| `POST`   | `/boletos`                         | Create new boleto                  |
| `GET`    | `/boletos/:nosso_numero`           | Query boleto                       |
| `PATCH`  | `/boletos/:nosso_numero`           | Update boleto (draft only)         |
| `DELETE` | `/boletos/:nosso_numero`           | Cancel boleto                      |
| `POST`   | `/boletos/:nosso_numero/pay`       | Mark boleto as paid                |
| `POST`   | `/settlements/trigger`             | Trigger settlement processing      |

## HTTP Status Codes

| Code   | Status                | Description                                            |
|--------|----------------------|--------------------------------------------------------|
| `200`  | OK                   | Request processed successfully                         |
| `201`  | Created              | Resource created successfully                          |
| `202`  | Accepted             | Request accepted for asynchronous processing           |
| `400`  | Bad Request          | Invalid or malformed parameters                        |
| `401`  | Unauthorized         | Missing or invalid API Key                             |
| `403`  | Forbidden            | No permission to access the resource                   |
| `404`  | Not Found            | Resource not found                                     |
| `422`  | Unprocessable Entity | Validation error in the submitted data                 |
| `429`  | Too Many Requests    | Request limit exceeded                                 |
| `500`  | Internal Server Error| Internal server error                                  |
| `503`  | Service Unavailable  | Service temporarily unavailable                        |

## Pagination

Endpoints that return lists support pagination through query parameters:

### Pagination Parameters

| Parameter | Type     | Default | Description                              |
|-----------|----------|---------|------------------------------------------|
| `page`    | integer  | 1       | Page number (starts at 1)                |
| `per_page`| integer  | 20      | Items per page (max 100)                 |

### Paginated Request Example

```bash
curl -X GET "https://api.monetarie_npc.com.br/api/v1/central/boletos?page=2&per_page=50" \
  -H "X-API-Key: pk_live_abc123def456"
```

### Paginated Response Format

```json
{
  "success": true,
  "data": [
    // List of items
  ],
  "meta": {
    "request_id": "req_abc123def456",
    "pagination": {
      "page": 2,
      "per_page": 50,
      "total_items": 247,
      "total_pages": 5,
      "has_next": true,
      "has_prev": true
    }
  }
}
```

## Rate Limiting

The API has request limits to ensure stability:

| Environment | Limit                   | Window    |
|-------------|-------------------------|-----------|
| Sandbox     | 100 requests            | per minute |
| Production  | 1000 requests           | per minute |

When the limit is exceeded, the API returns status `429 Too Many Requests` with headers:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706972400
```

For more details, see [Rate Limits](/en/reference/rate-limits).

## Next Steps

- [Boletos](/en/api/boletos) - Create and manage boletos
- [Settlements](/en/api/settlements) - Process settlement files
- [Health Check](/en/api/health) - Check service health