# UTERLAB Cascade API v1

Public documentation for **Cascade → UTERLAB** integration.

## Base URL

`https://YOUR-UTERLAB-DOMAIN/api/v1/cascade`

## Authentication

Headers:

- `X-API-Key`
- `X-Timestamp`
- `X-Nonce`
- `X-Signature`

Signature source:

```text
timestamp\nnonce\nMETHOD\n/path\nraw_body
```

`X-Signature = HMAC-SHA256(signature_string, secret)`

## Endpoints

| Method | Endpoint | Scope |
|---|---|---|
| GET | `/api/v1/cascade/orders/next` | `cascade:orders:pull` |
| GET | `/api/v1/cascade/orders/{dispatchId}` | `cascade:orders:read` |
| POST | `/api/v1/cascade/orders/{dispatchId}/accept` | `cascade:orders:write` |
| POST | `/api/v1/cascade/orders/{dispatchId}/reject` | `cascade:orders:write` |
| POST | `/api/v1/cascade/orders/{dispatchId}/complete` | `cascade:orders:write` |
| GET | `/api/v1/cascade/methods` | `cascade:methods:read` |
| GET | `/api/v1/cascade/balance` | `cascade:balance:read` |

## Flow

1. Call `GET /orders/next`.
2. Accept or reject the offered dispatch before it expires.
3. On accept, return valid payment requisites for the proposed method/currency.
4. Call `complete` after actual completion.

## Accept example

`POST /api/v1/cascade/orders/{dispatchId}/accept`

```json
{
  "bank_code": "sber",
  "bank_name": "СберБанк",
  "requisite": "2202201234567890",
  "holder_name": "Иван И."
}
```

## Dispatch statuses

- `offered`
- `pulled`
- `active`
- `completed`
- `rejected`
- `expired`
- `cancelled`

## Common HTTP errors

- `401` — API key/signature/timestamp error
- `403` — scope/IP/access error
- `404` — dispatch not found
- `409` — state conflict or replayed nonce
- `422` — invalid request/requisite data
- `429` — rate limit exceeded

Internal routing, commercial terms and reverse UTERLAB → Cascade integration settings are intentionally not included in this public document.


## Изменения 1.1.10

См. [UPDATE-1.1.10.md](UPDATE-1.1.10.md): callback-токен и идентификаторы исходящего каскада, сверка неизвестных результатов, безопасная отмена и повторная доставка webhook.