# Dokumentacja API LocalSERP Proxy

> REST API LocalSERP Proxy pod adresem localserpproxy.com/api: klucze API, błędy, limity i endpointy dotyczące salda, doładowań, zamówień i proxy.

- URL: https://localserpproxy.com/pl/docs/api/
- Ostatnia aktualizacja: 2026-10-15
- Publisher: LocalSERP Proxy (https://localserpproxy.com)

Wszystko, co robisz na koncie, możesz obsługiwać za pomocą skryptów: sprawdzać saldo, doładowywać konto kryptowalutą, kupować plan, tworzyć dane dostępowe do proxy i zmieniać mobilne IP. JSON przez HTTPS, jeden klucz API, przykłady w curl, Python i Node.js.

## Jak korzystać z API LocalSERP Proxy?

**Szybka odpowiedź**

Wysyłaj żądania HTTPS do `https://localserpproxy.com/api/v1`, umieszczając klucz API w nagłówku `Authorization: Bearer API_KEY`. Utwórz klucz na [stronie dla deweloperów](https://localserpproxy.com/app/developer?lang=pl) na swoim koncie (lub za pomocą `POST /v1/api-keys`) i przyznaj mu tylko niezbędne uprawnienia. Żądania i odpowiedzi są w formacie JSON; błędy są zawsze zwracane jako `{ "error": { "code", "message" } }`.

## W skrócie

| Atrybut | Wartość |
| --- | --- |
| Podstawowy URL | `https://localserpproxy.com/api/v1` |
| Format | JSON przez HTTPS, UTF-8 |
| Uwierzytelnianie | Klucz API: `Authorization: Bearer API_KEY` |
| Zakresy uprawnień klucza API | `read`, `proxies`, `billing` |
| Waluta | USD jako ciąg znaków z 2 miejscami po przecinku (`"29.00"`) |
| Kwoty w kryptowalutach | Ciągi dziesiętne, nigdy liczby zmiennoprzecinkowe (`"0.00045210"`) |
| Transfer danych | Bajty (1 GB = 1 000 000 000 bajtów) |
| Daty | ISO 8601 w UTC (`2026-10-05T14:03:11Z`) |
| Wersja | `/v1` w każdej ścieżce |

## 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`.

### Zakresy

Przyznawaj każdemu kluczowi tylko uprawnienia potrzebne skryptowi. Klucz bez wymaganego zakresu zwraca `403 forbidden`.

| Zakres | Do czego uprawnia |
| --- | --- |
| `read` | odczyt wszystkich danych (konto, saldo, usługi, wykorzystanie). |
| `proxies` | zmieniaj ustawienia i dane logowania proxy (etykiety, automatyczne odnawianie, nowe hasła), zarządzaj subużytkownikami i listą dozwolonych IP oraz rotuj porty mobilne (w tym link do rotacji). |
| `billing` | składaj zamówienia i doładowuj konto, płacąc z salda. |

Jedyny wyjątek to **link do rotacji mobilnej**, przeznaczony do wywoływania z zakładki w przeglądarce lub zwykłego `curl`: `GET https://localserpproxy.com/api/v1/mobile/PORT_ID/rotate?key=API_KEY` (klucz z zakresem `proxies`). Zobacz [Porty mobilne i rotacja IP](https://localserpproxy.com/pl/docs/api/mobile/).

*Sprawdź saldo*

```bash
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.

*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"
  }
}
```

### Kody statusu

| Status | Znaczenie |
| --- | --- |
| `422` | `validation_failed`: co najmniej jedno pole jest nieprawidłowe. |
| `401` | `unauthorized`: brakuje tokena, jest nieprawidłowy lub wygasł. |
| `402` | `insufficient_balance`: saldo nie wystarcza na opłacenie zamówienia. `details` = `InsufficientBalanceDetails`. |
| `403` | `forbidden`: klucz API nie ma wymaganego zakresu uprawnień lub konto jest zawieszone. |
| `404` | `not_found`: zasób nie istnieje lub należy do innego konta. |
| `409` | `conflict` (lub bardziej szczegółowy kod): nie można wykonać tej czynności w obecnym stanie. |
| `429` | `rate_limited` lub `rotation_too_soon`. |

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

## Dokumentacja API

- **[Konto i saldo](https://localserpproxy.com/pl/docs/api/account/)** — Sprawdź ustawienia konta, przedpłacone saldo w USD i każdą zmianę salda (doładowania, zakupy, zwroty).
- **[Doładowania kryptowalutami](https://localserpproxy.com/pl/docs/api/top-ups/)** — Doładuj saldo kryptowalutą: pobierz adres wpłaty i dokładną kwotę, wyślij dokładnie tę kwotę, zgłoś wysłanie płatności (identyfikator transakcji jest opcjonalny), a następnie śledź doładowanie do momentu zaksięgowania środków. Saldo służy do opłacania dowolnego z naszych planów.
- **[Zamówienia](https://localserpproxy.com/pl/docs/api/orders/)** — Wyświetl plany i ich ceny, kup plan z salda (nową usługę, większy pakiet transferu lub przedłużenie portu) i sprawdź wcześniejsze zamówienia.
- **[Proxy rezydencjalne i dane dostępowe](https://localserpproxy.com/pl/docs/api/residential/)** — Zarządzaj subskrypcjami transferu (proxy rezydencjalne oraz rotacyjne mobilne proxy 4G/5G rozliczane za GB): danymi dostępowymi do proxy, subużytkownikami z własnymi danymi dostępowymi i limitem transferu, dziennym zużyciem oraz lokalizacjami, które możesz wskazać w nazwie użytkownika proxy.
- **[Porty mobilne i rotacja IP](https://localserpproxy.com/pl/docs/api/mobile/)** — Dedykowane porty 4G/5G: zmień IP teraz lub ustaw zmianę na później, użyj linku rotacji i sprawdź dzienny transfer.
- **[Klucze API i lista dozwolonych IP](https://localserpproxy.com/pl/docs/api/api-keys/)** — Twórz i unieważniaj klucze API z ograniczonymi uprawnieniami oraz zarządzaj listą dozwolonych IP: maksymalnie 10 źródłowych adresów IP może korzystać z proxy bez nazwy użytkownika i hasła.

> **Płatność ze skryptu** Plany są zawsze opłacane z przedpłaconego salda w USD. Doładuj saldo kryptowalutą (minimum 25.00 USD) za pomocą POST /v1/topups, a następnie kup plan za pomocą POST /v1/orders. Obie operacje można wykonać jednym wywołaniem: doładowanie może zawierać zamówienie w purchase, a plan zostanie kupiony po zaksięgowaniu doładowania.

---

LocalSERP Proxy: LocalSERP Proxy to usługa proxy rezydencjalnych w USA do sprawdzania lokalnych wyników wyszukiwania, reklam i cen miasto po mieście, z płatnością w kryptowalutach i bez przesyłania dokumentu tożsamości.