Partner API

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

Создайте токен и передавайте его в заголовке Authorization. Для POST используйте JSON и Content-Type: application/json.

Адрес APIhttps://proxycola.com/api/v1/

Лимит300/min

Первый запрос · проверка токена

curl "https://proxycola.com/api/v1/account/" \
  -H "Authorization: Bearer <TOKEN>"

Скачать OpenAPI Все методы для импорта в Postman.

Аккаунт и каталог

GET /api/v1/account/ Аккаунт и лимит

Проверьте токен и узнайте ID, email аккаунта и лимит запросов в минуту.

Запрос · curl

curl "https://proxycola.com/api/v1/account/" \
  -H "Authorization: Bearer <TOKEN>"

Ответ · JSON

{
    "success": true,
    "data": {
        "user": {
            "id": 42,
            "email": "you@example.com"
        },
        "api_key": {
            "id": 1,
            "name": "Partner API",
            "rate_limit_per_minute": 300
        }
    },
    "request_id": "..."
}

Пример ответа сокращён. ID, цены и данные подключения приведены для примера.

GET /api/v1/balance/ Баланс в USD

Узнайте остаток средств в USD перед покупкой или продлением.

Запрос · curl

curl "https://proxycola.com/api/v1/balance/" \
  -H "Authorization: Bearer <TOKEN>"

Ответ · JSON

{
    "success": true,
    "data": {
        "balance": 100,
        "currency": "usd",
        "balance_text": "$100.00"
    },
    "request_id": "..."
}

Пример ответа сокращён. ID, цены и данные подключения приведены для примера.

GET /api/v1/catalog/ Страны и тарифы

Получите страны, операторов и тарифы. Используйте их коды и значения amount в запросах покупки.

Выбирайте страну с is_available=true и оператора с is_sellable=true. plans содержит цены по количеству дней, например plans["30"].

Запрос · curl

curl "https://proxycola.com/api/v1/catalog/" \
  -H "Authorization: Bearer <TOKEN>"

Ответ · JSON

{
    "success": true,
    "data": {
        "countries": [
            {
                "id": 1,
                "code": "ua",
                "name": "Ukraine",
                "operators": [
                    {
                        "id": 1,
                        "code": "kyivstar",
                        "name": "Kyivstar",
                        "is_active": 1,
                        "availables": 10,
                        "is_sellable": true
                    }
                ],
                "plans": {
                    "30": {
                        "id": 1,
                        "amount": 30,
                        "price": "10.00",
                        "old_price": null,
                        "currency": "usd",
                        "is_active": 1,
                        "sort": 30
                    }
                },
                "is_available": true
            }
        ]
    },
    "request_id": "..."
}

Пример ответа сокращён. ID, цены и данные подключения приведены для примера.

Покупка и продление

POST /api/v1/proxies/quote/ Расчёт стоимости

Узнайте стоимость покупки или продления до оплаты. Деньги не списываются.

Параметры JSON

Параметр	Тип	Обязателен	Что передать
`plan_type`	`"time"`	При покупке	Тип тарифа из каталога.
`amount`	`integer`	Да	Количество дней из каталога.
`country_code`	`string`	При покупке	Код страны из countries[].code.
`operator_code`	`string`	При покупке	Код доступного оператора выбранной страны из operators[].code.
`quantity`	`integer`	Нет	От 1 до 10. По умолчанию 1.
`max_total`	`string`	Нет	Максимальная сумма в USD, например "20.00". Если цена выше, списания не будет.
`proxy_id`	`integer`	При продлении	Для расчёта продления вместо параметров покупки.

Для продления передайте только proxy_id, amount и при необходимости max_total. Расчёт не резервирует цену и наличие.

Запрос · curl

curl -X POST "https://proxycola.com/api/v1/proxies/quote/" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_type": "time",
    "amount": 30,
    "country_code": "ua",
    "operator_code": "kyivstar",
    "max_total": "10.00"
}'

Ответ · JSON

