Desarrolladores

Documentación de API e integración

Dos formas de integrar SocksNode: conéctate directamente a la pasarela de proxy mediante HTTP(S) o SOCKS5, o gestiona el ancho de banda, el uso y los proxies de forma programática a través de la REST API.

En esta página

Proxies móviles

REST API 4G/5G

Compra y gestiona proxies móviles 4G/5G mediante API. Cada Mobile IP es una IP de operador rotativa (hasta 3 conexiones) por la duración elegida. Los alquileres y renovaciones se cobran de tu saldo de cuenta prepago (USD). Usa los ámbitos read:proxies / write:proxies.

https://socksnode.com/api/v1

Autenticación

URL base https://socksnode.com/api/v1. Crea una clave en Dashboard → API access y envíala como un token Bearer. Las claves tienen alcance limitado: solicita solo lo que necesites.

AlcanceConcede
read:usageAnalíticas de saldo y uso
read:proxiesListar credenciales de proxy guardadas
write:proxiesGenerar nuevas credenciales de proxy
purchaseComprar GB para proxies rotativos residenciales, de datacenter y móviles, comprar y renovar IPs estáticas e ISP, alquilar y renovar puertos 4G/5G, activar la renovación automática, comprar IPs de 24 horas y direcciones y ancho de banda de IP Vault, con cargo a tu saldo.

Límite de tasa: 120 solicitudes por minuto por clave (la generación de proxies se limita aún más). Mantén tu clave en secreto y en el lado del servidor.

GET /api/v1/account HTTP/1.1
Host: socksnode.com
Authorization: Bearer sk_YOUR_API_KEY

Errores

Los errores devuelven un cuerpo JSON { "error": { "code", "message" } } con el estado HTTP correspondiente:

EstadoSignificado
400Cuerpo de solicitud o parámetros no válidos
401Clave de API ausente, no válida o revocada
402Saldo de ancho de banda insuficiente para generar proxies
403La clave de API carece del alcance requerido
404No encontrado, o no es tuyo.
409El estado del puerto no lo permite ahora, p. ej. ha caducado.
429Límite de tasa superado — consulta la cabecera Retry-After
502Falló la red de origen. No se te cobró.
503El producto está en mantenimiento. Inténtalo en breve.
HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "error": {
    "code": "no_bandwidth",
    "message": "…"
  }
}

Endpoints de la API

duraciones, países, estados y operadores

GET/mobile/catalog

Alcance: read:proxies

Parámetros de consulta

  • countryintegerOpcional

    Id de país. Devuelve sus estados.

  • stateintegerOpcional

    Id de estado. Devuelve sus operadores.

  • availabilitystringOpcional

    Pon 1 para añadir cuánto queda libre de cada opción ahora mismo.

    1

  • tierstringOpcional

    De qué plan informar el stock.

    economybasicturboPredeterminado: basic

  • modemsstringOpcional

    Pon 1 junto con state para listar todos sus módems, libres y ocupados, con cuánto tiempo mantiene cada uno su IP. Mismos campos que /mobile/proxies/PROXY_ID/modems.

    1

  • carrierintegerOpcional

    Id de operador. Con modems=1, lista solo los módems de ese operador.

curl "https://socksnode.com/api/v1/mobile/catalog?state=12&availability=1" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Respuesta200
{
  "data": {
    "carriers": [
      { "id": 34, "name": "5G AT&T", "status": "ok", "pct": 82 },
      { "id": 35, "name": "5G T-Mobile", "status": "low", "pct": 11 },
      { "id": 36, "name": "5G Verizon", "status": "none", "pct": 0 }
    ]
  }
}
// status: "ok" | "low" | "none" | "unknown"
// Country and state stock is refreshed every ~15 min;
// carrier stock is checked live, right before you choose.

lista tus proxies móviles (con credenciales)

GET/mobile/proxies

Alcance: read:proxies

Sin parámetros.

curl "https://socksnode.com/api/v1/mobile/proxies" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Respuesta200
{
  "data": [
    {
      "id": "clx…",
      "name": "Port 1",
      "host": "mobile.socksnode.com",
      "port": 9094,
      "protocol": "socks5",
      "username": "sn_a1b2c3d4",
      "password": "…",
      "authMode": "userpass",
      "allowedIps": [],
      "country": "UNITED STATES",
      "state": "FLORIDA",
      "carrier": "5G AT&T",
      "rotationMinutes": 15,
      "modem": { "id": "3f9c0a1b2d4e5f607182", "code": "K7QM" },
      "status": "active",
      "paused": false,
      "bytesUsed": 0,
      "lastExitIp": null,
      "expiresAt": "2026-10-30T04:46:53.000Z"
    }
  ]
}

