Dokumentacja API LocalSERP Proxy

Uwierzytelnianie

Każde żądanie poza publicznym katalogiem wymaga klucza API: Authorization: Bearer API_KEY. Klucz jest wyświetlany w całości tylko raz — podczas tworzenia. Przechowuj go jak hasło. Klucz możesz unieważnić w dowolnym momencie; żądania z jego użyciem będą wtedy zwracać 401 unauthorized.

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

Żądania i odpowiedzi

• JSON na wejściu, JSON na wyjściu: wysyłaj Content-Type: application/json z treścią żądania.
• Listy, które mogą się rozrastać, są stronicowane za pomocą page (od 1) i perPage (1–100, domyślnie 20) i zwracają { "data": [...], "pagination": { "page", "perPage", "total", "totalPages" } }. Krótkie listy zwracają { "data": [...] }.
• Identyfikatory to nieprzezroczyste ciągi znaków z prefiksem typu: ord_ (zamówienie), top_ (doładowanie), txn_ (operacja na saldzie), res_ (subskrypcja ruchu), mob_ (port mobilny), key_ (klucz API) i ipw_ (wpis na liście dozwolonych IP).
• Bezpieczne ponawianie żądań: POST /v1/orders i POST /v1/topups akceptują nagłówek Idempotency-Key (dowolny unikalny ciąg znaków, przechowywany przez 24 h). Ponowne wysłanie żądania z tym samym kluczem zwraca pierwszą odpowiedź, zamiast ponownie składać zamówienie lub doładowywać konto.
• Przykłady pokazują strukturę każdej odpowiedzi: podane w nich identyfikatory, adresy IP, kwoty i daty są przykładowe, a identyfikatory planów i ceny są rzeczywiste.

Błędy

Każdy błąd ma taką samą treść. code jest stałe i przeznaczone do obsługi w kodzie; message to zdanie po angielsku, które może się zmieniać. Błędy walidacji wymieniają każde nieprawidłowe pole w fields. Mogą pojawić się nowe kody: nieznane kody obsługuj jako ogólny błąd.

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

Limity zapytań

Każda odpowiedź zawiera RateLimit-Limit, RateLimit-Remaining i RateLimit-Reset. Po przekroczeniu limitu API zwraca 429 rate_limited z nagłówkiem Retry-After (w sekundach): odczekaj wskazany czas, a następnie ponów próbę. IP portu mobilnego można zmienić najwyżej raz na 30 sekund (429 rotation_too_soon, z Retry-After).