dbis_core-lite/docs/api/reference.md

# API Documentation

## Authentication

All API endpoints (except `/api/auth/login`) require authentication via JWT token in the Authorization header:

```
Authorization: Bearer <token>
```

## Endpoints

### Authentication

#### POST /api/auth/login

Operator login.

**Request Body**:
```json
{
  "operatorId": "string",
  "password": "string",
  "terminalId": "string" (optional)
}
```

**Response**:
```json
{
  "token": "string",
  "operator": {
    "id": "string",
    "operatorId": "string",
    "name": "string",
    "role": "MAKER" | "CHECKER" | "ADMIN"
  }
}
```

#### POST /api/auth/logout

Operator logout.

**Headers**: `Authorization: Bearer <token>`

**Response**:
```json
{
  "message": "Logged out successfully"
}
```

#### GET /api/auth/me

Get current operator information.

**Headers**: `Authorization: Bearer <token>`

**Response**:
```json
{
  "id": "string",
  "operatorId": "string",
  "name": "string",
  "role": "MAKER" | "CHECKER" | "ADMIN"
}
```

### Payments

#### POST /api/payments

Initiate payment (Maker role required).

**Headers**: `Authorization: Bearer <token>`

**Request Body**:
```json
{
  "type": "CUSTOMER_CREDIT_TRANSFER" | "FI_TO_FI",
  "amount": 1234.56,
  "currency": "USD" | "EUR" | "GBP" | "JPY",
  "senderAccount": "string",
  "senderBIC": "string",
  "receiverAccount": "string",
  "receiverBIC": "string",
  "beneficiaryName": "string",
  "purpose": "string" (optional),
  "remittanceInfo": "string" (optional)
}
```

**Response**:
```json
{
  "paymentId": "string",
  "status": "PENDING_APPROVAL",
  "message": "Payment initiated, pending approval"
}
```

#### POST /api/payments/:id/approve

Approve payment (Checker role required).

**Headers**: `Authorization: Bearer <token>`

**Response**:
```json
{
  "message": "Payment approved and processing",
  "paymentId": "string"
}
```

#### POST /api/payments/:id/reject

Reject payment (Checker role required).

**Headers**: `Authorization: Bearer <token>`

**Request Body**:
```json
{
  "reason": "string" (optional)
}
```

**Response**:
```json
{
  "message": "Payment rejected",
  "paymentId": "string"
}
```

#### GET /api/payments/:id

Get payment status.

**Headers**: `Authorization: Bearer <token>`

**Response**:
```json
{
  "paymentId": "string",
  "status": "string",
  "amount": 1234.56,
  "currency": "USD",
  "uetr": "string" | null,
  "ackReceived": false,
  "settlementConfirmed": false,
  "createdAt": "2024-01-01T00:00:00Z"
}
```

#### GET /api/payments

List payments.

**Headers**: `Authorization: Bearer <token>`

**Query Parameters**:
- `limit` (optional, default: 50)
- `offset` (optional, default: 0)

**Response**:
```json
{
  "payments": [
    {
      "id": "string",
      "payment_id": "string",
      "type": "string",
      "amount": 1234.56,
      "currency": "USD",
      "status": "string",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 10
}
```

### Reconciliation

#### GET /api/reconciliation/daily

Generate daily reconciliation report (Checker role required).

**Headers**: `Authorization: Bearer <token>`

**Query Parameters**:
- `date` (optional, ISO date string, default: today)

**Response**:
```json
{
  "report": "string (formatted text report)",
  "date": "2024-01-01"
}
```

#### GET /api/reconciliation/aging

Get aging items (Checker role required).

**Headers**: `Authorization: Bearer <token>`

**Query Parameters**:
- `days` (optional, default: 1)

**Response**:
```json
{
  "items": [
    {
      "id": "string",
      "payment_id": "string",
      "amount": 1234.56,
      "currency": "USD",
      "status": "string",
      "created_at": "2024-01-01T00:00:00Z",
      "aging_reason": "string"
    }
  ],
  "count": 5
}
```

### Health Check

#### GET /health

Health check endpoint.

**Response**:
```json
{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00Z"
}
```

## Error Responses

All endpoints may return error responses:

```json
{
  "error": "Error message"
}
```

Status codes:
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not Found
- `500` - Internal Server Error

## Payment Status Flow

1. `INITIATED` - Payment created by Maker
2. `PENDING_APPROVAL` - Awaiting Checker approval
3. `APPROVED` - Approved by Checker
4. `COMPLIANCE_CHECKING` - Under compliance screening
5. `COMPLIANCE_PASSED` - Screening passed
6. `LEDGER_POSTED` - Funds reserved in ledger
7. `MESSAGE_GENERATED` - ISO 20022 message created
8. `TRANSMITTED` - Message sent via TLS
9. `ACK_RECEIVED` - Acknowledgment received
10. `SETTLED` - Settlement confirmed
11. `FAILED` - Processing failed
12. `CANCELLED` - Rejected/cancelled