un proxy: incluye datos usados + última IP de salida

GET/mobile/proxies/{id}

Alcance: read:proxies

Parámetros de ruta

  • idstringObligatorio

    El id del proxy móvil.

curl "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Respuesta200
{
  "data": {
    "id": "clx…",
    "name": "Port 1",
    "host": "mobile.socksnode.com",
    "port": 9094,
    "protocol": "socks5",
    "username": "sn_a1b2c3d4",
    "password": "…",
    "authMode": "userpass",
    "allowedIps": [],
    "country": "UNITED STATES",
    "state": "FLORIDA",
    "carrier": "5G AT&T",
    "rotationMinutes": 15,
    "modem": { "id": "3f9c0a1b2d4e5f607182", "code": "K7QM" },
    "status": "active",
    "paused": false,
    "bytesUsed": 0,
    "lastExitIp": null,
    "expiresAt": "2026-10-30T04:46:53.000Z"
  }
}

compra N puertos (se cobra del saldo; 402 si es insuficiente)

POST/mobile/proxies

Alcance: purchase

Parámetros del cuerpo

  • tierKeystringOpcional

    Plan que alquilar.

    economybasicturboPredeterminado: basic

  • durationKeystringObligatorio

    Duración del alquiler. Debe ser una que venda el plan.

    2h12h1d3d7d15d30d

  • quantityintegerOpcional

    Puertos que alquilar, 1–50. Si alguno no se puede crear, solo pagas el resto.

    Predeterminado: 1

  • countryIdintegerOpcional

    Id de país del catálogo. Omítelo para tomar cualquier ubicación disponible.

  • cityIdintegerOpcional

    Id de estado del catálogo.

  • spIdintegerOpcional

    Id de operador del catálogo.

  • modemIdstringOpcional

    Un id de módem de /mobile/catalog?modems=1 (mismo plan). Requiere cityId y quantity 1. 409 modem_taken si no tiene plaza libre; no se te cobra.

  • protocolstringOpcional

    Protocolo del puerto.

    sockshttpPredeterminado: socks

curl -X POST "https://socksnode.com/api/v1/mobile/proxies" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "durationKey": "30d",
    "quantity": 1,
    "countryId": 1,
    "cityId": 12,
    "spId": 34,
    "protocol": "socks"
  }'
Respuesta201
{
  "data": [
    {
      "id": "clx…",
      "name": "Port 1",
      "host": "mobile.socksnode.com",
      "port": 9094,
      "protocol": "socks5",
      "username": "sn_a1b2c3d4",
      "password": "…",
      "authMode": "userpass",
      "allowedIps": [],
      "country": "UNITED STATES",
      "state": "FLORIDA",
      "carrier": "5G AT&T",
      "rotationMinutes": 15,
      "modem": { "id": "3f9c0a1b2d4e5f607182", "code": "K7QM" },
      "status": "active",
      "paused": false,
      "bytesUsed": 0,
      "lastExitIp": null,
      "expiresAt": "2026-10-30T04:46:53.000Z"
    }
  ],
  "charged": 40
}

cambia país/estado/operador (gratis)

POST/mobile/proxies/{id}/switch

Alcance: write:proxies

Parámetros de ruta

  • idstringObligatorio

    El id del proxy móvil.

Parámetros del cuerpo

  • countryIdintegerObligatorio

    Id de país del catálogo.

  • cityIdintegerOpcional

    Id de estado del catálogo.

  • spIdintegerOpcional

    Id de operador del catálogo.

  • modemIdstringOpcional

    Un id de módem de la lista de módems. Requiere cityId. El puerto pasa solo a ese módem: 409 modem_taken si está lleno, 404 modem_gone si ya no está en la lista.

  • protocolstringOpcional

    Por defecto, el protocolo actual del puerto.

    sockshttp

curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/switch" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "countryId": 3,
    "cityId": 12,
    "spId": 34,
    "modemId": "8d21e7c40b9a6f5e3c12"
  }'
Respuesta200
{
  "data": {
    "id": "clx…",
    "host": "mobile.socksnode.com",
    "port": 9095,
    "protocol": "socks5",
    "country": "UNITED STATES",
    "state": "FLORIDA",
    "carrier": "5G AT&T",
    "status": "active"
  }
}
// + every other field of GET /mobile/proxies/{id}

lista los módems de un estado para un puerto (libres y ocupados, tiempo de IP)

GET/mobile/proxies/{id}/modems

Alcance: read:proxies

Parámetros de ruta

  • idstringObligatorio

    El id del proxy móvil.

