Partner API

Schnellstart

Token erstellen und im Authorization-Header senden. Für POST JSON und Content-Type: application/json verwenden.

API-Adressehttps://proxycola.com/api/v1/

Anfragelimit300/min

Erste Anfrage · Token prüfen

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

OpenAPI herunterladen Alle Methoden zum Import in Postman.

Konto & Katalog

GET /api/v1/account/ Konto & Limits

Token prüfen und Konto-ID, E-Mail sowie Anfragenlimit pro Minute abrufen.

Anfrage · curl

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

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

Gekürztes Antwortbeispiel. IDs, Preise und Zugangsdaten dienen als Beispiele.

GET /api/v1/balance/ Guthaben in USD

USD-Guthaben vor Kauf oder Verlängerung prüfen.

Anfrage · curl

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

Antwort · JSON

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

Gekürztes Antwortbeispiel. IDs, Preise und Zugangsdaten dienen als Beispiele.

GET /api/v1/catalog/ Länder & Tarife

Länder, Anbieter und Tarife abrufen. Deren Codes und amount-Werte beim Kauf verwenden.

Land mit is_available=true und Anbieter mit is_sellable=true wählen. plans enthält Preise nach Tagen, z. B. plans["30"].

Anfrage · curl

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

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

Gekürztes Antwortbeispiel. IDs, Preise und Zugangsdaten dienen als Beispiele.

Kaufen & verlängern

POST /api/v1/proxies/quote/ Preis berechnen

Kauf- oder Verlängerungspreis vor der Zahlung berechnen. Keine Abbuchung.

Parameter JSON

Parameter	Typ	Pflicht	Wert
`plan_type`	`"time"`	Beim Kauf	Tariftyp aus dem Katalog.
`amount`	`integer`	Ja	Anzahl Tage aus dem Katalog.
`country_code`	`string`	Beim Kauf	Ländercode aus countries[].code.
`operator_code`	`string`	Beim Kauf	Verfügbarer Anbietercode des gewählten Landes aus operators[].code.
`quantity`	`integer`	Nein	1–10. Standard: 1.
`max_total`	`string`	Nein	Maximalbetrag in USD, z. B. "20.00". Höhere Preise werden ohne Abbuchung abgelehnt.
`proxy_id`	`integer`	Bei Verlängerung	Für Verlängerungsangebote statt Kaufparametern.

Für Verlängerung nur proxy_id, amount und optional max_total senden. Ein Angebot reserviert weder Preis noch Verfügbarkeit.

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

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

Gekürztes Antwortbeispiel. IDs, Preise und Zugangsdaten dienen als Beispiele.

POST /api/v1/proxies/buy/ Proxys kaufen

1–10 Proxys mit einer Anfrage vom Guthaben kaufen. Bei einem Fehler wird der gesamte Kauf abgebrochen.

Parameter JSON

Parameter	Typ	Pflicht	Wert
`plan_type`	`"time"`	Ja	Tariftyp aus dem Katalog.
`amount`	`integer`	Ja	Anzahl Tage aus dem Katalog.
`country_code`	`string`	Ja	Ländercode aus countries[].code.
`operator_code`	`string`	Ja	Verfügbarer Anbietercode des gewählten Landes aus operators[].code.
`quantity`	`integer`	Nein	1–10. Standard: 1.
`max_total`	`string`	Nein	Maximalbetrag in USD, z. B. "20.00". Höhere Preise werden ohne Abbuchung abgelehnt.

Erhaltene proxy_ids in GET /proxies/?ids=… für Zugangsdaten nutzen. HTTP 201: gekauft; 200 mit replayed=true: früheres Ergebnis. Aktivierung kann kurz dauern.

Idempotency-Key erforderlich: 8–128 Buchstaben, Ziffern oder . _ : -. Neuer Schlüssel pro neuer Operation. Nach Timeout dieselbe Anfrage mit demselben Schlüssel wiederholen, um eine zweite Abbuchung zu vermeiden.

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

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

Gekürztes Antwortbeispiel. IDs, Preise und Zugangsdaten dienen als Beispiele.

POST /api/v1/proxies/renew/ Proxy verlängern

Tage hinzufügen. Restlaufzeit bleibt erhalten; abgelaufene Laufzeit beginnt mit der Verlängerung.

Parameter JSON

Parameter	Typ	Pflicht	Wert
`proxy_id`	`integer`	Ja	Eigene Proxy-ID aus GET /proxies/.
`amount`	`integer`	Ja	Anzahl Tage aus dem Katalog.
`max_total`	`string`	Nein	Maximalbetrag in USD, z. B. "20.00". Höhere Preise werden ohne Abbuchung abgelehnt.

Login, Passwort und Port bleiben gleich. Gesperrte oder archivierte Proxys sind nicht verlängerbar. Erfolg: HTTP 200; replayed=true bedeutet keine neue Abbuchung.

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

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

Gekürztes Antwortbeispiel. IDs, Preise und Zugangsdaten dienen als Beispiele.

Proxys verwalten

GET /api/v1/proxies/ Proxys & Zugangsdaten

Proxys mit Zugangsdaten, Verbindungs-URLs und Einstellungen abrufen. Nach ID, Port oder Status filtern.

Parameter query

