Documentazione API

Ordini

Aggiornato a ottobre 2026

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.

5 min di lettura

Endpoint in questa pagina

GET /v1/catalog/products: Prodotti, piani e prezzi
POST /v1/orders: Acquista un piano usando il saldo (nuovo servizio, più traffico o estensione della porta)
GET /v1/orders: Elenca gli ordini
GET /v1/orders/{orderId}: Recupera un ordine

URL di base https://localserpproxy.com/api/v1. Per autenticazione, errori e limiti, consulta la panoramica dell’API.

Prodotti, piani e prezzi

GET/v1/catalog/products

Tutti i prodotti con i relativi piani e prezzi, esattamente come vengono addebitati al momento dell’ordine.

Pubblico: non serve una chiave API.

Risposta `200 OK`

{
  "data": [
    {
      "id": "residential",
      "name": "Residential proxies",
      "description": "Residential traffic for manual local search, advertising, price and application checks in US cities. State, city and ZIP selection, subject to available exits; no promise of GPS position or rankings.",
      "unit": "GB",
      "plans": [
        {
          "id": "res-10",
          "productId": "residential",
          "name": "Local team",
          "quantity": 10,
          "unit": "GB",
          "durationDays": null,
          "price": "7.50",
          "pricePerUnit": "0.75",
          "popular": false,
          "features": [
            "US city selection, subject to availability",
            "Traffic stays until used",
            "Rotating or sticky sessions"
          ],
          "available": true,
          "countries": null
        }
      ]
    }
  ]
}

Esempi di codice

curl

curl -s "https://localserpproxy.com/api/v1/catalog/products"

Python

import os
import requests

API = "https://localserpproxy.com/api/v1"

r = requests.get(f"{API}/catalog/products", timeout=30)
r.raise_for_status()
print(r.json())

Node.js

// Node.js 18+ (built-in fetch), ES module
const API = 'https://localserpproxy.com/api/v1';

const res = await fetch(`${API}/catalog/products`);
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());

Acquista un piano usando il saldo (nuovo servizio, più traffico o estensione di una porta)

POST/v1/orders

Il pagamento viene sempre effettuato dal saldo prepagato: il prezzo viene calcolato dall’API (prezzo di catalogo × quantity), l’importo viene scalato dal saldo, il servizio viene creato o esteso e l’ordine viene restituito completed con il relativo fulfillment. Le credenziali proxy sono disponibili subito.

Nuovo traffico residenziale: { "planId": "res-10" }.
Nuovo traffico 4G/5G a rotazione (per GB): { "planId": "mgb-10" } (un abbonamento al traffico con productId: "mobile-gb", fornito in fulfillment.residentialSubscriptionId).
Aggiungi traffico a un abbonamento esistente: { "planId": "res-10", "options": { "subscriptionId": "res_9x2m4k" } }: il piano deve appartenere al prodotto dell’abbonamento.
Nuova/e porta/e mobile/i: { "planId": "mob-us-30d", "quantity": 1, "options": { "country": "US" } }, facoltativamente con carrier (consulta gli operatori di un paese in Porte mobili). I piani per zona coprono solo i paesi della zona (422 su options.country altrimenti).
Estendi una porta mobile: { "planId": "mob-us-7d", "options": { "portId": "mob_2v8k1q" } } aggiunge la durata del piano a expiresAt.

Saldo insufficiente → 402 insufficient_balance, con l’importo mancante e una ricarica suggerita in error.details (missing, suggestedTopUp). In caso di errore non viene scalato alcun importo. Per pagare la differenza, avvia una ricarica includendo la stessa richiesta in purchase (POST /v1/topups): il piano viene acquistato non appena la ricarica viene accreditata.

Autenticazione: chiave API nell'intestazione Authorization: Bearer API_KEY.

Parametri

Nome	In	Tipo	Obbligatorio	Descrizione
`Idempotency-Key`	header	string	No	Chiave univoca (ad es. un UUID) per ripetere una richiesta POST in sicurezza. Conservata per 24 h. — max. 128 caratteri

Corpo della richiesta

Campo	Tipo	Obbligatorio	Descrizione
`planId`	string	Sì	—
`quantity`	integer	No	1–100, predefinito `1`
`options`	object	No	—

Esempio: Residenziale

{
  "planId": "res-10"
}

Esempio: Porte mobili

{
  "planId": "mob-us-30d",
  "quantity": 1,
  "options": {
    "country": "US",
    "carrier": "verizon",
    "autoRenew": true
  }
}

Esempio: Estendi porta

{
  "planId": "mob-us-7d",
  "options": {
    "portId": "mob_2v8k1q"
  }
}

Esempio: Traffico mobile

{
  "planId": "mgb-10"
}

Esempio: Porta per zona

{
  "planId": "mob-us-30d",
  "options": {
    "country": "US",
    "carrier": "verizon"
  }
}

Risposta `201 Created`