{
    "success": true,
    "data": {
        "plan_type": "time",
        "plan_id": 1,
        "amount": 30,
        "unit": "days",
        "quantity": 1,
        "country_id": 1,
        "country_code": "ua",
        "operator_id": 1,
        "operator_code": "kyivstar",
        "unit_price": "10.00",
        "total": "10.00",
        "currency": "usd"
    },
    "request_id": "..."
}

Пример ответа сокращён. ID, цены и данные подключения приведены для примера.

POST /api/v1/proxies/buy/ Купить прокси

Купите от 1 до 10 прокси с баланса одним запросом. При ошибке покупка целиком отменяется.

Параметры JSON

Параметр	Тип	Обязателен	Что передать
`plan_type`	`"time"`	Да	Тип тарифа из каталога.
`amount`	`integer`	Да	Количество дней из каталога.
`country_code`	`string`	Да	Код страны из countries[].code.
`operator_code`	`string`	Да	Код доступного оператора выбранной страны из operators[].code.
`quantity`	`integer`	Нет	От 1 до 10. По умолчанию 1.
`max_total`	`string`	Нет	Максимальная сумма в USD, например "20.00". Если цена выше, списания не будет.

Возвращает proxy_ids: передайте их в GET /proxies/?ids=… для подключения. HTTP 201 — покупка, 200 и replayed=true — результат прежнего запроса. Активация может занять некоторое время.

Обязателен заголовок Idempotency-Key: 8–128 латинских букв, цифр или . _ : -. Для новой операции используйте новый ключ. При таймауте повторите тот же запрос и ключ — без повторного списания.

Запрос · curl

curl -X POST "https://proxycola.com/api/v1/proxies/buy/" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Idempotency-Key: <UNIQUE_OPERATION_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_type": "time",
    "amount": 30,
    "country_code": "ua",
    "operator_code": "kyivstar",
    "max_total": "10.00"
}'

Ответ · JSON

{
    "success": true,
    "data": {
        "operation_id": 42,
        "proxy_ids": [
            1702
        ],
        "quote": {
            "plan_type": "time",
            "plan_id": 1,
            "amount": 30,
            "unit": "days",
            "quantity": 1,
            "country_id": 1,
            "country_code": "ua",
            "operator_id": 1,
            "operator_code": "kyivstar",
            "unit_price": "10.00",
            "total": "10.00",
            "currency": "usd"
        },
        "balance_after": "90.00",
        "replayed": false
    },
    "request_id": "..."
}

Пример ответа сокращён. ID, цены и данные подключения приведены для примера.

POST /api/v1/proxies/renew/ Продлить прокси

Добавьте дни к своему прокси. Неиспользованный остаток сохраняется; истёкший срок начинается с момента продления.

Параметры JSON

Параметр	Тип	Обязателен	Что передать
`proxy_id`	`integer`	Да	ID вашего прокси из GET /proxies/.
`amount`	`integer`	Да	Количество дней из каталога.
`max_total`	`string`	Нет	Максимальная сумма в USD, например "20.00". Если цена выше, списания не будет.

Логин, пароль и порт сохраняются. Заблокированный или архивный прокси продлить нельзя. Успех: HTTP 200; replayed=true — повтор без нового списания.

Запрос · curl

curl -X POST "https://proxycola.com/api/v1/proxies/renew/" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Idempotency-Key: <UNIQUE_OPERATION_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "proxy_id": 1702,
    "amount": 30,
    "max_total": "10.00"
}'

Ответ · JSON

{
    "success": true,
    "data": {
        "proxy_id": 1702,
        "quote": {
            "proxy_id": 1702,
            "plan_type": "time",
            "plan_id": 1,
            "amount": 30,
            "unit": "days",
            "quantity": 1,
            "unit_price": "10.00",
            "total": "10.00",
            "currency": "usd"
        },
        "expires_at": "2026-11-25 12:00:00",
        "traffic_left": 0,
        "operation_id": 43,
        "balance_after": "80.00",
        "replayed": false
    },
    "request_id": "..."
}

Пример ответа сокращён. ID, цены и данные подключения приведены для примера.

Управление прокси

