# API Reference

Complete REST API reference for the Monetarie PIX Settlement Service (API Gateway) on port 4003.

## Prerequisites

- Monetarie PIX backend running
- Valid authentication credentials
- HTTP client (curl, Postman, or application code)

## Authentication

All API endpoints require a valid JWT session cookie (`pix_session`) obtained via login:

```bash
# Login
curl -X POST http://localhost:4003/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"username":"admin","password":"Admin@2026!"}'

# Authenticated request
curl http://localhost:4003/api/v1/transactions \
  -b cookies.txt
```

For requests that modify data, include the CSRF token from the `pix_csrf` cookie.

## Base URLs

| Service | URL | Port |
|---------|-----|------|
| Settlement (Gateway) | `http://localhost:4003` | 4003 |
| Dict (Internal) | `http://localhost:4001` | 4001 |
| SPI (Internal) | `http://localhost:4002` | 4002 |

## Authentication Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/auth/public-key` | RSA public key for login encryption |
| POST | `/api/v1/auth/login` | Login (returns HttpOnly JWT cookie) |
| POST | `/api/v1/auth/mfa/verify` | Verify MFA code |
| POST | `/api/v1/auth/logout` | Logout (blacklists JWT) |
| GET | `/api/v1/auth/me` | Current user profile |

## Transaction Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/transactions` | List transactions (paginated, filterable) |
| GET | `/api/v1/transactions/:id` | Transaction details |
| POST | `/api/v1/transactions` | Create transaction (idempotency supported) |
| GET | `/api/v1/transactions/:id/history` | Status history |
| GET | `/api/v1/transactions/summary` | Aggregate statistics |
| GET | `/api/v1/transactions/export` | CSV export |

### Query Parameters (List)

| Parameter | Type | Description |
|-----------|------|-------------|
| `status` | string | Filter by status (PDNG, ACSP, STLD, RJCT, CANC) |
| `e2e_id` | string | Search by End-to-End ID (trigram fuzzy) |
| `start_date` | date | Filter from date (YYYY-MM-DD) |
| `end_date` | date | Filter to date (YYYY-MM-DD) |
| `instrument_type` | string | Filter by instrument |
| `page` | integer | Page number (default 1) |
| `per_page` | integer | Items per page (default 20) |

## DICT Proxy Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/keys` | List PIX keys |
| POST | `/api/v1/keys` | Create PIX key |
| GET | `/api/v1/keys/:key` | Lookup PIX key |
| DELETE | `/api/v1/keys/:key` | Delete PIX key |
| POST | `/api/v1/claims` | Create claim |
| GET | `/api/v1/claims/:id` | Get claim details |
| POST | `/api/v1/claims/:id/respond` | Respond to claim |
| POST | `/api/v1/claims/:id/cancel` | Cancel claim |

## MED 2.0 Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v2/infraction-reports` | List infraction reports |
| GET | `/api/v2/infraction-reports/:id` | Report detail |
| PUT | `/api/v2/infraction-reports/:id/acknowledge` | Acknowledge receipt |
| PUT | `/api/v2/infraction-reports/:id/analyse` | Analyse (AGREED/DISAGREED) |
| PUT | `/api/v2/infraction-reports/:id/close` | Close report |

## Settlement Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/settlement/cycles` | List settlement cycles |
| GET | `/api/v1/settlement/balances` | Participant balances |
| GET | `/api/v1/settlement/reconciliation` | Reconciliation results |

## Accounting Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/accounting/chart-of-accounts` | 44 COSIF accounts |
| GET | `/api/v1/accounting/journal-entries` | Double-entry journal |
| GET | `/api/v1/accounting/events` | Accounting events |
| POST | `/api/v1/accounting/events` | Create accounting event |
| GET | `/api/v1/accounting/cost-centers` | List cost centers |
| POST | `/api/v1/accounting/cost-centers` | Create cost center |
| PUT | `/api/v1/accounting/cost-centers/:id` | Update cost center |
| POST | `/api/v1/accounting/cost-centers/:id/toggle-status` | Toggle status |

## System Configuration

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/system/config` | List system parameters |
| PUT | `/api/v1/system/config/:key` | Update parameter |
| GET | `/api/v1/system/config/categories` | List categories |
| GET | `/api/v1/system/config/schedules` | List schedules |

## Monitoring Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/monitoring/health` | Detailed health status |
| GET | `/api/v1/monitoring/metrics` | BEAM VM metrics |
| GET | `/api/v1/monitoring/alerts` | Infrastructure alerts |

## Error Response Format (RFC 7807)

All errors follow RFC 7807 `application/problem+json`:

```json
{
  "type": "https://api.fluxiq.com/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or expired token",
  "instance": "/api/v1/transactions"
}
```

## Idempotency

POST endpoints under `/api/v1/transactions` support the `Idempotency-Key` header:

```bash
curl -X POST http://localhost:4003/api/v1/transactions \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"amount": 10000, "creditor_key": "email@example.com"}'
```

- 24-hour TTL per idempotency key
- Atomic SET NX prevents duplicate processing
- Max body size: 64 KB

## Expected Outcome

After reviewing this API reference:

- You can authenticate and make API calls to all endpoints
- Transaction CRUD operations are accessible with proper filtering
- DICT proxy enables PIX key management through the gateway
- Error responses follow RFC 7807 for consistent error handling