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": "..."
}