GET /api/v1/proxies/ Прокси и доступы

Получите список прокси с логином, паролем, адресами подключения и настройками. Найдите нужные по ID, порту или состоянию.

Параметры query

Параметр	Тип	Обязателен	Что передать
`ids`	`string`	Нет	От 1 до 100 ID через запятую, например 1702,1703.
`port`	`integer`	Нет	Порт прокси: 1–65535.
`status`	`string`	Нет	all — все, active — активные, expired — неактивные. По умолчанию all.
`limit`	`integer`	Нет	Размер страницы: 1–500. По умолчанию 100.
`offset`	`integer`	Нет	Сколько результатов пропустить. По умолчанию 0.

Фильтры применяются вместе. pagination.total — число найденных прокси до разбивки на страницы. Архивные прокси не возвращаются. traffic_left — байты; даты — UTC.

Запрос · curl

curl "https://proxycola.com/api/v1/proxies/?ids=1702,1703" \
  -H "Authorization: Bearer <TOKEN>"

Ответ · JSON

{
    "success": true,
    "data": {
        "items": [
            {
                "id": 1702,
                "host": "tproxy.pro",
                "port": 20000,
                "login": "example_user",
                "password": "<PROXY_PASSWORD>",
                "http_url": "http://example_user:<PROXY_PASSWORD>@tproxy.pro:20000",
                "socks5_url": "socks5://example_user:<PROXY_PASSWORD>@tproxy.pro:20000",
                "udp_supported": false,
                "plan_type": "time",
                "status": 1,
                "is_active": true,
                "expires_at": "2026-10-25 12:00:00",
                "traffic_left": 0,
                "country": {
                    "id": 1,
                    "code": "ua",
                    "name": "Ukraine"
                },
                "operator": {
                    "id": 1,
                    "code": "kyivstar",
                    "name": "Kyivstar"
                },
                "auto_renew": false,
                "ip_change_interval": 0,
                "ip_bindings": []
            }
        ],
        "pagination": {
            "limit": 100,
            "offset": 0,
            "total": 1
        }
    },
    "request_id": "..."
}

Пример ответа сокращён. ID, цены и данные подключения приведены для примера.

POST /api/v1/proxies/settings/ Настройки прокси

Измените таймер смены IP, автопродление, пароль или разрешённые IP. Меняются только переданные настройки.

Параметры JSON

Параметр	Тип	Обязателен	Что передать
`proxy_id`	`integer`	Да	ID вашего прокси из GET /proxies/.
`auto_renew`	`boolean`	Нет	true — включить, false — выключить. Включение только для платных прокси.
`ip_change_interval`	`integer`	Нет	Интервал смены IP в минутах: 0–1440. 0 отключает таймер.
`password`	`string`	Нет	Новый пароль: 12–64 печатных ASCII-символа без пробелов.
`ip_bindings`	`string[]`	Нет	До 10 разрешённых IPv4-адресов. [] снимает ограничение по IP.

Только для активного прокси. Передайте хотя бы одну настройку. При ошибке ничего не меняется; повтор тех же значений безопасен. Изменения применяются с небольшой задержкой.

Запрос · curl

curl -X POST "https://proxycola.com/api/v1/proxies/settings/" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "proxy_id": 1702,
    "auto_renew": true,
    "ip_change_interval": 10,
    "ip_bindings": [
        "192.0.2.10"
    ]
}'

Ответ · JSON

{
    "success": true,
    "data": {
        "proxy_id": 1702,
        "changed": true,
        "settings": {
            "auto_renew": true,
            "ip_change_interval": 10,
            "ip_bindings": [
                "192.0.2.10"
            ]
        }
    },
    "request_id": "..."
}

Пример ответа сокращён. ID, цены и данные подключения приведены для примера.

POST /api/v1/proxies/set-location/ Выбрать локацию

Переключите активный прокси на другую страну и оператора из каталога.

Параметры JSON

