Sviluppatori

Documentazione API di LocalSERP Proxy

Aggiornato a ottobre 2026

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.

5 min di lettura

Risposta rapida

Come si usa l’API di LocalSERP Proxy?

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

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.

Controlla il saldo

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

{
  "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).