# Documentazione API di LocalSERP Proxy

> API REST di LocalSERP Proxy su localserpproxy.com/api: chiavi API, errori, limiti ed endpoint per saldo, ricariche, ordini e proxy.

- URL: https://localserpproxy.com/it/docs/api/
- Ultimo aggiornamento: 2026-10-15
- Publisher: LocalSERP Proxy (https://localserpproxy.com)

Puoi automatizzare tutte le operazioni del tuo account: controllare il saldo, ricaricare in criptovaluta, acquistare un piano, creare credenziali proxy e cambiare IP mobile. JSON su HTTPS, una chiave API ed esempi con curl, Python e Node.js.

## Come si usa l’API di LocalSERP Proxy?

**Risposta rapida**

Invia richieste HTTPS a `https://localserpproxy.com/api/v1` con la tua chiave API nell’intestazione `Authorization: Bearer API_KEY`. Crea la chiave nella [pagina sviluppatori](https://localserpproxy.com/app/developer?lang=it) del tuo account (oppure con `POST /v1/api-keys`) e assegnale solo gli ambiti necessari. Richieste e risposte sono in JSON; gli errori vengono sempre restituiti come `{ "error": { "code", "message" } }`.

## In breve

| Attributo | Valore |
| --- | --- |
| URL di base | `https://localserpproxy.com/api/v1` |
| Formato | JSON su HTTPS, UTF-8 |
| Autenticazione | Chiave API: `Authorization: Bearer API_KEY` |
| Ambiti della chiave API | `read`, `proxies`, `billing` |
| Valuta | USD come stringa con 2 decimali (`"29.00"`) |
| Importi in criptovaluta | Stringhe decimali, mai numeri in virgola mobile (`"0.00045210"`) |
| Traffico | Byte (1 GB = 1.000.000.000 byte) |
| Date | ISO 8601 in UTC (`2026-10-05T14:03:11Z`) |
| Versione | `/v1` in ogni percorso |

## Autenticazione

Ogni richiesta, tranne il catalogo pubblico, richiede una chiave API: `Authorization: Bearer API_KEY`. La chiave viene mostrata per intero **una sola volta**, quando la crei: conservala come una password. Puoi revocare una chiave in qualsiasi momento; le richieste effettuate con quella chiave restituiranno quindi `401 unauthorized`.

### Ambiti

Assegna a ogni chiave solo gli ambiti necessari al tuo script. Una chiave senza l'ambito richiesto restituisce `403 forbidden`.

| Ambito | Cosa consente |
| --- | --- |
| `read` | leggere tutti i dati (account, saldo, servizi, utilizzo). |
| `proxies` | modificare le impostazioni e le credenziali del proxy (etichette, rinnovo automatico, nuove password), gestire i sottoutenti, gestire la lista degli IP consentiti e ruotare le porte mobili (include il link di rotazione). |
| `billing` | creare ordini e ricariche, pagare con il saldo. |

L’unica eccezione è il **link di rotazione mobile**, pensato per essere richiamato da un segnalibro del browser o da un semplice `curl`: `GET https://localserpproxy.com/api/v1/mobile/PORT_ID/rotate?key=API_KEY` (chiave con ambito `proxies`). Consulta [Porte mobili e rotazione degli IP](https://localserpproxy.com/it/docs/api/mobile/).

*Controlla il saldo*

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

## Richieste e risposte

- **JSON in ingresso, JSON in uscita**: invia `Content-Type: application/json` con un corpo.
- Gli **elenchi** che possono crescere sono paginati con `page` (a partire da 1) e `perPage` (1–100, predefinito 20) e restituiscono `{ "data": [...], "pagination": { "page", "perPage", "total", "totalPages" } }`. Gli elenchi brevi restituiscono `{ "data": [...] }`.
- Gli **ID** sono stringhe opache con un prefisso di tipo: `ord_` (ordine), `top_` (ricarica), `txn_` (movimento del saldo), `res_` (abbonamento al traffico), `mob_` (porta mobile), `key_` (chiave API) e `ipw_` (voce della lista degli IP consentiti).
- **Nuovi tentativi sicuri**: `POST /v1/orders` e `POST /v1/topups` accettano un’intestazione `Idempotency-Key` (qualsiasi stringa univoca, conservata per 24 h). Ripetendo la richiesta con la stessa chiave viene restituita la prima risposta, senza effettuare un secondo acquisto o una seconda ricarica.
- Gli **esempi** mostrano la struttura di ogni risposta: gli ID, gli IP, gli importi e le date sono a titolo illustrativo; gli ID dei piani e i prezzi sono quelli reali.

## Errori

Tutti gli errori hanno lo stesso corpo. `code` è stabile ed è pensato per il tuo codice; `message` è una frase in inglese che può cambiare. Gli errori di convalida elencano ogni campo non valido in `fields`. Potrebbero essere aggiunti nuovi codici: gestisci quelli sconosciuti come errori generici.

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

### Codici di stato

| Stato | Significato |
| --- | --- |
| `422` | `validation_failed`: uno o più campi non sono validi. |
| `401` | `unauthorized`: token mancante, non valido o scaduto. |
| `402` | `insufficient_balance`: il saldo non è sufficiente per coprire l’ordine. `details` = `InsufficientBalanceDetails`. |
| `403` | `forbidden`: la chiave API non dispone dell’ambito richiesto oppure l’account è sospeso. |
| `404` | `not_found`: la risorsa non esiste o appartiene a un altro account. |
| `409` | `conflict` (o un codice più specifico): l’azione non è possibile nello stato attuale. |
| `429` | `rate_limited` o `rotation_too_soon`. |

## Limiti di frequenza

Ogni risposta include `RateLimit-Limit`, `RateLimit-Remaining` e `RateLimit-Reset`. Se si supera il limite, l’API risponde con `429 rate_limited` e un header `Retry-After` (secondi): attendi il tempo indicato, poi riprova. L’IP di una porta mobile può essere cambiato al massimo una volta ogni 30 secondi (`429 rotation_too_soon`, con `Retry-After`).

## Documentazione API

- **[Account e saldo](https://localserpproxy.com/it/docs/api/account/)** — Consulta le impostazioni del tuo account, il saldo prepagato in USD e tutti i movimenti del saldo (ricariche, acquisti, rimborsi).
- **[Ricariche in criptovaluta](https://localserpproxy.com/it/docs/api/top-ups/)** — Ricarica il saldo in criptovaluta: ottieni l’indirizzo di deposito e l’importo esatto, invia esattamente quell’importo, segnala l’invio del pagamento (l’ID della transazione è facoltativo), quindi segui la ricarica fino all’accredito sul saldo. Il saldo può essere usato per acquistare qualsiasi nostro piano.
- **[Ordini](https://localserpproxy.com/it/docs/api/orders/)** — Consulta i piani e i relativi prezzi, acquista un piano usando il saldo (nuovo servizio, più traffico o estensione di una porta) e consulta gli ordini passati.
- **[Proxy residenziali e credenziali](https://localserpproxy.com/it/docs/api/residential/)** — Gestisci gli abbonamenti al traffico (proxy residenziali e proxy mobili 4G/5G a GB): credenziali proxy, sottoutenti con credenziali e limite di traffico propri, utilizzo giornaliero e località selezionabili nel nome utente del proxy.
- **[Porte mobili e rotazione degli IP](https://localserpproxy.com/it/docs/api/mobile/)** — Porte dedicate 4G/5G: cambia IP subito o con un timer, usa il link di rotazione e consulta il traffico giornaliero.
- **[Chiavi API e IP consentiti](https://localserpproxy.com/it/docs/api/api-keys/)** — Crea e revoca chiavi API con autorizzazioni limitate e gestisci gli IP consentiti: fino a 10 IP di origine possono usare i proxy senza nome utente e password.

> **Pagare tramite script** I piani si pagano sempre usando il saldo prepagato in USD. Ricarica in criptovaluta (minimo 25.00 USD) con POST /v1/topups, poi acquista con POST /v1/orders. Puoi eseguire entrambe le operazioni con una sola chiamata: la ricarica può includere l’ordine in purchase e il piano viene acquistato non appena la ricarica viene accreditata.

---

LocalSERP Proxy: LocalSERP Proxy è un servizio di proxy residenziali negli Stati Uniti per verificare risultati di ricerca locali, annunci e prezzi città per città, con pagamento in criptovalute e senza caricare documenti di identità.