Parameter	Typ	Pflicht	Wert
`ids`	`string`	Nein	1–100 IDs, durch Kommas getrennt, z. B. 1702,1703.
`port`	`integer`	Nein	Proxy-Port: 1–65535.
`status`	`string`	Nein	all, active oder expired (inaktiv). Standard: all.
`limit`	`integer`	Nein	Seitengröße: 1–500. Standard: 100.
`offset`	`integer`	Nein	Anzahl zu überspringender Ergebnisse. Standard: 0.

Filter gelten gemeinsam. pagination.total zählt Treffer vor der Seiteneinteilung. Archivierte Proxys sind ausgeschlossen. traffic_left in Bytes; Datum in UTC.

Anfrage · curl

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

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

Gekürztes Antwortbeispiel. IDs, Preise und Zugangsdaten dienen als Beispiele.

POST /api/v1/proxies/settings/ Proxy-Einstellungen

IP-Wechselintervall, automatische Verlängerung, Passwort oder erlaubte IPs ändern. Nur übergebene Einstellungen ändern sich.

Parameter JSON

Parameter	Typ	Pflicht	Wert
`proxy_id`	`integer`	Ja	Eigene Proxy-ID aus GET /proxies/.
`auto_renew`	`boolean`	Nein	true aktiviert, false deaktiviert. Aktivierung nur für bezahlte Proxys.
`ip_change_interval`	`integer`	Nein	IP-Wechselintervall in Minuten: 0–1440. 0 deaktiviert den Timer.
`password`	`string`	Nein	Neues Passwort: 12–64 druckbare ASCII-Zeichen ohne Leerzeichen.
`ip_bindings`	`string[]`	Nein	Bis zu 10 erlaubte IPv4-Adressen. [] entfernt die IP-Beschränkung.

Nur aktive Proxys. Mindestens eine Einstellung senden. Bei Fehlern bleibt alles unverändert; identische Wiederholungen sind sicher. Änderungen können kurz verzögert sein.

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

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

Gekürztes Antwortbeispiel. IDs, Preise und Zugangsdaten dienen als Beispiele.

POST /api/v1/proxies/set-location/ Standort ändern

Aktiven Proxy auf ein anderes Land und einen Anbieter aus dem Katalog umstellen.

Parameter JSON

Parameter	Typ	Pflicht	Wert
`proxy_id`	`integer`	Ja	Eigene Proxy-ID aus GET /proxies/.
`country_code`	`string`	Ja	Ländercode aus countries[].code.
`operator_code`	`string`	Ja	Verfügbarer Anbietercode des gewählten Landes aus operators[].code.

Landwechsel alle 10 Minuten, Anbieterwechsel alle 5 Minuten. Verbleibende bezahlte Laufzeit wird beim Landwechsel zum neuen Preis umgerechnet.

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

Antwort · JSON

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

Gekürztes Antwortbeispiel. IDs, Preise und Zugangsdaten dienen als Beispiele.

POST /api/v1/proxies/set-operator/ Anbieter wechseln

Anbieter wechseln, ohne das Land zu ändern. Anbietercode aus dem Katalog verwenden.

Parameter JSON

Parameter	Typ	Pflicht	Wert
`proxy_id`	`integer`	Ja	Eigene Proxy-ID aus GET /proxies/.
`operator_code`	`string`	Ja	Verfügbarer Anbietercode des gewählten Landes aus operators[].code.

Anbieterwechsel alle 5 Minuten. Bei Wartezeit enthält data.retry_after die Sekunden bis zum nächsten Versuch.

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

Antwort · JSON

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

Gekürztes Antwortbeispiel. IDs, Preise und Zugangsdaten dienen als Beispiele.

POST /api/v1/proxies/change-ip/ IP wechseln

Neue Ausgangs-IP für einen aktiven Proxy anfordern. Danach die Adresse mit check-ip prüfen.

Parameter JSON

Parameter	Typ	Pflicht	Wert
`proxy_id`	`integer`	Ja	Eigene Proxy-ID aus GET /proxies/.

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

Antwort · JSON

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

Gekürztes Antwortbeispiel. IDs, Preise und Zugangsdaten dienen als Beispiele.

POST /api/v1/proxies/check-ip/ Aktuelle IP prüfen

Aktuelle Ausgangs-IP eines aktiven Proxys abrufen. Prüft die Verbindung, ohne die IP zu ändern.

Parameter JSON

Parameter	Typ	Pflicht	Wert
`proxy_id`	`integer`	Ja	Eigene Proxy-ID aus GET /proxies/.

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

Antwort · JSON

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

Gekürztes Antwortbeispiel. IDs, Preise und Zugangsdaten dienen als Beispiele.

Fehler & Wiederholungen

Bei Erfolg data lesen, bei Fehlern error und message. request_id für Supportanfragen aufbewahren.

401: Token und Header Authorization: Bearer <TOKEN> prüfen.
402: Guthaben reicht nicht. Aufladen; data.needed zeigt den fehlenden Betrag.
404: Proxy nicht gefunden. proxy_id in der eigenen Liste prüfen.
409: error prüfen: Preis über max_total, Schlüssel mit anderen Parametern verwendet oder Aktion für diesen Proxy nicht verfügbar.
429: Zu viele Anfragen. Falls Retry-After oder data.retry_after vorhanden ist, diese Sekunden warten; sonst den Abstand zwischen Anfragen erhöhen.
500: Vorübergehender Fehler. Später wiederholen; Kauf und Verlängerung nur mit demselben Idempotency-Key.

Fehlerbeispiel

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