> For the complete documentation index, see [llms.txt](https://docs.esimpay.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.esimpay.net/bystryi-start.md).

# Быстрый старт

### Предварительные требования

1. **Учетные данные мерчанта**
   * `CF-MERCHANT-ID` — идентификатор вашего мерчанта
   * `CF-API-SECRET` — секретный ключ для подписей
2. **API Secret** — получите в личном кабинете

### Шаг 1: Проверьте баланс (без подписи)

Это самый простой запрос для тестирования подключения:

```bash
curl -X GET https://api.esimpay.net/api/v1/customer/balance \
  -H "CF-MERCHANT-ID: your_merchant_id"
```

**Ответ:**

```json
{
  "status": "completed",
  "message": null,
  "balance": 1000.0
}
```

### Шаг 2: Получите список доступных пакетов

```bash
curl -X GET https://api.esimpay.net/api/v1/products/list \
  -H "CF-MERCHANT-ID: your_merchant_id"
```

### Шаг 3: Создайте заказ (требуется подпись)

Для POST запросов нужна подпись HMAC-SHA256.

#### Генерирование подписи (Python)

```python
import json
import hmac
import hashlib
import base64
import requests

MERCHANT_ID = 'your_merchant_id'
API_SECRET = 'your_api_secret'
BASE_URL = 'https://api.esimpay.net/api/v1'

def sign(payload: dict):
    # 1. Сортируем ключи, удаляем пробелы
    json_str = json.dumps(
        payload,
        separators=(',', ':'),
        ensure_ascii=False,
        sort_keys=True,
    )
    
    # 2. HMAC-SHA256
    digest = hmac.new(
        API_SECRET.encode('utf-8'),
        json_str.encode('utf-8'),
        hashlib.sha256,
    ).digest()
    
    # 3. Base64
    signature = base64.b64encode(digest).decode('utf-8')
    return json_str, signature

# Пример: создание заказа
payload = {
    'orderId': 'order_123',
    'productId': 'b27bfd74-c46d-479c-b628-ec7ca69a146f',
    'activationMode': 'NOW',
}

body, signature = sign(payload)

response = requests.post(
    f'{BASE_URL}/orders/submit',
    data=body,
    headers={
        'Content-Type': 'application/json',
        'CF-MERCHANT-ID': MERCHANT_ID,
        'CF-ACCESS-SIGN': signature,
    },
)

print(response.json())
```

### Шаг 4: Проверьте статус

```bash
curl -X GET "https://api.esimpay.net/api/v1/customer/history?limit=10" \
  -H "CF-MERCHANT-ID: your_merchant_id"
```

### Следующие шаги

1. Изучите Аутентификацию для понимания безопасности
2. Посмотрите все API Endpoints
3. Выберите примеры для вашего языка
4. Ознакомьтесь с Обработкой ошибок

### Советы

#### Используйте интерактивное тестирование

**Откройте OpenAPI Interactive Module** — здесь вы можете:

* Тестировать все endpoints
* Видеть примеры запросов/ответов
* Генерировать код для разных языков

#### Сохраняйте API Secret

```python
# ✅ Правильно
import os
from dotenv import load_dotenv

load_dotenv()
API_SECRET = os.getenv('ESIMPAY_API_SECRET')
```

```bash
# Файл .env (добавить в .gitignore)
ESIMPAY_API_SECRET=your_secret_key
ESIMPAY_MERCHANT_ID=your_merchant_id
```

***

**Готовы начать? Переходите к Аутентификации!**