> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vargopartners.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Начало работы

> Ключ, повтор запроса без второго счёта, язык ответов

## Ключ

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

```http theme={"dark"}
Authorization: Bearer vgo_live_…
```

Ключ выдаёт платформа — напишите менеджеру в [Telegram](https://t.me/DanielCode). Без ключа, с неверным или отозванным ключом, а также при выключенном доступе к API ответ один и тот же — `401 UNAUTHORIZED`: по ответу нельзя понять, существовал ли ключ.

* Храните ключ только на сервере: в переменных окружения или хранилище секретов, не в репозитории.
* В код мини-аппа, сайта или мобильного приложения ключ не попадает никогда. Клиентская часть ходит к вашему серверу, сервер — к API.
* Ключ утёк — сразу напишите менеджеру: старый ключ отзовут, выдадут новый.

<Warning>
  **Тестового режима нет.** Каждый ключ боевой: `POST /payments` выставляет настоящий счёт, пробный период выдаёт настоящий доступ. Неоплаченный счёт ничего не стоит — он просто истекает. Проверку интеграции проведите на себе: выставьте счёт своему `client_id` и оплатите его.
</Warning>

## Клиент — ваш id

Клиент определяется вашим идентификатором `client_id`: номер пользователя в вашем боте, id в базе сайта — что угодно, что не меняется.

* 1–128 символов: латиница, цифры и `. _ : @ + -`; не `.` и не `..`; регистр различается.
* Уникален внутри вашего аккаунта: одинаковый `client_id` у двух партнёров — разные клиенты.
* Отдельно заводить клиента не нужно: он появляется с первым счётом или пробным периодом.

## Повтор запроса без второго счёта

Сеть рвётся: запрос на выставление счёта мог дойти, а ответ — потеряться. Чтобы повтор не выставил клиенту второй счёт, `POST /payments` требует заголовок `Idempotency-Key`:

```http theme={"dark"}
Idempotency-Key: order-1001
```

Удобнее всего передавать номер заказа в вашей системе. Ключ — до 200 символов, уникален внутри вашего аккаунта.

| Что пришло | Ответ |
| - | - |
| Новый ключ | `201` — счёт выставлен |
| Тот же ключ и те же поля | `200` — тот же счёт, `replayed: true` |
| Тот же ключ, другие поля | `409 IDEMPOTENCY_KEY_REUSE` — возьмите новый ключ |
| Тот же ключ, первый запрос ещё идёт | `409 OPERATION_IN_PROGRESS` — повторите тем же ключом через пару секунд |
| Нет ключа | `400 IDEMPOTENCY_KEY_REQUIRED` |
| Ключ длиннее 200 символов | `400 IDEMPOTENCY_KEY_TOO_LONG` |

«Те же поля» — это `client_id`, `purpose`, `plan_id`, `devices`, `method` и `return_url`. Порядок ключей в JSON значения не имеет.

<Tip>
  Таймаут, обрыв соединения, `5xx` на `POST /payments` — повторяйте с **тем же** `Idempotency-Key`. Новый ключ на повторе — это новый счёт.
</Tip>

## Источник истины — запрос `GET`

Состояние счёта и клиента всегда берите из API: `GET /payments/{payment_id}` и `GET /clients/{client_id}`. Перед тем как выдать клиенту что-то у себя (открыть доступ, начислить бонус), перечитайте счёт.

Пока клиент на странице оплаты, опрашивайте счёт раз в несколько секунд. Статус `expired` не окончательный: оплата, пришедшая позже срока, всё равно проходит, и счёт становится `succeeded`. Поэтому к истёкшему счёту стоит вернуться, когда клиент снова придёт к вам.

## Язык ответов

Заголовок `Accept-Language: ru` — тексты на русском: названия способов оплаты, подписи ссылок на приложения, заголовки документов, поле `message` в ошибках. Без заголовка или с другим языком — английский.

```http theme={"dark"}
Accept-Language: ru
```

## Совместимость

Новые поля в ответах и новые коды ошибок появляются без смены версии. Код интеграции не должен ломаться на незнакомых полях, а незнакомый код ошибки — трактовать как обычный отказ. Удаление и переименование полей — только в новой версии пути (`/v2`).