Parámetros de consulta

  • stateintegerObligatorio

    Id de estado del catálogo. Lista los módems de ese estado para el plan de este puerto.

  • carrierintegerOpcional

    Id de operador. Con modems=1, lista solo los módems de ese operador.

curl "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/modems?state=12&carrier=34" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Respuesta200
{
  "data": {
    "modems": [
      {
        "id": "3f9c0a1b2d4e5f607182",
        "code": "K7QM",
        "carrier": "5G AT&T",
        "free": true,
        "current": true,
        "yours": 0,
        "yourPorts": [],
        "rotationMinutes": 30,
        "lastIp": "174.208.161.27",
        "lastOkAt": "2026-10-28T03:12:40.000Z",
        "failing": false
      },
      {
        "id": "8d21e7c40b9a6f5e3c12",
        "code": "R4XB",
        "carrier": "5G AT&T",
        "free": false,
        "current": false,
        "yours": 0,
        "yourPorts": [],
        "rotationMinutes": 60,
        "lastIp": null,
        "lastOkAt": null,
        "failing": false
      }
    ],
    "free": 1,
    "total": 2
  }
}
// free: has a slot for one more port. current: this port is on it.
// yours: your other live ports on it (they share its IP); yourPorts: their port numbers.
// rotationMinutes: how long the modem keeps one IP.

nueva IP de salida (gratis)

POST/mobile/proxies/{id}/rotate

Alcance: write:proxies

Parámetros de ruta

  • idstringObligatorio

    El id del proxy móvil.

curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/rotate" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Respuesta200
{
  "data": {
    "id": "clx…",
    "host": "mobile.socksnode.com",
    "port": 9095,
    "protocol": "socks5",
    "country": "UNITED STATES",
    "state": "FLORIDA",
    "carrier": "5G AT&T",
    "status": "active"
  }
}
// + every other field of GET /mobile/proxies/{id}

lee la IP de salida en vivo

GET/mobile/proxies/{id}/check-ip

Alcance: read:proxies

Parámetros de ruta

  • idstringObligatorio

    El id del proxy móvil.

curl "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/check-ip" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Respuesta200
{
  "data": { "ip": "174.208.161.27" }
}

cambia SOCKS5 ↔ HTTP(S)

POST/mobile/proxies/{id}/protocol

Alcance: write:proxies

Parámetros de ruta

  • idstringObligatorio

    El id del proxy móvil.

Parámetros del cuerpo

  • protocolstringObligatorio

    Protocolo del puerto.

    sockshttp

curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/protocol" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "http"
  }'
Respuesta200
{
  "data": {
    "id": "clx…",
    "host": "mobile.socksnode.com",
    "port": 9095,
    "protocol": "socks5",
    "country": "UNITED STATES",
    "state": "FLORIDA",
    "carrier": "5G AT&T",
    "status": "active"
  }
}
// + every other field of GET /mobile/proxies/{id}

cambia el modo de auth

POST/mobile/proxies/{id}/auth

Alcance: write:proxies

Parámetros de ruta

  • idstringObligatorio

    El id del proxy móvil.

Parámetros del cuerpo

  • modestringObligatorio

    userpass entra con usuario y contraseña; whitelist deja conectar sin ella a las IP de la lista.

    userpasswhitelist

  • allowedIpsstring[]Opcional

    Hasta 3 direcciones IPv4 o IPv6 públicas, sin rangos. Necesario para whitelist.

    Predeterminado: []

curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/auth" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "whitelist",
    "allowedIps": [
      "203.0.113.7"
    ]
  }'
Respuesta200
{
  "data": {
    "id": "clx…",
    "host": "mobile.socksnode.com",
    "port": 9095,
    "protocol": "socks5",
    "country": "UNITED STATES",
    "state": "FLORIDA",
    "carrier": "5G AT&T",
    "status": "active"
  }
}
// + every other field of GET /mobile/proxies/{id}

renueva el puerto (se cobra del saldo)

POST/mobile/proxies/{id}/renew

Alcance: purchase

Parámetros de ruta

  • idstringObligatorio

    El id del proxy móvil.

Parámetros del cuerpo

  • durationKeystringObligatorio

    Duración del alquiler. Debe ser una que venda el plan del puerto.

    2h12h1d3d7d15d30d

curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/renew" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "durationKey": "30d"
  }'
Respuesta200
{
  "data": {
    "id": "clx…",
    "host": "mobile.socksnode.com",
    "port": 9095,
    "protocol": "socks5",
    "country": "UNITED STATES",
    "state": "FLORIDA",
    "carrier": "5G AT&T",
    "status": "active"
  },
  "charged": 40
}
// + every other field of GET /mobile/proxies/{id}

¿Listo para construir?

Genera credenciales en el panel o crea una clave de API para automatizarlo.