Параметр	Тип	Обязателен	Что передать
`proxy_id`	`integer`	Да	ID вашего прокси из GET /proxies/.
`country_code`	`string`	Да	Код страны из countries[].code.
`operator_code`	`string`	Да	Код доступного оператора выбранной страны из operators[].code.

Страну можно менять раз в 10 минут, оператора — раз в 5 минут. При смене страны оставшийся срок платного прокси пересчитывается по цене новой страны.

Запрос · curl

curl -X POST "https://proxycola.com/api/v1/proxies/set-location/" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "proxy_id": 1702,
    "country_code": "ua",
    "operator_code": "kyivstar"
}'

Ответ · JSON

{
    "success": true,
    "data": {
        "proxy_id": 1702,
        "country_code": "ua",
        "operator_code": "kyivstar"
    },
    "request_id": "..."
}

Пример ответа сокращён. ID, цены и данные подключения приведены для примера.

POST /api/v1/proxies/set-operator/ Сменить оператора

Смените оператора, сохранив текущую страну прокси. Код оператора возьмите из каталога.

Параметры JSON

Параметр	Тип	Обязателен	Что передать
`proxy_id`	`integer`	Да	ID вашего прокси из GET /proxies/.
`operator_code`	`string`	Да	Код доступного оператора выбранной страны из operators[].code.

Менять оператора можно раз в 5 минут. При ограничении ответ содержит data.retry_after — сколько секунд подождать.

Запрос · curl

curl -X POST "https://proxycola.com/api/v1/proxies/set-operator/" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "proxy_id": 1702,
    "operator_code": "kyivstar"
}'

Ответ · JSON

{
    "success": true,
    "data": {
        "proxy_id": 1702,
        "country_code": "ua",
        "operator_code": "kyivstar"
    },
    "request_id": "..."
}

Пример ответа сокращён. ID, цены и данные подключения приведены для примера.

POST /api/v1/proxies/change-ip/ Сменить IP

Запросите новый выходной IP для активного прокси. После смены проверьте адрес через check-ip.

Параметры JSON

Параметр	Тип	Обязателен	Что передать
`proxy_id`	`integer`	Да	ID вашего прокси из GET /proxies/.

Запрос · curl

curl -X POST "https://proxycola.com/api/v1/proxies/change-ip/" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "proxy_id": 1702
}'

Ответ · JSON

{
    "success": true,
    "data": {
        "proxy_id": 1702,
        "hub_response": {}
    },
    "request_id": "..."
}

Пример ответа сокращён. ID, цены и данные подключения приведены для примера.

POST /api/v1/proxies/check-ip/ Узнать текущий IP

Узнайте текущий выходной IP активного прокси. Запрос проверяет подключение и не меняет IP.

Параметры JSON

Параметр	Тип	Обязателен	Что передать
`proxy_id`	`integer`	Да	ID вашего прокси из GET /proxies/.

Запрос · curl

curl -X POST "https://proxycola.com/api/v1/proxies/check-ip/" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "proxy_id": 1702
}'

Ответ · JSON

{
    "success": true,
    "data": {
        "proxy_id": 1702,
        "current_ip": "203.0.113.10"
    },
    "request_id": "..."
}

Пример ответа сокращён. ID, цены и данные подключения приведены для примера.

Ошибки и повтор запросов

При успехе читайте data. При ошибке — error и message. Сохраните request_id для обращения в поддержку.

401: Проверьте токен и заголовок Authorization: Bearer <TOKEN>.
402: Недостаточно средств. Пополните баланс; data.needed показывает недостающую сумму.
404: Прокси не найден. Проверьте proxy_id в списке своих прокси.
409: Проверьте error: цена выше max_total, ключ использован с другими параметрами или действие недоступно для этого прокси.
429: Слишком частые запросы. Если есть Retry-After или data.retry_after, подождите указанное число секунд; иначе увеличьте паузу между запросами.
500: Временная ошибка. Повторите позже; покупку и продление — только с тем же Idempotency-Key.

Пример ошибки

{
    "success": false,
    "error": "insufficient_balance",
    "message": "Insufficient balance",
    "data": {
        "needed": "5.00"
    },
    "request_id": "..."
}