# LocalSERP Proxy API-documentatie

> LocalSERP Proxy REST API op localserpproxy.com/api: API-sleutels, fouten, limieten en endpoints voor je saldo, opwaarderingen, bestellingen en proxy's.

- URL: https://localserpproxy.com/nl/docs/api/
- Laatst bijgewerkt: 2026-10-15
- Publisher: LocalSERP Proxy (https://localserpproxy.com)

Alles wat je in je account doet, kun je scripten: je saldo controleren, opwaarderen met crypto, een abonnement kopen, proxygegevens aanmaken en een mobiel IP-adres wijzigen. JSON via HTTPS, één API-sleutel en voorbeelden in curl, Python en Node.js.

## Hoe gebruik ik de LocalSERP Proxy API?

**Kort antwoord**

Stuur HTTPS-verzoeken naar `https://localserpproxy.com/api/v1` met je API-sleutel in de header `Authorization: Bearer API_KEY`. Maak de sleutel aan op de [ontwikkelaarspagina](https://localserpproxy.com/app/developer?lang=nl) van je account (of met `POST /v1/api-keys`) en geef deze alleen de benodigde rechten. Verzoeken en antwoorden zijn JSON; fouten worden altijd teruggestuurd als `{ "error": { "code", "message" } }`.

## In één oogopslag

| Kenmerk | Waarde |
| --- | --- |
| Basis-URL | `https://localserpproxy.com/api/v1` |
| Indeling | JSON via HTTPS, UTF-8 |
| Authenticatie | API-sleutel: `Authorization: Bearer API_KEY` |
| API-sleutelrechten | `read`, `proxies`, `billing` |
| Valuta | USD als tekenreeks met 2 decimalen (`"29.00"`) |
| Crypto-bedragen | Decimale tekenreeksen, nooit floats (`"0.00045210"`) |
| Dataverkeer | Bytes (1 GB = 1.000.000.000 bytes) |
| Datums | ISO 8601 in UTC (`2026-10-05T14:03:11Z`) |
| Versie | `/v1` in elk pad |

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

### Scopes

Geef elke sleutel alleen de rechten die je script nodig heeft. Een sleutel zonder de vereiste scope geeft `403 forbidden` terug.

| Scope | Wat de scope toestaat |
| --- | --- |
| `read` | alles lezen (account, saldo, services, gebruik). |
| `proxies` | proxyinstellingen en inloggegevens wijzigen (labels, automatisch verlengen, nieuwe wachtwoorden), subgebruikers beheren, de IP-allowlist beheren en mobiele poorten roteren (inclusief de rotatielink). |
| `billing` | bestellingen plaatsen en saldo opwaarderen, betalen met je saldo. |

De enige uitzondering is de **link voor mobiele rotatie**, bedoeld om te openen via een bladwijzer in je browser of een gewone `curl`: `GET https://localserpproxy.com/api/v1/mobile/PORT_ID/rotate?key=API_KEY` (sleutel met de scope `proxies`). Bekijk [Mobiele poorten en IP-rotatie](https://localserpproxy.com/nl/docs/api/mobile/).

*Je saldo bekijken*

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

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

### Statuscodes

| Status | Betekenis |
| --- | --- |
| `422` | `validation_failed`: een of meer velden zijn ongeldig. |
| `401` | `unauthorized`: token ontbreekt, is ongeldig of is verlopen. |
| `402` | `insufficient_balance`: het saldo is niet toereikend voor de bestelling. `details` = `InsufficientBalanceDetails`. |
| `403` | `forbidden`: de API-sleutel heeft niet de vereiste scope of het account is opgeschort. |
| `404` | `not_found`: de resource bestaat niet of hoort bij een ander account. |
| `409` | `conflict` (of een specifiekere code): de actie is in de huidige status niet mogelijk. |
| `429` | `rate_limited` of `rotation_too_soon`. |

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

## API-referentie

- **[Account en saldo](https://localserpproxy.com/nl/docs/api/account/)** — Bekijk je accountinstellingen, je prepaid USD-saldo en alle mutaties op dat saldo (opwaarderingen, aankopen, terugbetalingen).
- **[Opwaarderen met crypto](https://localserpproxy.com/nl/docs/api/top-ups/)** — Waardeer je saldo op met crypto: ontvang het stortingsadres en het exacte bedrag, verstuur precies dat bedrag, meld dat de betaling is verzonden (het transactie-ID is optioneel) en volg de opwaardering totdat het saldo is bijgeschreven. Je saldo betaalt voor al onze abonnementen.
- **[Bestellingen](https://localserpproxy.com/nl/docs/api/orders/)** — Bekijk de abonnementen en hun prijzen, koop een abonnement met je saldo (nieuwe dienst, meer verkeer of verlenging van een poort) en bekijk je eerdere bestellingen.
- **[Residentiële proxy's en inloggegevens](https://localserpproxy.com/nl/docs/api/residential/)** — Beheer verkeersabonnementen (residentiële proxy's en roterende 4G/5G per GB): proxy-inloggegevens, subgebruikers met eigen inloggegevens en verkeerslimiet, dagelijks gebruik en de locaties waarop je je kunt richten via de proxygebruikersnaam.
- **[Mobiele poorten en IP-rotatie](https://localserpproxy.com/nl/docs/api/mobile/)** — Speciale 4G/5G-poorten: wijzig het IP-adres direct of volgens een timer, gebruik de rotatielink en bekijk het dagelijkse dataverbruik.
- **[API-sleutels en IP-allowlist](https://localserpproxy.com/nl/docs/api/api-keys/)** — Maak API-sleutels met beperkte rechten aan en trek ze in, en beheer de IP-allowlist: maximaal 10 bron-IP-adressen mogen de proxy's zonder gebruikersnaam en wachtwoord gebruiken.

> **Betalen vanuit een script** Plannen worden altijd betaald met het vooraf opgeladen USD-saldo. Laad tegoed op met crypto (minimaal 25.00 USD) via POST /v1/topups en koop daarna via POST /v1/orders. Beide kunnen in één aanroep: een opwaardering kan de bestelling bevatten in purchase, waarna het plan wordt gekocht zodra het tegoed is bijgeschreven.

---

LocalSERP Proxy: LocalSERP Proxy is een residentiële proxydienst in de VS om lokale zoekresultaten, advertenties en prijzen per stad te controleren, met betaling in crypto en zonder een identiteitsbewijs te uploaden.