# Documentation de l’API LocalSERP Proxy

> API REST de LocalSERP Proxy sur localserpproxy.com/api : clés API, erreurs, limites et endpoints pour le solde, les recharges, les commandes et les proxys.

- URL: https://localserpproxy.com/fr/docs/api/
- Dernière mise à jour: 2026-10-15
- Publisher: LocalSERP Proxy (https://localserpproxy.com)

Vous pouvez automatiser toutes les opérations de votre compte : consulter le solde, payer en crypto, acheter une offre, créer des identifiants proxy et changer d’IP mobile. JSON sur HTTPS, une seule clé API, exemples avec curl, Python et Node.js.

## Comment utiliser l’API LocalSERP Proxy ?

**Réponse rapide**

Envoyez des requêtes HTTPS à `https://localserpproxy.com/api/v1` avec votre clé API dans l’en-tête `Authorization: Bearer API_KEY`. Créez la clé sur la [page développeur](https://localserpproxy.com/app/developer?lang=fr) de votre compte (ou avec `POST /v1/api-keys`) et attribuez-lui uniquement les autorisations nécessaires. Les requêtes et les réponses sont au format JSON ; les erreurs sont toujours renvoyées sous la forme `{ "error": { "code", "message" } }`.

## En bref

| Attribut | Valeur |
| --- | --- |
| URL de base | `https://localserpproxy.com/api/v1` |
| Format | JSON sur HTTPS, UTF-8 |
| Authentification | Clé API : `Authorization: Bearer API_KEY` |
| Autorisations de la clé API | `read`, `proxies`, `billing` |
| Montants | USD sous forme de chaîne avec 2 décimales (`"29.00"`) |
| Montants en crypto | Chaînes décimales, jamais de nombres à virgule flottante (`"0.00045210"`) |
| Trafic | Octets (1 GB = 1 000 000 000 octets) |
| Dates | ISO 8601 en UTC (`2026-10-05T14:03:11Z`) |
| Version | `/v1` dans chaque chemin |

## Authentification

Chaque requête, à l’exception du catalogue public, nécessite une clé API : `Authorization: Bearer API_KEY`. Une clé est affichée en entier **une seule fois**, lors de sa création : conservez-la comme un mot de passe. Vous pouvez révoquer une clé à tout moment ; les requêtes effectuées avec celle-ci renverront alors `401 unauthorized`.

### Autorisations

N’accordez à chaque clé que les autorisations nécessaires à votre script. Une clé sans l’autorisation requise renvoie `403 forbidden`.

| Autorisation | Ce qu’elle permet |
| --- | --- |
| `read` | tout consulter (compte, solde, services, utilisation). |
| `proxies` | modifier les paramètres et identifiants du proxy (libellés, renouvellement automatique, nouveaux mots de passe), gérer les sous-utilisateurs, gérer la liste d’autorisation IP et faire tourner les ports mobiles (lien de rotation inclus). |
| `billing` | créer des commandes et des recharges, payer avec le solde. |

La seule exception est le **lien de rotation mobile**, conçu pour être appelé depuis un favori de navigateur ou un simple `curl` : `GET https://localserpproxy.com/api/v1/mobile/PORT_ID/rotate?key=API_KEY` (clé avec la portée `proxies`). Voir [Ports mobiles et rotation d’IP](https://localserpproxy.com/fr/docs/api/mobile/).

*Consulter votre solde*

```bash
curl -s "https://localserpproxy.com/api/v1/balance" \
  -H "Authorization: Bearer $API_KEY"
```

## Requêtes et réponses

- **JSON en entrée, JSON en sortie** : envoyez `Content-Type: application/json` avec un corps.
- Les **listes** susceptibles de s’allonger sont paginées avec `page` (à partir de 1) et `perPage` (1–100, 20 par défaut) et renvoient `{ "data": [...], "pagination": { "page", "perPage", "total", "totalPages" } }`. Les listes courtes renvoient `{ "data": [...] }`.
- Les **identifiants** sont des chaînes opaques avec un préfixe de type : `ord_` (commande), `top_` (recharge), `txn_` (mouvement de solde), `res_` (abonnement de trafic), `mob_` (port mobile), `key_` (clé API) et `ipw_` (entrée de la liste d’autorisation IP).
- **Relances sans risque** : `POST /v1/orders` et `POST /v1/topups` acceptent un en-tête `Idempotency-Key` (n’importe quelle chaîne unique, conservée 24 h). Réutiliser la même clé renvoie la première réponse au lieu de créer un double achat ou une double recharge.
- Les **exemples** illustrent la structure de chaque réponse : les identifiants, IP, montants et dates sont donnés à titre d’exemple ; les identifiants de forfait et les prix sont réels.

## Erreurs

Toutes les erreurs ont le même corps. `code` est stable et destiné à votre code ; `message` est une phrase en anglais susceptible de changer. Les erreurs de validation indiquent chaque champ invalide dans `fields`. De nouveaux codes peuvent être ajoutés : traitez les codes inconnus comme des échecs génériques.

*422 validation_failed*

```json
{
  "error": {
    "code": "validation_failed",
    "message": "Some fields are invalid.",
    "fields": [
      {
        "field": "amountUsd",
        "code": "too_small",
        "message": "The minimum top-up is 25.00 USD."
      }
    ],
    "requestId": "req_2b7c0f"
  }
}
```

### Codes d’état

| État | Signification |
| --- | --- |
| `422` | `validation_failed` : un ou plusieurs champs sont invalides. |
| `401` | `unauthorized` : jeton manquant, invalide ou expiré. |
| `402` | `insufficient_balance` : le solde ne couvre pas la commande. `details` = `InsufficientBalanceDetails`. |
| `403` | `forbidden` : la clé API ne dispose pas de l’autorisation requise, ou le compte est suspendu. |
| `404` | `not_found` : la ressource n’existe pas ou appartient à un autre compte. |
| `409` | `conflict` (ou un code plus précis) : l’action n’est pas possible dans l’état actuel. |
| `429` | `rate_limited` ou `rotation_too_soon`. |

## Limites de débit

Chaque réponse contient `RateLimit-Limit`, `RateLimit-Remaining` et `RateLimit-Reset`. Au-delà de la limite, l’API répond `429 rate_limited` avec un en-tête `Retry-After` (en secondes) : attendez cette durée, puis réessayez. L’IP d’un port mobile peut être changée au maximum une fois toutes les 30 secondes (`429 rotation_too_soon`, avec `Retry-After`).

## Référence API

- **[Compte et solde](https://localserpproxy.com/fr/docs/api/account/)** — Consultez les paramètres de votre compte, votre solde prépayé en USD et chaque mouvement de ce solde (rechargements, achats, remboursements).
- **[Rechargements en crypto](https://localserpproxy.com/fr/docs/api/top-ups/)** — Rechargez votre solde en crypto : obtenez l’adresse de dépôt et le montant exact, envoyez exactement ce montant, indiquez que le paiement a été envoyé (l’ID de transaction est facultatif), puis suivez le rechargement jusqu’à ce que le solde soit crédité. Le solde permet de payer n’importe lequel de nos forfaits.
- **[Commandes](https://localserpproxy.com/fr/docs/api/orders/)** — Consultez les forfaits et leurs prix, achetez un forfait avec votre solde (nouveau service, trafic supplémentaire ou prolongation d’un port) et consultez vos commandes passées.
- **[Proxys résidentiels et identifiants](https://localserpproxy.com/fr/docs/api/residential/)** — Gérez vos abonnements de trafic (résidentiel et 4G/5G rotatif au GB) : identifiants de proxy, sous-utilisateurs avec leurs propres identifiants et limite de trafic, consommation quotidienne et emplacements que vous pouvez cibler dans le nom d’utilisateur du proxy.
- **[Ports mobiles et rotation d’IP](https://localserpproxy.com/fr/docs/api/mobile/)** — Ports 4G/5G dédiés : changez d’IP maintenant ou selon une minuterie, utilisez le lien de rotation et consultez le trafic quotidien.
- **[Clés API et liste d’autorisation IP](https://localserpproxy.com/fr/docs/api/api-keys/)** — Créez et révoquez des clés API avec des autorisations limitées, et gérez la liste d’autorisation IP : jusqu’à 10 IP sources peuvent utiliser les proxys sans nom d’utilisateur ni mot de passe.

> **Payer depuis un script** Les forfaits sont toujours payés à partir du solde prépayé en USD. Rechargez en crypto (minimum 25.00 USD) avec POST /v1/topups, puis achetez avec POST /v1/orders. Les deux opérations peuvent être effectuées en un seul appel : une recharge peut inclure la commande dans purchase, et le forfait est acheté dès que la recharge est créditée.

---

LocalSERP Proxy: LocalSERP Proxy est un service de proxy résidentiel aux États-Unis pour vérifier les résultats de recherche locaux, les annonces et les prix ville par ville, avec paiement en crypto et sans envoi de pièce d’identité.