Documentation de l’API LocalSERP Proxy

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.

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.

{
  "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"
  }
}

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).