目录与地理位置

权限：catalog:read。

GET /api/v1/products

在售产品，价格按密钥所有者计算。列表中只有当前可以购买的产品；不在列表中的 slug 返回 400 unknown_product。

字段	含义
`slug`	计算价格和购买时作为 `product` 传入：`residential`、`ipv4`
`family`	产品类型：`traffic_gateway`（流量）或 `dedicated`（固定地址）
`unit`	销售单位：`gb` 或 `ip`
`unit_price`	你的每 GB 价格；`ipv4` 为 `null`，价格取决于国家和周期
`monthly_price_from`	`ipv4`：你的单个地址最低月价；流量产品为 `null`
`min_volume`, `volume_presets`, `volume_discounts`	流量购买量：最小值、界面预设值、按量折扣阶梯（百分比）

总金额由 POST /api/v1/quote 计算。

产品参数

GET /api/v1/products/{product}/options - 购买固定地址时可选的内容。流量产品的 countries 为空：它只按流量购买。

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

字段	购买时对应的字段	含义
`countries[].code`	`country`	国家，ISO 3166-1 alpha-2
`countries[].periods`	`period`	该国家可售的期限
`countries[].quantity_max`	`quantity`	单次购买可购的地址数量；`null` - 没有单独限制
`plans[].id`	`plan`	资费方案；如果该国家只有一个方案，可以不传
`plans[].operators[].id`	`operator`	位置：整个国家或某个城市；必填
`plans[].operators[].available`	-	该位置当前可用的地址数量

请在购买前重新读取参数，不要缓存在本地：国家列表和库存会变化。

错误：400 unknown_product（slug 未知或产品不在售）。

地理目录

仅适用于 Residential：流量套餐可以从哪些位置出口。共四个层级，每个层级都：

接受必填的 product - 目前为 residential；
支持 If-None-Match，并返回不带响应体的 304；
返回 version，代码不区分大小写。

ETag - 不透明的版本哈希；同一版本的可读形式是 version 字段。

路由	参数	响应
`GET /api/v1/geo/countries`	`product`	`countries[]`，含 `code`、`name`、`pool` (`thin` \| `normal` \| `deep`)
`GET /api/v1/geo/states`	`product`, `country`	`states[]`，含 `code` 和 `name`
`GET /api/v1/geo/cities`	`product`, `country`, `state`（可选）	`cities[]`，含 `code` 和 `name`
`GET /api/v1/geo/asns`	`product`, `country`	`asns[]`，含 `code` 和 `name`

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

不传 state 时，cities 返回该国家的所有城市。不再提供服务的国家返回空列表，而不是错误。

错误：400 validation_failed（未传 product 或 country）、unknown_product（slug 未知或产品不在售）；503 catalog_unavailable。

这些响应中的代码就是生成连接时 geo 接受的值；目录之外的值返回 422 invalid_targeting。