dbis_core/docs/nostro-vostro/api-reference.md

# DBIS Nostro/Vostro API Reference

## Base URL

- **Production**: `https://api.scb.example.com/api/v1/nostro-vostro`
- **Sandbox**: `https://sandbox.scb.example.com/api/v1/nostro-vostro`

## Authentication

All requests require OAuth2 authentication with Mutual TLS:

```
Authorization: Bearer <access_token>
```

## Endpoints

### Participants

#### List Participants
```
GET /participants
```

**Query Parameters**:
- `regulatoryTier` (optional): Filter by tier (SCB, Tier1, Tier2, PSP)
- `country` (optional): Filter by country code
- `status` (optional): Filter by status
- `page` (optional): Page number (default: 1)
- `pageSize` (optional): Items per page (default: 50)

**Response**:
```json
{
  "success": true,
  "data": {
    "data": [
      {
        "participantId": "PART-123",
        "name": "Central Bank of Example",
        "bic": "CBEXUS33",
        "country": "US",
        "regulatoryTier": "SCB",
        "status": "active"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 50,
      "total": 1,
      "totalPages": 1
    }
  }
}
```

#### Get Participant
```
GET /participants/{participantId}
```

#### Create Participant
```
POST /participants
```

**Request Body**:
```json
{
  "name": "Central Bank of Example",
  "bic": "CBEXUS33",
  "lei": "5493000X9ZXSQ9B6Y815",
  "country": "US",
  "regulatoryTier": "SCB"
}
```

### Accounts

#### List Accounts
```
GET /accounts
```

#### Create Account
```
POST /accounts
```

**Request Body**:
```json
{
  "ownerParticipantId": "PART-123",
  "counterpartyParticipantId": "PART-456",
  "ibanOrLocalAccount": "US64SVBKUS6S3300958879",
  "currency": "USD",
  "accountType": "NOSTRO"
}
```

#### Get Account
```
GET /accounts/{accountId}
```

#### Get Account Balances
```
GET /accounts/{accountId}/balances
```

**Response**:
```json
{
  "success": true,
  "data": {
    "accountId": "ACC-123",
    "currentBalance": "1000000.00",
    "availableLiquidity": "950000.00",
    "holdAmount": "50000.00",
    "currency": "USD",
    "lastUpdatedAt": "2024-01-15T10:30:00Z"
  }
}
```

### Transfers

#### Create Transfer
```
POST /transfers
```

**Headers**:
- `Idempotency-Key` (optional): Unique key for idempotency

**Request Body**:
```json
{
  "fromAccountId": "ACC-123",
  "toAccountId": "ACC-456",
  "amount": "1000.00",
  "currency": "USD",
  "settlementAsset": "FIAT",
  "valueDate": "2024-01-15",
  "reference": "PAYMENT-REF-001"
}
```

#### Get Transfer
```
GET /transfers/{transferId}
```

#### List Transfers
```
GET /transfers
```

### Reconciliations

#### Request Reconciliation
```
POST /reconciliations
```

**Request Body**:
```json
{
  "participantId": "PART-123",
  "asOfDate": "2024-01-15"
}
```

#### Get Reconciliation
```
GET /reconciliations/{reportId}
```

### Webhooks

#### Create Subscription
```
POST /webhooks/subscriptions
```

**Request Body**:
```json
{
  "participantId": "PART-123",
  "webhookUrl": "https://example.com/webhooks",
  "eventTypes": ["TRANSFER_CREATED", "TRANSFER_SETTLED"]
}
```

#### List Subscriptions
```
GET /webhooks/subscriptions?participantId=PART-123
```

### GRU/FX

#### Get Rate
```
GET /gru-fx/rates?pair=USD/GRU
```

**Response**:
```json
{
  "success": true,
  "data": {
    "pair": "USD/GRU",
    "rate": "0.6667",
    "timestamp": "2024-01-15T10:30:00Z",
    "source": "DBIS_GRU",
    "bid": "0.6663",
    "ask": "0.6671",
    "spread": "0.0008"
  }
}
```

