Partner API

Pornire rapidă

Creați un token și trimiteți-l în antetul Authorization. Pentru POST folosiți JSON și Content-Type: application/json.

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

Limită de cereri300/min

Prima cerere · verificarea tokenului

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

Descarcă OpenAPI Toate metodele pentru import în Postman.

Cont și catalog

GET /api/v1/account/ Cont și limite

Verificați tokenul și aflați ID-ul, e-mailul contului și limita de cereri pe minut.

Cerere · curl

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

Răspuns · 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": "..."
}

Exemplul de răspuns este prescurtat. ID-urile, prețurile și datele de acces sunt ilustrative.

GET /api/v1/balance/ Sold în USD

Verificați soldul în USD înainte de cumpărare sau prelungire.

Cerere · curl

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

Răspuns · JSON

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

Exemplul de răspuns este prescurtat. ID-urile, prețurile și datele de acces sunt ilustrative.

GET /api/v1/catalog/ Țări și planuri

Obțineți țările, operatorii și planurile. Folosiți codurile și valorile amount la cumpărare.

Alegeți o țară cu is_available=true și un operator cu is_sellable=true. plans conține prețuri după numărul de zile, de ex. plans["30"].

Cerere · curl

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

Răspuns · 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": "..."
}

Exemplul de răspuns este prescurtat. ID-urile, prețurile și datele de acces sunt ilustrative.

Cumpărare și prelungire

POST /api/v1/proxies/quote/ Calculați prețul

Calculați prețul cumpărării sau prelungirii înainte de plată. Nu se debitează bani.

Parametri JSON

Parametru	Tip	Obligatoriu	Ce să trimiteți
`plan_type`	`"time"`	La cumpărare	Tipul planului din catalog.
`amount`	`integer`	Da	Numărul de zile din catalog.
`country_code`	`string`	La cumpărare	Codul țării din countries[].code.
`operator_code`	`string`	La cumpărare	Codul unui operator disponibil din țara aleasă, din operators[].code.
`quantity`	`integer`	Nu	1–10. Implicit 1.
`max_total`	`string`	Nu	Total maxim în USD, de ex. "20.00". Un preț mai mare este refuzat fără debitare.
`proxy_id`	`integer`	La prelungire	Pentru calculul prelungirii, în locul parametrilor de cumpărare.

Pentru prelungire trimiteți doar proxy_id, amount și opțional max_total. Calculul nu rezervă prețul sau disponibilitatea.

Cerere · 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"
}'

Răspuns · 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": "..."
}

Exemplul de răspuns este prescurtat. ID-urile, prețurile și datele de acces sunt ilustrative.

POST /api/v1/proxies/buy/ Cumpărați proxy-uri

Cumpărați 1–10 proxy-uri din sold printr-o cerere. La eroare, întreaga cumpărare este anulată.

Parametri JSON

Parametru	Tip	Obligatoriu	Ce să trimiteți
`plan_type`	`"time"`	Da	Tipul planului din catalog.
`amount`	`integer`	Da	Numărul de zile din catalog.
`country_code`	`string`	Da	Codul țării din countries[].code.
`operator_code`	`string`	Da	Codul unui operator disponibil din țara aleasă, din operators[].code.
`quantity`	`integer`	Nu	1–10. Implicit 1.
`max_total`	`string`	Nu	Total maxim în USD, de ex. "20.00". Un preț mai mare este refuzat fără debitare.

Folosiți proxy_ids returnate în GET /proxies/?ids=… pentru conectare. HTTP 201: cumpărat; 200 cu replayed=true: rezultat anterior. Activarea poate dura puțin.

Antet Idempotency-Key obligatoriu: 8–128 litere, cifre sau . _ : -. Cheie nouă pentru fiecare operație nouă. După timeout repetați aceeași cerere și cheie pentru a evita o a doua debitare.

Cerere · 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"
}'

Răspuns · 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": "..."
}

Exemplul de răspuns este prescurtat. ID-urile, prețurile și datele de acces sunt ilustrative.

POST /api/v1/proxies/renew/ Prelungiți un proxy

Adăugați zile la proxy. Timpul rămas se păstrează; perioada expirată reîncepe la prelungire.

Parametri JSON

Parametru	Tip	Obligatoriu	Ce să trimiteți
`proxy_id`	`integer`	Da	ID-ul proxy-ului propriu din GET /proxies/.
`amount`	`integer`	Da	Numărul de zile din catalog.
`max_total`	`string`	Nu	Total maxim în USD, de ex. "20.00". Un preț mai mare este refuzat fără debitare.

Loginul, parola și portul rămân identice. Proxy-urile blocate sau arhivate nu pot fi prelungite. Succes: HTTP 200; replayed=true înseamnă fără debitare nouă.

Antet Idempotency-Key obligatoriu: 8–128 litere, cifre sau . _ : -. Cheie nouă pentru fiecare operație nouă. După timeout repetați aceeași cerere și cheie pentru a evita o a doua debitare.

Cerere · 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"
}'

Răspuns · 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": "..."
}

Exemplul de răspuns este prescurtat. ID-urile, prețurile și datele de acces sunt ilustrative.

Gestionarea proxy-urilor

GET /api/v1/proxies/ Proxy-uri și acces

Listați proxy-urile cu datele de acces, adresele de conectare și setările. Filtrați după ID, port sau stare.

Parametri query

