Catálogo y geo

Alcance: catalog:read.

GET /api/v1/products

Qué se vende, con el precio para el titular de la clave. La lista solo incluye lo que se puede comprar ahora mismo; un slug fuera de la lista responde 400 unknown_product.

Campo	Significado
slug	se pasa en product al calcular el precio y al comprar: residential, ipv4
family	tipo de producto: traffic_gateway (tráfico) o dedicated (direcciones fijas)
unit	unidad de venta: gb o ip
unit_price	precio del gigabyte para usted; en ipv4 es null, el precio depende del país y del período
monthly_price_from	en ipv4: el precio más bajo de una dirección por mes para usted; en tráfico, null
min_volume, volume_presets, volume_discounts	volumen de compra de tráfico: mínimo, sugerencias para la interfaz, escala de descuentos por volumen en porcentaje

El importe final lo calcula POST /api/v1/quote.

Parámetros del producto

GET /api/v1/products/{product}/options: qué se puede elegir al comprar direcciones fijas. En el producto de tráfico countries está vacío: se compra solo por volumen.

curl "https://ipv.rent/api/v1/products/ipv4/options" \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "type": "ipv4",
  "countries": [
    {
      "code": "us",
      "name": "United States",
      "periods": ["week", "2_weeks", "month", "2_months", "3_months"],
      "quantity_max": null,
      "plans": [
        {
          "id": "dc",
          "traffic_gb": null,
          "periods": ["week", "2_weeks", "month", "2_months", "3_months"],
          "operators": [
            {
              "id": "united-states",
              "name": "United States",
              "available": 374
            }
          ]
        }
      ]
    }
  ]
}

Campo	A dónde va en la compra	Significado
countries[].code	country	país, ISO 3166-1 alpha-2
countries[].periods	period	plazos para los que se vende el país
countries[].quantity_max	quantity	cuántas direcciones se pueden tomar en una compra; null: no hay un límite aparte
plans[].id	plan	plan; se puede omitir si el país tiene un solo plan
plans[].operators[].id	operator	ubicación: el país entero o una ciudad; obligatoria
plans[].operators[].available	-	cuántas direcciones hay libres ahora en la ubicación

Vuelva a leer los parámetros antes de comprar en lugar de guardarlos: el conjunto de países y las existencias cambian.

Rechazos: 400 unknown_product (slug desconocido o producto que no está a la venta).

Catálogo geográfico

Solo para Residential: hacia dónde puede salir un paquete de tráfico. Cuatro niveles, y cada uno de ellos:

• acepta el parámetro obligatorio product, hoy residential;
• admite If-None-Match y responde 304 sin cuerpo;
• devuelve version y no distingue mayúsculas de minúsculas en los códigos.

ETag es un hash opaco de la versión; la misma versión en forma legible es el campo version.

Ruta	Parámetros	Respuesta
GET /api/v1/geo/countries	product	countries[] con code, name, pool (thin | normal | deep)
GET /api/v1/geo/states	product, country	states[] con code y name
GET /api/v1/geo/cities	product, country, state (opcional)	cities[] con code y name
GET /api/v1/geo/asns	product, country	asns[] con code y name

curl "https://ipv.rent/api/v1/geo/countries?product=residential" \
  -H 'Authorization: Bearer YOUR_API_KEY'

Sin state, cities devuelve todas las ciudades del país. Un país que ya no tiene servicio devuelve una lista vacía, no un rechazo.

Rechazos: 400 validation_failed (falta product o country), unknown_product (slug desconocido o producto que no está a la venta); 503 catalog_unavailable.

Los códigos de estas respuestas son lo que acepta geo al generar conexiones; un valor fuera del catálogo recibe 422 invalid_targeting.