Partner API

Démarrage rapide

Créez un jeton et envoyez-le dans le header Authorization. Pour POST, utilisez JSON et Content-Type: application/json.

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

Limite de requêtes300/min

Première requête · vérifier le jeton

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

Télécharger OpenAPI Toutes les méthodes à importer dans Postman.

Compte et catalogue

GET /api/v1/account/ Compte et limites

Vérifiez le jeton et obtenez l’ID, l’e-mail du compte et la limite de requêtes par minute.

Requête · curl

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

Réponse · 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": "..."
}

Exemple de réponse abrégé. ID, prix et identifiants sont illustratifs.

GET /api/v1/balance/ Solde en USD

Consultez votre solde en USD avant un achat ou un renouvellement.

Requête · curl

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

Réponse · JSON

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

Exemple de réponse abrégé. ID, prix et identifiants sont illustratifs.

GET /api/v1/catalog/ Pays et forfaits

Obtenez les pays, opérateurs et forfaits. Utilisez leurs codes et valeurs amount pour acheter.

Choisissez un pays avec is_available=true et un opérateur avec is_sellable=true. plans contient les prix par durée, ex. plans["30"].

Requête · curl

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

Réponse · 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": "..."
}

Exemple de réponse abrégé. ID, prix et identifiants sont illustratifs.

Achat et renouvellement

POST /api/v1/proxies/quote/ Calculer le prix

Calculez le prix d’un achat ou renouvellement avant de payer. Aucun débit.

Paramètres JSON

Paramètre	Type	Requis	Valeur à envoyer
`plan_type`	`"time"`	Pour acheter	Type de forfait du catalogue.
`amount`	`integer`	Oui	Nombre de jours du catalogue.
`country_code`	`string`	Pour acheter	Code pays dans countries[].code.
`operator_code`	`string`	Pour acheter	Code d’un opérateur disponible du pays choisi dans operators[].code.
`quantity`	`integer`	Non	1 à 10. Par défaut : 1.
`max_total`	`string`	Non	Total maximal en USD, ex. "20.00". Un prix supérieur est refusé sans débit.
`proxy_id`	`integer`	Pour renouveler	Pour calculer un renouvellement, à la place des paramètres d’achat.

Pour renouveler, envoyez uniquement proxy_id, amount et éventuellement max_total. Le calcul ne réserve ni prix ni disponibilité.

Requête · 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éponse · 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": "..."
}

Exemple de réponse abrégé. ID, prix et identifiants sont illustratifs.

POST /api/v1/proxies/buy/ Acheter des proxys

Achetez 1 à 10 proxys sur votre solde en une requête. En cas d’échec, tout l’achat est annulé.

Paramètres JSON

Paramètre	Type	Requis	Valeur à envoyer
`plan_type`	`"time"`	Oui	Type de forfait du catalogue.
`amount`	`integer`	Oui	Nombre de jours du catalogue.
`country_code`	`string`	Oui	Code pays dans countries[].code.
`operator_code`	`string`	Oui	Code d’un opérateur disponible du pays choisi dans operators[].code.
`quantity`	`integer`	Non	1 à 10. Par défaut : 1.
`max_total`	`string`	Non	Total maximal en USD, ex. "20.00". Un prix supérieur est refusé sans débit.

Utilisez les proxy_ids reçus dans GET /proxies/?ids=… pour les identifiants. HTTP 201 : achat ; 200 avec replayed=true : résultat précédent. L’activation peut prendre un court délai.

Header Idempotency-Key requis : 8–128 lettres, chiffres ou . _ : -. Nouvelle opération, nouvelle clé. Après un timeout, répétez la même requête et la même clé pour éviter un second débit.

Requête · 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éponse · 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": "..."
}

Exemple de réponse abrégé. ID, prix et identifiants sont illustratifs.

POST /api/v1/proxies/renew/ Renouveler un proxy

Ajoutez des jours à votre proxy. Le temps restant est conservé ; une durée expirée repart au renouvellement.

Paramètres JSON

Paramètre	Type	Requis	Valeur à envoyer
`proxy_id`	`integer`	Oui	ID de votre proxy dans GET /proxies/.
`amount`	`integer`	Oui	Nombre de jours du catalogue.
`max_total`	`string`	Non	Total maximal en USD, ex. "20.00". Un prix supérieur est refusé sans débit.

Login, mot de passe et port restent identiques. Proxys bloqués ou archivés non renouvelables. Succès : HTTP 200 ; replayed=true indique l’absence de nouveau débit.

Requête · 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éponse · 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": "..."
}

Exemple de réponse abrégé. ID, prix et identifiants sont illustratifs.

Gestion des proxys

GET /api/v1/proxies/ Proxys et identifiants

Listez les proxys avec identifiants, URL de connexion et paramètres. Filtrez par ID, port ou état.

Paramètres query

