Partner API

Szybki start

Utwórz token i przesyłaj go w nagłówku Authorization. Dla POST używaj JSON i Content-Type: application/json.

Adres APIhttps://proxycola.com/api/v1/

Limit zapytań300/min

Pierwsze żądanie · sprawdź token

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

Pobierz OpenAPI Wszystkie metody do importu w Postman.

Konto i katalog

GET /api/v1/account/ Konto i limity

Sprawdź token i pobierz ID, e-mail konta oraz limit żądań na minutę.

Żądanie · curl

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

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

Przykład odpowiedzi jest skrócony. ID, ceny i dane dostępu są przykładowe.

GET /api/v1/balance/ Saldo w USD

Sprawdź saldo w USD przed zakupem lub przedłużeniem.

Żądanie · curl

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

Odpowiedź · JSON

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

Przykład odpowiedzi jest skrócony. ID, ceny i dane dostępu są przykładowe.

GET /api/v1/catalog/ Kraje i plany

Pobierz kraje, operatorów i plany. Używaj ich kodów oraz wartości amount przy zakupie.

Wybierz kraj z is_available=true i operatora z is_sellable=true. plans zawiera ceny według liczby dni, np. plans["30"].

Żądanie · curl

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

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

Przykład odpowiedzi jest skrócony. ID, ceny i dane dostępu są przykładowe.

Zakup i przedłużenie

POST /api/v1/proxies/quote/ Oblicz cenę

Oblicz cenę zakupu lub przedłużenia przed płatnością. Bez pobierania środków.

Parametry JSON

Parametr	Typ	Wymagany	Co przesłać
`plan_type`	`"time"`	Przy zakupie	Typ planu z katalogu.
`amount`	`integer`	Tak	Liczba dni z katalogu.
`country_code`	`string`	Przy zakupie	Kod kraju z countries[].code.
`operator_code`	`string`	Przy zakupie	Kod dostępnego operatora wybranego kraju z operators[].code.
`quantity`	`integer`	Nie	1–10. Domyślnie 1.
`max_total`	`string`	Nie	Maksymalna kwota w USD, np. "20.00". Wyższa cena jest odrzucana bez opłaty.
`proxy_id`	`integer`	Przy przedłużeniu	Do wyceny przedłużenia zamiast parametrów zakupu.

Dla przedłużenia wyślij tylko proxy_id, amount i opcjonalnie max_total. Wycena nie rezerwuje ceny ani dostępności.

Żądanie · 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"
}'

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

Przykład odpowiedzi jest skrócony. ID, ceny i dane dostępu są przykładowe.

POST /api/v1/proxies/buy/ Kup proxy

Kup 1–10 proxy z salda jednym żądaniem. W razie błędu cały zakup jest anulowany.

Parametry JSON

Parametr	Typ	Wymagany	Co przesłać
`plan_type`	`"time"`	Tak	Typ planu z katalogu.
`amount`	`integer`	Tak	Liczba dni z katalogu.
`country_code`	`string`	Tak	Kod kraju z countries[].code.
`operator_code`	`string`	Tak	Kod dostępnego operatora wybranego kraju z operators[].code.
`quantity`	`integer`	Nie	1–10. Domyślnie 1.
`max_total`	`string`	Nie	Maksymalna kwota w USD, np. "20.00". Wyższa cena jest odrzucana bez opłaty.

Użyj zwróconych proxy_ids w GET /proxies/?ids=… po dane połączenia. HTTP 201: zakup; 200 i replayed=true: wcześniejszy wynik. Aktywacja może chwilę potrwać.

Wymagany nagłówek Idempotency-Key: 8–128 liter, cyfr lub . _ : -. Nowa operacja wymaga nowego klucza. Po timeout powtórz to samo żądanie i klucz, aby uniknąć drugiej opłaty.

Żądanie · 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"
}'

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

Przykład odpowiedzi jest skrócony. ID, ceny i dane dostępu są przykładowe.

POST /api/v1/proxies/renew/ Przedłuż proxy

Dodaj dni do swojego proxy. Niewykorzystany czas pozostaje; wygasły okres zaczyna się od przedłużenia.

Parametry JSON

Parametr	Typ	Wymagany	Co przesłać
`proxy_id`	`integer`	Tak	ID własnego proxy z GET /proxies/.
`amount`	`integer`	Tak	Liczba dni z katalogu.
`max_total`	`string`	Nie	Maksymalna kwota w USD, np. "20.00". Wyższa cena jest odrzucana bez opłaty.

Login, hasło i port pozostają bez zmian. Nie można przedłużyć zablokowanego lub archiwalnego proxy. Sukces: HTTP 200; replayed=true oznacza brak nowej opłaty.

Wymagany nagłówek Idempotency-Key: 8–128 liter, cyfr lub . _ : -. Nowa operacja wymaga nowego klucza. Po timeout powtórz to samo żądanie i klucz, aby uniknąć drugiej opłaty.

Żądanie · 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"
}'

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

Przykład odpowiedzi jest skrócony. ID, ceny i dane dostępu są przykładowe.

Zarządzanie proxy

GET /api/v1/proxies/ Proxy i dane dostępu

Pobierz proxy z loginem, hasłem, adresami połączenia i ustawieniami. Filtruj według ID, portu lub stanu.

Parametry query

