# API #### Общие сведения * **URL API**: (ниже используются относительные пути) * **Формат ответа**: `application/json` * **Коды ответов**: HTTP-код `200`. Результат выполнения запроса в ответе в полях `rc` и `msg`. **Термины и сущности** * **provider\_code** — 8 символов `[A-Za-z0-9]{8}` (ID провайдера). * **auth\_key** — 32 символа `[-_A-Za-z0-9]{32}` (ключ авторизации провайдера). * **install\_code** — 12 символов `[A-Za-z0-9]{12}` (код установки). * **domain\_hash** — 64 символа `[a-f0-9]{64}` (SHA-256 от домена подписки, в нижнем регистре). *** **GET `/api/add-install`** **Назначение:** создать ссылку провайдера **Query-параметры** * `provider_code` *(string, required)* — 8 символов * `auth_key` *(string, required)* — 32 символа * `install_limit` *(int, required)* — от `1` до `100` * `install_code` *(string, optional)* — 12 символов. Если не передан — будет сгенерирован * `note` *(string, optional)* — до 255 символов **Ответы**
Успешно ```json { "rc": 1, "msg": "Ok", "install_code": "ABCDEF123456", "id": 33 } ```
Такой install_code уже существует ```json { "rc": 2, "msg": "Install code exists" } ```
Ошибки валидации/авторизации/лимитов ```json { "rc": 0, "msg": "Auth error" } ``` ```json { "rc": 0, "msg": "This feature requires an active subscription" } ``` ```json { "rc": 0, "msg": "Install limit error" } ``` ```json { "rc": 0, "msg": "Install code limit reached" } ``` ```json { "rc": 0, "msg": "Unknown error" } ```
**Пример** ```bash curl -X 'GET' '{url_api}/api/add-install?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_12345&install_limit=10' \ -H 'accept: application/json' ``` *** **GET `/api/update-install`** **Назначение:** изменить ссылку провайдера **Query-параметры** * `provider_code` *(string, required)* — 8 символов * `auth_key` *(string, required)* — 32 символа * `id` *(int, required)* * `install_limit` *(int, optional)* — от `1` до `100`, если не указано - значение не меняется, значение не может быть меньше `install_count` * `note` *(string, optional)* — 255 символов, если не указано - значение не меняется * `status` *(int, optional)* — 5 - Disabled / 10 - Active, если не указано - значение не меняется **Ответы**
Успешно ```json { "rc": 1, "msg": "Ok", "install_code": "ABCDEF123456", "id": 33 } ```
Ошибки валидации/авторизации/лимитов ```json { "rc": 0, "msg": "Auth error" } ``` ```json { "rc": 0, "msg": "This feature requires an active subscription" } ``` ```json { "rc": 0, "msg": "Install limit error" } ``` ```json { "rc": 0, "msg": "Install limit is less than the current install_count" } ``` ```json { "rc": 0, "msg": "Install status error" } ``` ```json { "rc": 0, "msg": "Error save install" } ``` ```json { "rc": 0, "msg": "Install not found" } ``` ```json { "rc": 0, "msg": "Unknown error" } ```
**Пример** ```bash curl -X 'GET' '{url_api}/api/update-install?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_12345&id=33&status=10' \ -H 'accept: application/json' ``` *** **GET `/api/list-install`** **Назначение:** получить список ссылок провайдера **Query-параметры** * `provider_code` *(string, required)* — 8 символов * `auth_key` *(string, required)* — 32 символа * `id` *(int, optional)* — если не передан возвращаются последние 5000 записей **Ответы**
Успешно ```json { "rc": 1, "msg": "Ok", "data": [ { "id": 1, "install_code": "INSTALLCODE1", "install_limit": 100, "install_count": 43, "status": 10, "note": null, "created_at": "2025-02-18 18:03:54" }, { "id": 2, "install_code": "INSTALLCODE2", "install_limit": 100, "install_count": 100, "status": 10, "note": "Note", "created_at": "2025-02-18 18:05:54" } ] } ``` * в `data` - массив найденных `install` * `install_count` - текущее количество HWID у данного install * Значения **status**: * 5 - Disabled * 10 - Active
Ошибки валидации/авторизации ```json { "rc": 0, "msg": "Auth error" } ``` ```json { "rc": 0, "msg": "This feature requires an active subscription" } ``` ```json { "rc": 0, "msg": "Unknown error" } ```
**Пример** ```bash curl -X 'GET' '{url_api}/api/list-install?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_12345' \ -H 'accept: application/json' ``` *** **GET `/api/list-hwid`** **Назначение:** получить список hwid по ссылке провайдера **Query-параметры** * `provider_code` *(string, required)* — 8 символов * `auth_key` *(string, required)* — 32 символа * `install_code` *(string, optional)* — обязателен, если не передан `install_id` * `install_id` *(int, optional)* — обязателен, если не передан `install_code` * `hwid` *(string, optional)* — если не передан возвращаются последние 5000 записей **Ответы**
Успешно ```json { "rc": 1, "msg": "Ok", "data": [ { "hwid": "4998793c-3ce5-4ac9-9dfa-0ef5417b00fa", "date": "2025-07-23 13:38:02", "device_name": "DESKTOP-4C6OAQN_x86_64" }, { "hwid": "890877189e13ca8b", "date": "2025-05-15 13:41:49", "device_name": "SM-A528B" } ] } ``` * в `data` - массив найденных `hwid`
Ошибки валидации/авторизации ```json { "rc": 0, "msg": "Auth error" } ``` ```json { "rc": 0, "msg": "This feature requires an active subscription" } ``` ```json { "rc": 0, "msg": "Install code error" } ``` ```json { "rc": 0, "msg": "Unknown error" } ```
**Пример** ```bash curl -X 'GET' '{url_api}/api/list-hwid?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_12345&install_code=INSTIDCODE01' \ -H 'accept: application/json' ``` *** **GET `/api/delete-hwid`** **Назначение:** удалить hwid по ссылке провайдера **Query-параметры** * `provider_code` *(string, required)* — 8 символов * `auth_key` *(string, required)* — 32 символа * `install_code` *(string, optional)* — обязателен, если не передан `install_id` * `install_id` *(int, optional)* — обязателен, если не передан `install_code` * `hwid` *(string, required)* **Ответы**
Успешно ```json { "rc": 1, "msg": "Ok", "install_count": 42 } ``` * `install_count` - текущее количество HWID у данного install
Ошибки валидации/авторизации ```json { "rc": 0, "msg": "Auth error" } ``` ```json { "rc": 0, "msg": "This feature requires an active subscription" } ``` ```json { "rc": 0, "msg": "Invalid parameters" } ``` ```json { "rc": 0, "msg": "Install code error" } ``` ```json { "rc": 0, "msg": "Unknown error" } ```
**Пример** ```bash curl -X 'GET' '{url_api}/api/delete-hwid?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_12345&install_code=INSTIDCODE01&hwid=DEVICEHWID' \ -H 'accept: application/json' ``` *** **GET `/api/add-domain`** **Назначение:** привязать домен подписки к провайдеру. **Query-параметры** * `provider_code` *(string, required)* — 8 символов * `auth_key` *(string, required)* — 32 символа * `domain_name` *(string, optional)* — описание для домена, заданного в `domain_hash`. Если не передан, в качестве описания будут использоваться первые 10 символов `domain_hash` * `domain_hash` *(string, required)* — SHA-256 домена в нижнем регистре (64 hex) **Ответы**
Успешно ```json { "rc": 1, "msg": "Ok", "id": 33 } ```
Такой domain_hash уже существует * `domain_hash` существует, активен ```json { "rc": 2, "msg": "Domain hash exists", "id": 33 } ``` * `domain_hash` существует, не активен, активирован ```json { "rc": 2, "msg": "Domain hash exists. State set to active", "id": 33 } ```
Ошибки валидации/авторизации/сохранения ```json { "rc": 0, "msg": "Auth error" } ``` ```json { "rc": 0, "msg": "This feature requires an active subscription" } ``` ```json { "rc": 0, "msg": "Domain hash error" } ``` ```json { "rc": 0, "msg": "Error save domain" } ``` ```json { "rc": 0, "msg": "Error change state to active" } ``` ```json { "rc": 0, "msg": "Unknown error" } ```
**Пример** ```bash curl -X 'GET' '{url_api}/api/add-domain?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_12345&domain_hash=005c4a974d8b94af421206f9ef34efebab39a7a4d25a81723933892a1fdf2e31&domain_name=sub.example.com' \ -H 'accept: application/json' ``` *** **GET `/api/delete-domain`** **Назначение:** удалить домен провайдера **Query-параметры** * `provider_code` *(string, required)* — 8 символов * `auth_key` *(string, required)* — 32 символа * `id` *(int, required)* **Ответы**
Успешно ```json { "rc": 1, "msg": "Ok" } ```
Ошибки валидации/авторизации/сохранения ```json { "rc": 0, "msg": "Auth error" } ``` ```json { "rc": 0, "msg": "This feature requires an active subscription" } ``` ```json { "rc": 0, "msg": "Domain delete error" } ``` ```json { "rc": 0, "msg": "Domain not found" } ``` ```json { "rc": 0, "msg": "Unknown error" } ```
**Пример** ```bash curl -X 'GET' '{url_api}/api/delete-domain?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_12345&id=33' \ -H 'accept: application/json' ``` *** **GET `/api/list-domain`** **Назначение:** получить список доменов провайдера **Query-параметры** * `provider_code` *(string, required)* — 8 символов * `auth_key` *(string, required)* — 32 символа * `id` *(int, optional)* — если не передан возвращаются последние 5000 записей **Ответы**
Успешно ```json { "rc": 1, "msg": "Ok", "data": [ { "id": 1, "domain_name": "Domain1", "domain_hash": "41e5e446716d7577286255aa55fd03e3420510cb85f20b8968e7010c81aa5468", "status": 10, "created_at": "2025-02-19 22:50:33" }, { "id": 2, "domain_name": "Domain2", "domain_hash": "e9f29ba623b30632f120a6c338ce066685492f2d4fc9544507388b70691a2f17", "status": 5, "created_at": "2025-02-19 22:50:33" } ] } ``` * в `data` - массив найденных `domain` * Значения **status**: * 5 - Disabled * 10 - Active
Ошибки валидации/авторизации ```json { "rc": 0, "msg": "Auth error" } ``` ```json { "rc": 0, "msg": "This feature requires an active subscription" } ``` ```json { "rc": 0, "msg": "Unknown error" } ```
**Пример** ```bash curl -X 'GET' '{url_api}/api/list-domain?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_12345' \ -H 'accept: application/json' ``` *** #### Общие запросы для PUSH-уведомлений и команд удалённого управления **GET `/remote/cancel`** **Назначение:** отмена уведомления или команды **Query-параметры** * `provider_code` *(string, required)* — 8 символов * `auth_key` *(string, required)* — 32 символа * `id` *(int, required)* **Правила:** * Отменить можно только свою рассылку * Нельзя отменять менее чем за **10 минут** до времени отправки **Ответы**
Успешно ```json { "rc": 1, "msg": "Ok" } ```
Ошибки валидации/авторизации/лимитов/отмены ```json { "rc": 0, "msg": "Auth error" } ``` ```json { "rc": 0, "msg": "This feature requires an active subscription" } ``` ```json { "rc": 0, "msg": "Notification not found" } ``` ```json { "rc": 0, "msg": "Cannot cancel notification less than 10 minutes before scheduled time" } ``` ```json { "rc": 0, "msg": "Failed to cancel notification" } ``` ```json { "rc": 0, "msg": "Unknown error" } ```
**Пример** ```bash curl -X GET '{url_api}/remote/cancel?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_12345&id=10' \ -H 'accept: application/json' ``` *** **GET `/remote/list`** **Назначение:** список уведомлений и команд **Query-параметры** * `provider_code` *(string, required)* — 8 символов * `auth_key` *(string, required)* — 32 символа * `id` *(int, optional)* — id уведомления или команды, если не передан возвращаются последние 5000 записей **Ответы**
Успешно ```json { "rc": 1, "msg": "Ok", "data": [ { "id": 585, "target_os": null, "target_hwid": "e2a1b20d417fdf9e", "status": 100, "created_at": "2025-11-18 23:20:22", "sent_at": "2025-11-18 23:21:02", "notification_type": 20 }, { "id": 584, "target_os": null, "target_hwid": "e2a1b20d417fdf9e", "status": 110, "created_at": "2025-11-18 23:19:24", "sent_at": "2025-11-18 23:20:01", "notification_type": 20 } ] } ``` * в `data` - массив найденных `push` * Значения **status**: * 5 - Load * 6 - Load from * 10 - Created * 20 - Checking * 30 - Pending * 40 - Sending * 100 - Sent * 110 - Sent with errors * 120 - Failed * 130 - Cancelled * 140 - Blocked * Значения **notification\_type**: * 10 - Push * 20 - Command
Ошибки валидации/авторизации ```json { "rc": 0, "msg": "Auth error" } ``` ```json { "rc": 0, "msg": "This feature requires an active subscription" } ``` ```json { "rc": 0, "msg": "Unknown error" } ```
**Пример** ```bash curl -X GET '{url_api}/remote/list?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_12345&id=10' \ -H 'accept: application/json' ``` *** #### Массовые PUSH-уведомления **POST `/remote/notification`** **Доступ:** требуется **активная подписка** и тариф **Enterprise** **Query** * `provider_code` *(string, required)* — 8 символов * `auth_key` *(string, required)* — 32 символа **Минимальный body (JSON)** ```json { "PushNotificationForm": { "body": "Please update your app to the latest version", "type_push": "optional", "expire_days": 7 }, "os": ["android"] } ``` **Body (JSON)** ```json { "PushNotificationForm": { "title": "Default title", "body": "Default body", "link_for_open": "https://example.com/", "background_image": "https://example.com/image.jpg", "locales": { "RU": { "title": "Важное обновление", "body": "Пожалуйста, обновите приложение до последней версии", "link-for-open": "https://example.com/?ru" }, "EN": { "title": "Important Update", "body": "Please update your app to the latest version", "link-for-open": "https://example.com/?en" }, "CN": { "title": "Important Update", "body": "Please update your app to the latest version", "link-for-open": "https://example.com/?cn" }, "FA": { "title": "Important Update", "body": "Please update your app to the latest version", "link-for-open": "https://example.com/?fa" } }, "type_push": "force", "expire_days": 7, "send_date": "2025-12-31", "send_time": "23:59" }, "hwid": "HWID1,HWID2" } ``` **Ограничения и валидация** * `type_push` может принимать значения: * `force` * `optional` * `send_date` - в формате `YYYY-MM-DD` * `send_time` - в формате `HH:MM`, часовой пояс UTC +3 * `hwid` - строка, до 5 `hwid` через запятую, параметр `os` не учитывается * `os` - массив OS, обязателен, если не указан параметр `hwid` * Тело сообщения сериализуется как JSON и кодируется base64; **размер base64-строки ≤ 4096 байт**. * Если отправка **не по конкретным HWID**, действует антиспам: **не чаще 1 раза в 5 минут** на «общую» рассылку. * VPN провайдер: * с `hwid` — HWID должны принадлежать пользователю. * с `os` — рассылка только по устройствам пользователя с указанной OS **Ответы**
Успешно ```json { "rc": 1, "msg": "Ok", "id": 10 } ```
Ошибки валидации/авторизации/лимитов/сохранения ```json { "rc": 0, "msg": "Auth error" } ``` ```json { "rc": 0, "msg": "This feature requires an active subscription" } ``` ```json { "rc": 0, "msg": "This feature requires Enterprise plan" } ``` ```json { "rc": 0, "msg": "You can send general notifications only once every 5 minutes" } ``` ```json { "rc": 0, "msg": "Message too large (max 4096 bytes)" } ``` ```json { "rc": 0, "msg": "Device with this HWID not found" } ``` ```json { "rc": 0, "msg": "No devices found for selected OS and your provider IDs" } ``` ```json { "rc": 0, "msg": "Failed to save notification" } ``` ```json { "rc": 0, "msg": "Unknown error" } ```
**Пример** ```bash curl -X POST '{url_api}/remote/notification?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_12345' \ -H 'Content-Type: application/json' \ -d '{ "PushNotificationForm": { "body": "Please update your app to the latest version", "type_push": "optional", "expire_days": 7 }, "os": ["android"] }' ``` ```bash curl -X POST '{url_api}/remote/notification?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_12345' \ -H 'Content-Type: application/json' \ -d '{ "PushNotificationForm": { "title": "Default title", "body": "Default body", "link_for_open": "https://example.com/", "background_image": "https://example.com/image.jpg", "locales": { "RU": { "title": "Важное обновление", "body": "Пожалуйста, обновите приложение до последней версии", "link-for-open": "https://example.com/?ru" }, "EN": { "title": "Important Update", "body": "Please update your app to the latest version", "link-for-open": "https://example.com/?en" }, "CN": { "title": "Important Update", "body": "Please update your app to the latest version", "link-for-open": "https://example.com/?cn" }, "FA": { "title": "Important Update", "body": "Please update your app to the latest version", "link-for-open": "https://example.com/?fa" } }, "type_push": "force", "expire_days": 7, "send_date": "2025-12-31", "send_time": "23:59" }, "hwid": "HWID1,HWID2" }' ``` *** #### Команды удалённого управления (Remote Control) **POST `/remote/command`** **Доступ:** требуется **активная подписка** и тариф **Pro** или **Enterprise** **Query** * `provider_code` *(string, required)* — 8 символов * `auth_key` *(string, required)* — 32 символа **Body (JSON)** **Общие параметры для всех команд:** * Значения `specific_device_toggle`: * `true` - параметр `hwid` обязателен, иначе ошибка `HWID is required for specific device`. Параметр `os` - не учитывается * `false` - параметр `os` обязателен, должен быть непустым, иначе ошибка `Select at least one OS or enable specific device`. Параметр `hwid` - не учитывается * `send_date` - в формате `YYYY-MM-DD` * `send_time` - в формате `HH:MM`, часовой пояс UTC +3 * `hwid` - строка, до 5 HWID через запятую, обязательно при `specific_device_toggle=true` * `os` - массив OS, обязательно при `specific_device_toggle=false` 1. **Отправить данные для импорта** ```json { "action_type": "import-data", "import_data": "raw string to import", "specific_device_toggle": false, "os": ["ios","android"] } ``` ```json { "action_type": "import-data", "import_data": "raw string to import", "specific_device_toggle": true, "hwid": "HWID1,HWID2" } ``` * `import_data` - будет закодировано в base64 и передано как "input-data" 2. **Обновить все подписки** ```json { "action_type": "update-subscription", "specific_device_toggle": true, "hwid": "HWID1,HWID2" } ``` 3. **Установить настройки** ```json { "action_type": "set-settings", "settings": { "log_level": "info", "featureX": true }, "specific_device_toggle": true, "hwid": "HWID1,HWID2" } ``` * `settings` - обязателен, должен быть корректным JSON **Параметры настройки приложения** | Название параметра | Значения | | -------------------------------------- | ------------------------------ | | `fragmentation-enable` | `true` /`false` | | `fragmentation-packets` | `"tlshello"` / `"1-3"` | | `fragmentation-length` | Int | | `fragmentation-interval` | Int | | `local-dns-enable` | `true` /`false` | | `subscription-auto-update-enable` | `true` /`false` | | `subscription-auto-update-open-enable` | `true` /`false` | | `subscription-always-hwid-enable` | `true` /`false` | | `subscription-autoconnect` | `true` /`false` | | `subscription-ping-onopen-enabled` | `true` /`false` | | `subscription-autoconnect-type` | `"lastused"` / `"lowestdelay"` | | `notification-subs-expire` | `true` /`false` | | `check-url-via-proxy` | String | | `ping-type` | `"proxy"` / `"tcp"` / `"icmp"` | | `fragmentation-type` | `"xray"` / `"advanced"` | | `fragmentation-advanced-param` | String | | `change-user-agent` | String | | `app-auto-start` | `true` /`false` | | `server-address-resolve-enable` | `true` /`false` | | `server-address-resolve-dns-ip` | String | | `server-address-resolve-dns-domain` | String | | `per-app-proxy-mode` | `"off"` / `"on"` / `"bypass"` | | `per-app-proxy-list` | String | | Custom | String | * `Custom` - строка, любой произвольный ключ 4. **Изменение подписки** ```json { "action_type": "sub-change", "change_type": "domain", "change_value": "example.com", "specific_device_toggle": false, "os": ["ios","android"] } ``` * Значения `change_type`: * `domain` * `url` **Ответы**
Успешно ```json { "rc": 1, "msg": "Ok", "id": 10 } ```
Ошибки валидации/авторизации/лимитов/сохранения ```json { "rc": 0, "msg": "Auth error" } ``` ```json { "rc": 0, "msg": "This feature requires an active subscription" } ``` ```json { "rc": 0, "msg": "This feature requires Pro or Enterprise plan" } ``` ```json { "rc": 0, "msg": "HWID is required for specific device" } ``` ```json { "rc": 0, "msg": "Select at least one OS or enable specific device" } ``` ```json { "rc": 0, "msg": "Import data cannot be empty" } ``` ```json { "rc": 0, "msg": "Settings cannot be empty" } ``` ```json { "rc": 0, "msg": "Action is not allowed for not linked HWIDs" } ``` ```json { "rc": 0, "msg": "Device with this HWID not found" } ``` ```json { "rc": 0, "msg": "The maximum number of commands to unbound HWIDs has been exceeded" } ``` ```json { "rc": 0, "msg": "Failed to save command" } ``` ```json { "rc": 0, "msg": "Unknown error" } ```
**Пример** ```bash curl -X POST '{url_api}/remote/command?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_12345' \ -H 'Content-Type: application/json' \ -d '{ "action_type":"set-settings", "settings": {"ping-type": "proxy"}, "specific_device_toggle":true, "hwid":"HWID-1" }' ``` *** #### Дополнительно * **Разрешённые HTML-теги** в `body` уведомлений отфильтровываются (разрешены базовые теги: `a,b,big,blockquote,br,cite,del,dfn,div,em,i,img,li,p,s,small,span,strike,strong,sub,sup,tt,u,ul`; разрешённые атрибуты: `href,title,src,alt`; разрешены `target="_blank"`). * **OS-значения** — `ios`, `android`. * **Лимиты**: * `/remote/notification`: общий пуш без `hwid` — не чаще 1 раза в 5 минут. * Payload уведомления после base64 — до **4096 байт**. * HWID в точечных отправках — до **5** штук за раз. *** **Краткая сводка валидаций по RegExp** | Поле | Регулярка | | --------------- | --------------------- | | `provider_code` | `^[A-Za-z0-9]{8}$` | | `auth_key` | `^[-_A-Za-z0-9]{32}$` | | `install_code` | `^[A-Za-z0-9]{12}$` | | `domain_hash` | `^[a-f0-9]{64}$` | | `install_limit` | целое `1..100` | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.happ-proxy.com/ru/getting-started/api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.