LocalSERP Proxy API-documentatie

Authenticatie

Elke aanvraag, behalve de openbare catalogus, bevat een API-sleutel: Authorization: Bearer API_KEY. Een sleutel wordt eenmalig volledig weergegeven wanneer je deze aanmaakt: bewaar hem als een wachtwoord. Je kunt een sleutel op elk moment intrekken; aanvragen ermee geven daarna 401 unauthorized terug.

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

Verzoeken en antwoorden

• JSON erin, JSON eruit: stuur Content-Type: application/json met een body.
• Lijsten die kunnen groeien, zijn gepagineerd met page (vanaf 1) en perPage (1–100, standaard 20) en geven { "data": [...], "pagination": { "page", "perPage", "total", "totalPages" } } terug. Korte lijsten geven { "data": [...] } terug.
• ID's zijn ondoorzichtige strings met een typeprefix: ord_ (bestelling), top_ (opwaardering), txn_ (saldo-mutatie), res_ (verkeersabonnement), mob_ (mobiele poort), key_ (API-sleutel) en ipw_ (IP-allowlistvermelding).
• Veilig opnieuw proberen: POST /v1/orders en POST /v1/topups accepteren een Idempotency-Key-header (een willekeurige unieke string, 24 uur bewaard). Bij herhaling met dezelfde sleutel wordt het eerste antwoord teruggegeven, zodat je niet twee keer iets koopt of opwaardeert.
• Voorbeelden tonen de structuur van elk antwoord: de ID's, IP's, bedragen en datums zijn ter illustratie; de plan-ID's en prijzen zijn echt.

Fouten

Elke fout heeft dezelfde body. code is stabiel en bedoeld voor je code; message is een Engelse zin die kan veranderen. Validatiefouten vermelden elk ongeldig veld in fields. Er kunnen nieuwe codes worden toegevoegd: behandel onbekende codes als een algemene fout.

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

Limieten voor aanvragen

Elke reactie bevat RateLimit-Limit, RateLimit-Remaining en RateLimit-Reset. Bij overschrijding van de limiet antwoordt de API met 429 rate_limited en een Retry-After-header (seconden): wacht die tijd en probeer het opnieuw. Het IP-adres van een mobiele poort kan maximaal eens per 30 seconden worden gewijzigd (429 rotation_too_soon, met Retry-After).