# Extraction API (mode liste blanche)

En mode liste blanche, une requête HTTP GET permet d'extraire en lot des proxys au format `IP:port`, utilisables en connexion directe, sans identifiants. La liste blanche elle-même est administrable par API, pour un processus entièrement programmable.

## Prérequis

1. Avoir acheté un forfait de Proxys Résidentiels dynamiques.
2. L'IP de sortie de votre serveur figure déjà en liste blanche (opération sur la page « Liste blanche » du tableau de bord, ou via l'API de gestion de la liste blanche ci-dessous).

## Interface d'extraction

```
GET https://api.eproxies.net/gateway_api/extract_ip
```

| Paramètre | Obligatoire | Valeurs possibles | Description |
| --- | --- | --- | --- |
| `count` | oui | nombre | quantité d'IP par extraction |
| `country` | non | code pays / `Global` | région, ex. `US` ; `Global` pour tous pays confondus |
| `protocol` | non | `http` / `socks5` | protocole du proxy |
| `format` | non | `txt` / `json` | format de retour |
| `session` | non | `sticky` / `random` | type d'IP : `sticky` persistant (réutilise le même lot d'IP) / `random` aléatoire |
| `separator` | non | `crlf` / `br` / `cr` / `lf` / `tab` | séparateur du format txt : `\r\n`, `</br>`, `\r`, `\n`, `\t` |
| `st` | non | chaîne personnalisée | séparateur personnalisé (remplace `separator`) |

Exemples :

```bash
# Extraire 10 proxys HTTP américains, au format JSON, IP persistantes
curl "https://api.eproxies.net/gateway_api/extract_ip?count=10&country=US&protocol=http&format=json&session=sticky"

# Extraire 5 proxys SOCKS5 de pays aléatoires, au format txt, un par ligne
curl "https://api.eproxies.net/gateway_api/extract_ip?count=5&protocol=socks5&format=txt&separator=lf&session=random"
```

Avec `format=json`, la réponse est un tableau d'objets contenant chacun les deux champs `ipAddress` et `portValue` :

```json
[
  { "ipAddress": "203.0.113.10", "portValue": 23333 },
  { "ipAddress": "203.0.113.11", "portValue": 23333 }
]
```

```python
import requests

resp = requests.get(
    "https://api.eproxies.net/gateway_api/extract_ip",
    params={"count": 10, "country": "US", "protocol": "http",
            "format": "json", "session": "sticky"},
    timeout=30,
)
proxy_list = resp.json()

# Les proxys extraits s'utilisent en connexion directe, sans identifiants
first = proxy_list[0]
endpoint = f"{first['ipAddress']}:{first['portValue']}"
proxies = {"http": f"http://{endpoint}", "https": f"http://{endpoint}"}
print(requests.get("https://ipinfo.io", proxies=proxies, timeout=30).json())
```

Liste des pays disponibles à l'extraction (retourne `country` code pays, `name` nom, `flag_url` icône de drapeau) :

```
GET https://api.eproxies.net/gateway_api/country-list
```

> La requête d'extraction doit impérativement provenir d'une IP inscrite en liste blanche, faute de quoi elle sera refusée. La page « Extraction API » du tableau de bord propose un générateur de lien visuel.

## API de gestion de la liste blanche

L'ajout, la suppression et la consultation de la liste blanche sont entièrement pilotables par API, ce qui facilite la maintenance automatique lorsque l'IP de sortie change. Les trois interfaces s'authentifient avec `userName` (nom d'utilisateur) + `userKeyValue` (clé utilisateur, à récupérer dans le tableau de bord) :

```bash
# Ajouter une IP à la liste blanche
curl "https://api.eproxies.net/gateway_api/add-ip?userName=USERNAME&userKeyValue=USER_KEY&ipAddress=203.0.113.10"

# Supprimer une IP de la liste blanche
curl "https://api.eproxies.net/gateway_api/del-ip?userName=USERNAME&userKeyValue=USER_KEY&ipAddress=203.0.113.10"

# Consulter la liste blanche actuelle
curl "https://api.eproxies.net/gateway_api/lists-ip?userName=USERNAME&userKeyValue=USER_KEY"
```

Flux d'automatisation typique (environnement à IP de sortie variable) :

```python
import requests

BASE = "https://api.eproxies.net/gateway_api"
AUTH = {"userName": "USERNAME", "userKeyValue": "USER_KEY"}

# 1. Obtenir l'IP de sortie actuelle de la machine
my_ip = requests.get("https://ipinfo.io/json", timeout=30).json()["ip"]

# 2. L'ajouter à la liste blanche
requests.get(f"{BASE}/add-ip", params={**AUTH, "ipAddress": my_ip}, timeout=30)

# 3. Extraire des proxys et les utiliser
proxies = requests.get(
    f"{BASE}/extract_ip",
    params={"count": 10, "country": "US", "protocol": "http",
            "format": "json", "session": "random"},
    timeout=30,
).json()
print(proxies)
```

## Mode identifiants ou mode extraction : lequel choisir

| | Mode identifiants | Extraction API (liste blanche) |
| --- | --- | --- |
| Granularité du ciblage | pays/état/ville/ASN | pays |
| Contrôle de session | contrôle fin par sid/ttl | `session=sticky/random`, par lot |
| Compatibilité | nécessite un logiciel gérant l'authentification proxy | tout logiciel acceptant un proxy |
| Scénarios recommandés | intégration dans du code, collecte fine | outils anciens, distribution en masse, environnements sans authentification |

## Spécification OpenAPI

Une définition lisible par machine de tous les endpoints de cette page est disponible sur [openapi.json](https://www.eproxies.io/docs/openapi.json) — importez-la dans Postman / Swagger UI, ou chargez-la depuis un agent IA.