Referência da API

Pedidos

Atualizado em outubro de 2026

Consulte os planos e seus preços, compre um plano usando o saldo (novo serviço, mais tráfego ou extensão de porta) e consulte seus pedidos anteriores.

5 min de leitura

Endpoints nesta página

GET /v1/catalog/products: Produtos, planos e preços
POST /v1/orders: Comprar um plano com o saldo (novo serviço, mais tráfego ou extensão de porta)
GET /v1/orders: Listar pedidos
GET /v1/orders/{orderId}: Consultar um pedido

URL base https://localserpproxy.com/api/v1. Autenticação, erros e limites: consulte a visão geral da API.

Produtos, planos e preços

GET/v1/catalog/products

Todos os produtos com seus planos e preços, exatamente como cobrados no pedido.

Público: não é necessária uma chave da API.

Resposta `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
        }
      ]
    }
  ]
}

Exemplos de código

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());

Comprar um plano com o saldo (novo serviço, mais tráfego ou extensão de porta)

POST/v1/orders

O pagamento é sempre feito com o saldo pré-pago: o preço é calculado pela API (preço do catálogo × quantity), o valor é debitado do saldo, o serviço é criado ou estendido e o pedido é retornado completed com seu fulfillment. As credenciais do proxy ficam disponíveis imediatamente.

Novo tráfego residencial: { "planId": "res-10" }.
Novo tráfego rotativo 4G/5G (por GB): { "planId": "mgb-10" } (uma assinatura de tráfego com productId: "mobile-gb", entregue em fulfillment.residentialSubscriptionId).
Adicionar tráfego a uma assinatura existente: { "planId": "res-10", "options": { "subscriptionId": "res_9x2m4k" } }: o plano deve pertencer ao produto da assinatura.
Nova(s) porta(s) móvel(is): { "planId": "mob-us-30d", "quantity": 1, "options": { "country": "US" } }, opcionalmente com carrier (consulte as operadoras de um país em Portas móveis). Os planos por zona cobrem apenas os países da zona (422 em options.country caso contrário).
Estender uma porta móvel: { "planId": "mob-us-7d", "options": { "portId": "mob_2v8k1q" } } adiciona a duração do plano a expiresAt.

Saldo insuficiente → 402 insufficient_balance, com o valor que falta e uma sugestão de recarga em error.details (missing, suggestedTopUp). Nenhum valor é debitado em caso de erro. Para pagar a diferença, inicie uma recarga com a mesma solicitação em purchase (POST /v1/topups): o plano é comprado assim que a recarga for creditada.

Autenticação: chave da API no cabeçalho Authorization: Bearer API_KEY.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
`Idempotency-Key`	header	string	Não	Chave única (por exemplo, um UUID) para repetir uma solicitação POST com segurança. Mantida por 24 h. — máx. 128 caracteres

Corpo da solicitação

Campo	Tipo	Obrigatório	Descrição
`planId`	string	Sim	—
`quantity`	integer	Não	1–100, padrão `1`
`options`	object	Não	—

Exemplo: Residencial

{
  "planId": "res-10"
}

Exemplo: Portas móveis

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

Exemplo: Estender porta

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

Exemplo: Tráfego móvel

{
  "planId": "mgb-10"
}

Exemplo: Porta por zona

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

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

Exemplos de código

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());

Listar pedidos

GET/v1/orders

Autenticação: chave da API no cabeçalho Authorization: Bearer API_KEY.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
`page`	query	integer	Não	≥ 1, padrão `1`
`perPage`	query	integer	Não	1–100, padrão `20`
`status`	query	`completed` · `cancelled`	Não	Os pedidos são criados já pagos (debitados do saldo). `completed` — pago e entregue (credenciais disponíveis imediatamente).
`productId`	query	string	Não	ID do produto no catálogo. Valores para LocalSERP Proxy: `residential` (GB), `mobile` (portas dedicadas 4G/5G) e `mobile-gb` (tráfego rotativo 4G/5G por GB). Os clientes devem aceitar valores desconhecidos.

Resposta `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
  }
}

Exemplos de código

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());

Consultar um pedido

GET/v1/orders/{orderId}

Autenticação: chave da API no cabeçalho Authorization: Bearer API_KEY.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
`orderId`	path	string	Sim	—

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

Exemplos de código

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());

Produtos, planos e preços

Resposta 200 OK

Exemplos de código

Comprar um plano com o saldo (novo serviço, mais tráfego ou extensão de porta)

Parâmetros

Corpo da solicitação

Resposta 201 Created

Exemplos de código

Listar pedidos

Parâmetros

Resposta 200 OK

Exemplos de código

Consultar um pedido

Parâmetros

Resposta 200 OK

Exemplos de código

Páginas relacionadas

Resposta `200 OK`

Resposta `201 Created`

Resposta `200 OK`

Resposta `200 OK`