{
  "id": "ord_4f8k2m9q",
  "status": "completed",
  "productId": "residential",
  "planId": "res-10",
  "planName": "Local team",
  "quantity": 1,
  "unitPrice": "7.50",
  "subtotal": "7.50",
  "discount": "0.00",
  "total": "7.50",
  "promoCode": null,
  "currency": "USD",
  "topUpId": null,
  "options": {},
  "fulfillment": {
    "residentialSubscriptionId": "res_9x2m4k",
    "mobilePortIds": []
  },
  "createdAt": "2026-10-05T14:03:11Z",
  "paidAt": "2026-10-05T14:03:11Z"
}

Esempi di codice

curl

curl -s -X POST "https://localserpproxy.com/api/v1/orders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"planId":"res-10"}'

Python

import os, uuid
import requests

API = "https://localserpproxy.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4())}

r = requests.post(f"{API}/orders", headers=HEADERS, json={"planId": "res-10"}, timeout=30)
r.raise_for_status()
print(r.json())

Node.js

// Node.js 18+ (built-in fetch), ES module
import { randomUUID } from 'node:crypto';

const API = 'https://localserpproxy.com/api/v1';

const res = await fetch(`${API}/orders`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Idempotency-Key': randomUUID(), 'Content-Type': 'application/json' },
  body: JSON.stringify({ planId: 'res-10' }),
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());

Elenco ordini

GET/v1/orders

Autenticazione: chiave API nell'intestazione Authorization: Bearer API_KEY.

Parametri

Nome	In	Tipo	Obbligatorio	Descrizione
`page`	query	integer	No	≥ 1, predefinito `1`
`perPage`	query	integer	No	1–100, predefinito `20`
`status`	query	`completed` · `cancelled`	No	Gli ordini vengono creati già pagati (l’importo viene scalato dal saldo). `completed` — pagato e consegnato (credenziali disponibili subito).
`productId`	query	string	No	ID prodotto dal catalogo. Valori per LocalSERP Proxy: `residential` (GB), `mobile` (porte 4G/5G dedicate) e `mobile-gb` (traffico 4G/5G a rotazione per GB). I client devono gestire valori sconosciuti.

Risposta `200 OK`

{
  "data": [
    {
      "id": "ord_4f8k2m9q",
      "status": "completed",
      "productId": "residential",
      "planId": "res-10",
      "planName": "Local team",
      "quantity": 1,
      "unitPrice": "7.50",
      "subtotal": "7.50",
      "discount": "0.00",
      "total": "7.50",
      "promoCode": null,
      "currency": "USD",
      "topUpId": null,
      "options": {},
      "fulfillment": {
        "residentialSubscriptionId": "res_9x2m4k",
        "mobilePortIds": []
      },
      "createdAt": "2026-10-05T14:03:11Z",
      "paidAt": "2026-10-05T14:03:11Z"
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 1,
    "totalPages": 1
  }
}

Esempi di codice

curl

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

Python

import os
import requests

API = "https://localserpproxy.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

r = requests.get(f"{API}/orders", headers=HEADERS, timeout=30)
r.raise_for_status()
print(r.json())

Node.js

// Node.js 18+ (built-in fetch), ES module
const API = 'https://localserpproxy.com/api/v1';

const res = await fetch(`${API}/orders`, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());

Ottieni un ordine

GET/v1/orders/{orderId}

Autenticazione: chiave API nell'intestazione Authorization: Bearer API_KEY.

Parametri

Nome	In	Tipo	Obbligatorio	Descrizione
`orderId`	path	string	Sì	—

Risposta `200 OK`

{
  "id": "ord_4f8k2m9q",
  "status": "completed",
  "productId": "residential",
  "planId": "res-10",
  "planName": "Local team",
  "quantity": 1,
  "unitPrice": "7.50",
  "subtotal": "7.50",
  "discount": "0.00",
  "total": "7.50",
  "promoCode": null,
  "currency": "USD",
  "topUpId": null,
  "options": {},
  "fulfillment": {
    "residentialSubscriptionId": "res_9x2m4k",
    "mobilePortIds": []
  },
  "createdAt": "2026-10-05T14:03:11Z",
  "paidAt": "2026-10-05T14:03:11Z"
}

Esempi di codice

curl

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

Python

import os
import requests

API = "https://localserpproxy.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

r = requests.get(f"{API}/orders/ord_4f8k2m9q", headers=HEADERS, timeout=30)
r.raise_for_status()
print(r.json())

Node.js

// Node.js 18+ (built-in fetch), ES module
const API = 'https://localserpproxy.com/api/v1';

const res = await fetch(`${API}/orders/ord_4f8k2m9q`, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());

Prodotti, piani e prezzi

Risposta 200 OK

Esempi di codice

Acquista un piano usando il saldo (nuovo servizio, più traffico o estensione di una porta)

Parametri

Corpo della richiesta

Risposta 201 Created

Esempi di codice

Elenco ordini

Parametri

Risposta 200 OK

Esempi di codice

Ottieni un ordine

Parametri

Risposta 200 OK

Esempi di codice

Pagine correlate

Risposta `200 OK`

Risposta `201 Created`

Risposta `200 OK`

Risposta `200 OK`