# API сервиса — справочник

Все запросы — **server-to-server** (PHP→PHP). Браузер покупателя не обращается к этим URL.

## Авторизация

Каждый запрос должен содержать заголовок:

```
Authorization: Bearer YOUR_API_TOKEN
```

Токен берётся из личного кабинета (поле `api_token` пользователя).

---

## Endpoints

### POST /ClientPaymentApi/Track/

Регистрирует клик по партнёрской ссылке. Возвращает токен сессии для отслеживания.

**Тело запроса (JSON):**

| Поле | Тип | Обязательный | Описание |
|------|-----|:---:|---------|
| `code` | string | ✓ | Партнёрский код |
| `ip` | string | ✓ | IP покупателя (определяется на сервере клиента) |
| `user_agent` | string | ✓ | User-Agent покупателя |
| `referer` | string | — | HTTP Referer |
| `fp` | string | — | Fingerprint (если уже известен) |
| `sub` | string | — | Суб-аккаунт партнёра |
| `data1`..`data5` | string | — | Keitaro/трекер параметры |
| Любые другие | string | — | utm_*, fbclid, gclid, roistat, и т.д. |

**Пример запроса:**

```json
{
  "code": "abc123",
  "ip": "93.12.34.56",
  "user_agent": "Mozilla/5.0 ...",
  "data1": "keitaro_click_id_here",
  "utm_source": "google",
  "utm_campaign": "summer_sale"
}
```

**Ответ (успех):**

```json
{
  "status": "success",
  "data": {
    "fp": "d41d8cd98f00b204e9800998ecf8427e",
    "product_url": "https://author-site.com/product-page/",
    "partner_id": 1234,
    "product_id": 567
  }
}
```

| Поле | Описание |
|------|---------|
| `fp` | Токен сессии — передать покупателю через `?fp=TOKEN` или cookie |
| `product_url` | URL страницы товара для редиректа |

**Ошибки:**

```json
{ "status": "error", "errors": { "code": "not found" } }
{ "status": "error", "errors": { "ip": "blocked" } }
```

---

### GET /ClientPaymentApi/Order/

Возвращает данные заказа для рендера формы оплаты.

**Query-параметры:**

| Параметр | Тип | Описание |
|----------|-----|---------|
| `order_id` | int | ID заказа |
| `order_hash` | string | HMAC-хэш заказа |

**Пример:**

```
GET /ClientPaymentApi/Order/?order_id=123456&order_hash=abc...
```

**Ответ:**

```json
{
  "status": "success",
  "data": {
    "order_id": 123456,
    "amount": 1990.0,
    "product_name": "Курс «PHP для начинающих»",
    "status": 0,
    "deadline": 540,
    "methods": [
      { "alias": "epqr",  "label": "ePay СБП QR"  },
      { "alias": "exqr",  "label": "Express QR"   },
      { "alias": "ex",    "label": "Express карта" }
    ]
  }
}
```

| Поле | Описание |
|------|---------|
| `status` | 0=ожидает, 1=оплачен, -1=отклонён |
| `deadline` | Секунд до истечения сессии оплаты |
| `methods` | Доступные методы оплаты в порядке приоритета |

---

### POST /ClientPaymentApi/GetCard/

Инициирует платёж: получает реквизиты карты или QR-код у платёжного провайдера.

**Тело запроса (JSON):**

| Поле | Тип | Обязательный | Описание |
|------|-----|:---:|---------|
| `order_id` | int | ✓ | ID заказа |
| `order_hash` | string | ✓ | HMAC-хэш заказа |
| `provider` | string | — | Alias метода (`epqr`, `ex`, `ep`, и т.д.). Если не указан — используется первый доступный |
| `solo` | bool | — | `true` = без фоллбэка (тестовый режим конкретного провайдера) |
| `fp` | string | — | Fingerprint для привязки к сессии |
| `extra` | object | — | Дополнительные параметры (utm_*, и т.д.) |

**Пример:**

```json
{
  "order_id": 123456,
  "order_hash": "abc...",
  "provider": "epqr"
}
```

**Ответ (QR-код):**

```json
{
  "status": "success",
  "data": {
    "tid": 789,
    "provider": "epay_sbp_qr",
    "method": "qr",
    "amount": 1990.0,
    "qr_link": "https://qr.nspk.ru/...",
    "deadline": 520
  }
}
```

**Ответ (P2P карта):**

```json
{
  "status": "success",
  "data": {
    "tid": 789,
    "provider": "p2p_express",
    "method": "card",
    "amount": 2015.0,
    "card": "4276123456789012",
    "receiver_name": "Иван И.",
    "receiver_bank": "Сбербанк",
    "deadline": 700
  }
}
```

**Ответ (ошибка с фоллбэком):**

```json
{
  "status": "error",
  "next_provider": "exqr"
}
```

Если `next_provider` есть — повторите запрос с этим alias. Если нет — все методы исчерпаны.

---

### GET /ClientPaymentApi/Status/

Проверяет статус оплаты заказа.

**Query-параметры:**

| Параметр | Тип | Описание |
|----------|-----|---------|
| `order_id` | int | ID заказа |
| `order_hash` | string | HMAC-хэш |
| `tid` | int | ID транзакции (из GetCard ответа) |

**Ответ:**

```json
{ "status": "success", "data": { "status": "pending" } }
{ "status": "success", "data": { "status": "success" } }
{ "status": "success", "data": { "status": "reject"  } }
```

---

### POST /ClientPaymentApi/Confirm/

Покупатель подтверждает, что отправил деньги (нажал «Я оплатил»).

**Тело запроса:**

```json
{
  "order_id": 123456,
  "order_hash": "abc...",
  "tid": 789
}
```

**Ответ:**

```json
{ "status": "success", "data": { "status": "ok" } }
```

---

## Коды ошибок

| HTTP код | Значение |
|----------|---------|
| 200 | Успех (проверяйте `status` в теле) |
| 401 | Неверный или отсутствующий API-токен |
| 404 | Ресурс не найден |
| 405 | Метод не поддерживается |

Тело ошибки:

```json
{
  "status": "error",
  "errors": {
    "field_name": "описание ошибки"
  }
}
```

---

## Логи сервиса

| Файл | Содержимое |
|------|----------|
| `!!!!partner_link_debug.log` | Входящие запросы на `/ClientPaymentApi/Track/` |
| `clickpay24.tv.postback_new.log` | Отправка и ответы постбэков |
| `clickpay24.tv.payments.!!sbp_form_debug.log` | Инициализация платежей |
| `clickpay24.tv.payments.handler_missing.log` | Отсутствующий handler у провайдера |