Parametr	Typ	Wymagany	Co przesłać
`ids`	`string`	Nie	1–100 ID oddzielonych przecinkami, np. 1702,1703.
`port`	`integer`	Nie	Port proxy: 1–65535.
`status`	`string`	Nie	all — wszystkie, active — aktywne, expired — nieaktywne. Domyślnie all.
`limit`	`integer`	Nie	Rozmiar strony: 1–500. Domyślnie 100.
`offset`	`integer`	Nie	Liczba pomijanych wyników. Domyślnie 0.

Filtry działają razem. pagination.total liczy wyniki przed stronicowaniem. Archiwalne proxy są pomijane. traffic_left w bajtach; daty w UTC.

Żądanie · curl

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

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

Przykład odpowiedzi jest skrócony. ID, ceny i dane dostępu są przykładowe.

POST /api/v1/proxies/settings/ Ustawienia proxy

Zmień interwał rotacji IP, automatyczne przedłużanie, hasło lub dozwolone IP. Zmieniają się tylko przesłane ustawienia.

Parametry JSON

Parametr	Typ	Wymagany	Co przesłać
`proxy_id`	`integer`	Tak	ID własnego proxy z GET /proxies/.
`auto_renew`	`boolean`	Nie	true włącza, false wyłącza. Włączanie tylko dla płatnych proxy.
`ip_change_interval`	`integer`	Nie	Interwał rotacji IP w minutach: 0–1440. 0 wyłącza timer.
`password`	`string`	Nie	Nowe hasło: 12–64 drukowalne znaki ASCII bez spacji.
`ip_bindings`	`string[]`	Nie	Do 10 dozwolonych adresów IPv4. [] usuwa ograniczenie IP.

Tylko aktywne proxy. Podaj co najmniej jedno ustawienie. Błąd niczego nie zmienia; identyczne powtórzenia są bezpieczne. Zmiany mogą wymagać krótkiej chwili.

Żądanie · 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"
    ]
}'

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

Przykład odpowiedzi jest skrócony. ID, ceny i dane dostępu są przykładowe.

POST /api/v1/proxies/set-location/ Zmień lokalizację

Przełącz aktywne proxy na inny kraj i operatora z katalogu.

Parametry JSON

Parametr	Typ	Wymagany	Co przesłać
`proxy_id`	`integer`	Tak	ID własnego proxy z GET /proxies/.
`country_code`	`string`	Tak	Kod kraju z countries[].code.
`operator_code`	`string`	Tak	Kod dostępnego operatora wybranego kraju z operators[].code.

Zmiana kraju co 10 minut, operatora co 5 minut. Pozostały płatny czas jest przeliczany według ceny nowego kraju.

Żądanie · 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"
}'

Odpowiedź · JSON

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

Przykład odpowiedzi jest skrócony. ID, ceny i dane dostępu są przykładowe.

POST /api/v1/proxies/set-operator/ Zmień operatora

Zmień operatora bez zmiany kraju proxy. Kod operatora pobierz z katalogu.

Parametry JSON

Parametr	Typ	Wymagany	Co przesłać
`proxy_id`	`integer`	Tak	ID własnego proxy z GET /proxies/.
`operator_code`	`string`	Tak	Kod dostępnego operatora wybranego kraju z operators[].code.

Operatora można zmieniać co 5 minut. Przy ograniczeniu data.retry_after podaje czas oczekiwania w sekundach.

Żądanie · 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"
}'

Odpowiedź · JSON

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

Przykład odpowiedzi jest skrócony. ID, ceny i dane dostępu są przykładowe.

POST /api/v1/proxies/change-ip/ Zmień IP

Poproś o nowy wyjściowy adres IP aktywnego proxy. Po zmianie sprawdź adres przez check-ip.

Parametry JSON

Parametr	Typ	Wymagany	Co przesłać
`proxy_id`	`integer`	Tak	ID własnego proxy z GET /proxies/.

Żądanie · 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
}'

Odpowiedź · JSON

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

Przykład odpowiedzi jest skrócony. ID, ceny i dane dostępu są przykładowe.

POST /api/v1/proxies/check-ip/ Sprawdź obecne IP

Sprawdź obecny wyjściowy adres IP aktywnego proxy. Żądanie sprawdza połączenie bez zmiany IP.

Parametry JSON

Parametr	Typ	Wymagany	Co przesłać
`proxy_id`	`integer`	Tak	ID własnego proxy z GET /proxies/.

Żądanie · 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
}'

Odpowiedź · JSON

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

Przykład odpowiedzi jest skrócony. ID, ceny i dane dostępu są przykładowe.

Błędy i ponawianie

Przy sukcesie odczytaj data, przy błędzie error i message. Zachowaj request_id dla wsparcia.

401: Sprawdź token i nagłówek Authorization: Bearer <TOKEN>.
402: Za mało środków. Doładuj saldo; data.needed pokazuje brakującą kwotę.
404: Nie znaleziono proxy. Sprawdź proxy_id na swojej liście.
409: Sprawdź error: cena przekracza max_total, klucz użyty z innymi parametrami lub czynność niedostępna dla proxy.
429: Zbyt wiele żądań. Jeśli jest Retry-After lub data.retry_after, odczekaj podaną liczbę sekund; w przeciwnym razie wydłuż przerwę.
500: Błąd tymczasowy. Spróbuj później; zakup i przedłużenie tylko z tym samym Idempotency-Key.

Przykład błędu

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