Paramètre	Type	Requis	Valeur à envoyer
`ids`	`string`	Non	1 à 100 ID séparés par des virgules, ex. 1702,1703.
`port`	`integer`	Non	Port du proxy : 1–65535.
`status`	`string`	Non	all, active ou expired (inactifs). Par défaut : all.
`limit`	`integer`	Non	Taille de page : 1 à 500. Par défaut : 100.
`offset`	`integer`	Non	Nombre de résultats à ignorer. Par défaut : 0.

Les filtres se combinent. pagination.total compte les résultats avant pagination. Proxys archivés exclus. traffic_left en octets ; dates en UTC.

Requête · curl

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

Réponse · 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": "..."
}

Exemple de réponse abrégé. ID, prix et identifiants sont illustratifs.

POST /api/v1/proxies/settings/ Paramètres du proxy

Modifiez la rotation IP, le renouvellement automatique, le mot de passe ou les IP autorisées. Seuls les paramètres fournis changent.

Paramètres JSON

Paramètre	Type	Requis	Valeur à envoyer
`proxy_id`	`integer`	Oui	ID de votre proxy dans GET /proxies/.
`auto_renew`	`boolean`	Non	true active, false désactive. Activation uniquement pour les proxys payants.
`ip_change_interval`	`integer`	Non	Intervalle de rotation IP en minutes : 0–1440. 0 désactive le minuteur.
`password`	`string`	Non	Nouveau mot de passe : 12–64 caractères ASCII imprimables, sans espaces.
`ip_bindings`	`string[]`	Non	Jusqu’à 10 adresses IPv4 autorisées. [] supprime la restriction IP.

Proxys actifs uniquement. Envoyez au moins un paramètre. Une erreur laisse tout inchangé ; répétitions identiques sûres. L’application peut prendre un court délai.

Requête · 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éponse · 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": "..."
}

Exemple de réponse abrégé. ID, prix et identifiants sont illustratifs.

POST /api/v1/proxies/set-location/ Changer de localisation

Changez le pays et l’opérateur d’un proxy actif à partir du catalogue.

Paramètres JSON

Paramètre	Type	Requis	Valeur à envoyer
`proxy_id`	`integer`	Oui	ID de votre proxy dans GET /proxies/.
`country_code`	`string`	Oui	Code pays dans countries[].code.
`operator_code`	`string`	Oui	Code d’un opérateur disponible du pays choisi dans operators[].code.

Pays : toutes les 10 minutes ; opérateur : toutes les 5 minutes. Un changement de pays recalcule la durée payée restante au nouveau tarif.

Requête · 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éponse · JSON

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

Exemple de réponse abrégé. ID, prix et identifiants sont illustratifs.

POST /api/v1/proxies/set-operator/ Changer d’opérateur

Changez d’opérateur en conservant le pays du proxy. Prenez le code dans le catalogue.

Paramètres JSON

Paramètre	Type	Requis	Valeur à envoyer
`proxy_id`	`integer`	Oui	ID de votre proxy dans GET /proxies/.
`operator_code`	`string`	Oui	Code d’un opérateur disponible du pays choisi dans operators[].code.

Changement d’opérateur toutes les 5 minutes. En cas de délai, data.retry_after indique les secondes à attendre.

Requête · 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éponse · JSON

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

Exemple de réponse abrégé. ID, prix et identifiants sont illustratifs.

POST /api/v1/proxies/change-ip/ Changer d’IP

Demandez une nouvelle IP de sortie pour un proxy actif. Vérifiez ensuite l’adresse avec check-ip.

Paramètres JSON

Paramètre	Type	Requis	Valeur à envoyer
`proxy_id`	`integer`	Oui	ID de votre proxy dans GET /proxies/.

Requête · 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éponse · JSON

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

Exemple de réponse abrégé. ID, prix et identifiants sont illustratifs.

POST /api/v1/proxies/check-ip/ Vérifier l’IP actuelle

Obtenez l’IP de sortie actuelle d’un proxy actif. Vérifie la connexion sans changer l’IP.

Paramètres JSON

Paramètre	Type	Requis	Valeur à envoyer
`proxy_id`	`integer`	Oui	ID de votre proxy dans GET /proxies/.

Requête · 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éponse · JSON

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

Exemple de réponse abrégé. ID, prix et identifiants sont illustratifs.

Erreurs et nouvelles tentatives

En cas de succès, lisez data. Sinon, lisez error et message. Gardez request_id pour le support.

401: Vérifiez le jeton et le header Authorization: Bearer <TOKEN>.
402: Solde insuffisant. Rechargez ; data.needed indique le montant manquant.
404: Proxy introuvable. Vérifiez proxy_id dans votre liste.
409: Vérifiez error : prix supérieur à max_total, clé utilisée avec d’autres paramètres ou action indisponible pour ce proxy.
429: Trop de requêtes. Si Retry-After ou data.retry_after est présent, attendez ce nombre de secondes ; sinon espacez davantage les requêtes.
500: Erreur temporaire. Réessayez plus tard ; pour achat et renouvellement, gardez le même Idempotency-Key.

Exemple d’erreur

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