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

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

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

## Ключ

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

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

Ключ выпускается в кабинете партнёра, раздел [«API»](https://admin.vargopartners.com/reseller/api): значение показывается один раз, в базе хранится только его хеш. Ключ один — чтобы заменить, отзовите прежний и выпустите новый; пока новый ключ не встал на сервер, запросы получают `401`. Без ключа, с неверным или отозванным ключом, при выключенном доступе к API, а также когда аккаунт партнёра заблокирован платформой, ответ один и тот же — `401 UNAUTHORIZED`: по ответу нельзя понять, существовал ли ключ.

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

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

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

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

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

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

Сеть рвётся: запрос на выставление счёта мог дойти, а ответ — потеряться. Чтобы повтор не выставил клиенту второй счёт, [`POST /payments`](https://vargopartners.com/docs/api/create-payment) требует заголовок `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`. Новый ключ на повторе — это новый счёт.

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

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

Пока клиент на странице оплаты, опрашивайте счёт раз в несколько секунд — или подключите [вебхуки](https://vargopartners.com/docs/webhooks.md), и об оплате ваш сервер узнает сам. Статус `expired` не окончательный: оплата, пришедшая позже срока, всё равно проходит, и счёт становится `succeeded`. Поэтому к истёкшему счёту стоит вернуться, когда клиент снова придёт к вам.

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

Заголовок `Accept-Language: ru` — тексты на русском: подписи ссылок на приложения, заголовки документов, поле `message` в ошибках. Без заголовка или с другим языком — английский. Названия способов оплаты из [`GET /payment-methods`](https://vargopartners.com/docs/api/payment-methods) от заголовка не зависят и всегда на русском.

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

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

Новые поля, коды ошибок и типы событий появляются без смены версии, и интеграция не должна на них ломаться. Подробно — [Ошибки и лимиты](https://vargopartners.com/docs/errors.md#версии).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.