Parametru	Tip	Obligatoriu	Ce să trimiteți
`ids`	`string`	Nu	1–100 ID-uri separate prin virgulă, de ex. 1702,1703.
`port`	`integer`	Nu	Portul proxy-ului: 1–65535.
`status`	`string`	Nu	all, active sau expired (inactive). Implicit all.
`limit`	`integer`	Nu	Dimensiunea paginii: 1–500. Implicit 100.
`offset`	`integer`	Nu	Numărul de rezultate de omis. Implicit 0.

Filtrele se aplică împreună. pagination.total numără rezultatele înainte de paginare. Proxy-urile arhivate sunt excluse. traffic_left în octeți; date în UTC.

Cerere · curl

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

Răspuns · 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": "..."
}

Exemplul de răspuns este prescurtat. ID-urile, prețurile și datele de acces sunt ilustrative.

POST /api/v1/proxies/settings/ Setări proxy

Modificați intervalul de rotație IP, reînnoirea automată, parola sau IP-urile permise. Se schimbă doar setările trimise.

Parametri JSON

Parametru	Tip	Obligatoriu	Ce să trimiteți
`proxy_id`	`integer`	Da	ID-ul proxy-ului propriu din GET /proxies/.
`auto_renew`	`boolean`	Nu	true activează, false dezactivează. Activare doar pentru proxy-uri plătite.
`ip_change_interval`	`integer`	Nu	Interval de rotație IP în minute: 0–1440. 0 dezactivează temporizatorul.
`password`	`string`	Nu	Parolă nouă: 12–64 caractere ASCII imprimabile, fără spații.
`ip_bindings`	`string[]`	Nu	Maximum 10 adrese IPv4 permise. [] elimină restricția IP.

Doar proxy-uri active. Trimiteți cel puțin o setare. La eroare nu se schimbă nimic; repetările identice sunt sigure. Aplicarea poate dura puțin.

Cerere · 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"
    ]
}'

Răspuns · 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": "..."
}

Exemplul de răspuns este prescurtat. ID-urile, prețurile și datele de acces sunt ilustrative.

POST /api/v1/proxies/set-location/ Schimbați locația

Schimbați țara și operatorul unui proxy activ folosind catalogul.

Parametri JSON

Parametru	Tip	Obligatoriu	Ce să trimiteți
`proxy_id`	`integer`	Da	ID-ul proxy-ului propriu din GET /proxies/.
`country_code`	`string`	Da	Codul țării din countries[].code.
`operator_code`	`string`	Da	Codul unui operator disponibil din țara aleasă, din operators[].code.

Țara se poate schimba la 10 minute, operatorul la 5 minute. Timpul plătit rămas se recalculează la prețul noii țări.

Cerere · 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"
}'

Răspuns · JSON

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

Exemplul de răspuns este prescurtat. ID-urile, prețurile și datele de acces sunt ilustrative.

POST /api/v1/proxies/set-operator/ Schimbați operatorul

Schimbați operatorul păstrând țara proxy-ului. Luați codul operatorului din catalog.

Parametri JSON

Parametru	Tip	Obligatoriu	Ce să trimiteți
`proxy_id`	`integer`	Da	ID-ul proxy-ului propriu din GET /proxies/.
`operator_code`	`string`	Da	Codul unui operator disponibil din țara aleasă, din operators[].code.

Schimbați operatorul la 5 minute. La limitare, data.retry_after indică secundele de așteptat.

Cerere · 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"
}'

Răspuns · JSON

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

Exemplul de răspuns este prescurtat. ID-urile, prețurile și datele de acces sunt ilustrative.

POST /api/v1/proxies/change-ip/ Schimbați IP-ul

Solicitați un nou IP de ieșire pentru un proxy activ. După rotație verificați adresa prin check-ip.

Parametri JSON

Parametru	Tip	Obligatoriu	Ce să trimiteți
`proxy_id`	`integer`	Da	ID-ul proxy-ului propriu din GET /proxies/.

Cerere · 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
}'

Răspuns · JSON

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

Exemplul de răspuns este prescurtat. ID-urile, prețurile și datele de acces sunt ilustrative.

POST /api/v1/proxies/check-ip/ Verificați IP-ul actual

Aflați IP-ul de ieșire actual al unui proxy activ. Verifică conexiunea fără a schimba IP-ul.

Parametri JSON

Parametru	Tip	Obligatoriu	Ce să trimiteți
`proxy_id`	`integer`	Da	ID-ul proxy-ului propriu din GET /proxies/.

Cerere · 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
}'

Răspuns · JSON

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

Exemplul de răspuns este prescurtat. ID-urile, prețurile și datele de acces sunt ilustrative.

Erori și reîncercări

La succes citiți data. La eroare citiți error și message. Păstrați request_id pentru asistență.

401: Verificați tokenul și antetul Authorization: Bearer <TOKEN>.
402: Sold insuficient. Alimentați contul; data.needed arată suma lipsă.
404: Proxy negăsit. Verificați proxy_id în lista proprie.
409: Verificați error: preț peste max_total, cheie folosită cu alți parametri sau acțiune indisponibilă pentru proxy.
429: Prea multe cereri. Dacă există Retry-After sau data.retry_after, așteptați secundele indicate; altfel măriți pauza dintre cereri.
500: Eroare temporară. Reîncercați mai târziu; cumpărarea și prelungirea doar cu același Idempotency-Key.

Exemplu de eroare

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