#### Get Rate History
```
GET /gru-fx/rates/history?pair=USD/GRU&startDate=2024-01-01&endDate=2024-01-15&interval=1d
```

#### Convert Currency
```
POST /gru-fx/convert
```

**Request Body**:
```json
{
  "fromCurrency": "USD",
  "toCurrency": "EUR",
  "amount": "1000.00",
  "settlementAsset": "FIAT"
}
```

## Error Responses

All errors follow this format:

```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
```

### Error Codes

- `VALIDATION_ERROR`: Invalid request parameters
- `NOT_FOUND`: Resource not found
- `UNAUTHORIZED`: Authentication required
- `FORBIDDEN`: Insufficient permissions
- `CONFLICT`: Resource already exists
- `UNPROCESSABLE_ENTITY`: Business logic error (e.g., insufficient balance)
- `INTERNAL_ERROR`: Server error

## Rate Limiting

- Default: 1000 requests per minute per FI
- Burst: Up to 100 requests in 10 seconds
- Headers:
  - `X-RateLimit-Limit`: Total allowed requests
  - `X-RateLimit-Remaining`: Remaining requests
  - `X-RateLimit-Reset`: Reset time (Unix timestamp)

## Webhooks

### Event Types

- `TRANSFER_CREATED`: New transfer created
- `TRANSFER_SETTLED`: Transfer settled
- `TRANSFER_REJECTED`: Transfer rejected
- `ACCOUNT_UPDATED`: Account updated
- `BALANCE_CHANGED`: Balance changed
- `RECONCILIATION_COMPLETED`: Reconciliation completed

### Webhook Payload

```json
{
  "eventId": "EVT-123",
  "eventType": "TRANSFER_SETTLED",
  "timestamp": "2024-01-15T10:30:00Z",
  "payload": {
    "transferId": "TRF-123",
    "status": "SETTLED",
    "settledAt": "2024-01-15T10:30:00Z"
  }
}
```

### Signature Verification

Webhooks include a signature header:

```
X-DBIS-Signature: <signature>
X-DBIS-Timestamp: <timestamp>
```

Verify using HMAC-SHA256:

```typescript
const message = `${timestamp}.${JSON.stringify(payload)}`;
const signature = crypto.createHmac('sha256', secret).update(message).digest('hex');
```

## Idempotency

Use `Idempotency-Key` header for idempotent operations:

```
Idempotency-Key: unique-key-12345
```

Duplicate requests with the same key return the original response.

## Pagination

All list endpoints support pagination:

```
GET /participants?page=1&pageSize=50
```

Response includes pagination metadata:

```json
{
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 100,
    "totalPages": 2
  }
}
```

## Examples

### Complete Transfer Flow

1. **Create Transfer**:
```bash
curl -X POST https://api.example.com/api/v1/nostro-vostro/transfers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{
    "fromAccountId": "ACC-123",
    "toAccountId": "ACC-456",
    "amount": "1000.00",
    "currency": "USD",
    "reference": "PAYMENT-001"
  }'
```

2. **Check Transfer Status**:
```bash
curl https://api.example.com/api/v1/nostro-vostro/transfers/TRF-123 \
  -H "Authorization: Bearer $TOKEN"
```

3. **Get Account Balances**:
```bash
curl https://api.example.com/api/v1/nostro-vostro/accounts/ACC-123/balances \
  -H "Authorization: Bearer $TOKEN"
```

## SDKs

Official SDKs available:
- Java
- .NET
- Python
- Node.js

See [SDK Documentation](./cb-implementation-guide.md) for details.

## Support

- **API Documentation**: To be configured (e.g. https://docs.your-domain.com/nostro-vostro)
- **Support Email**: To be configured
- **Emergency Hotline**: To be configured