# Residential Proxies

Операции для резидентских прокси

## Купить дополнительный трафик (Residential)

`POST /user/api/orders/{id}/add-bandwidth`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Купить дополнительный трафик (Residential)",
  "parameters": [
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "integer"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AddBandwidthRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Успешно",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string",
                "example": "Order paid successfully"
              }
            },
            "required": [
              "success",
              "message"
            ]
          }
        }
      }
    }
  }
}
```

## Трафик владельца аккаунта

`GET /user/api/proxies/profile`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Трафик владельца аккаунта",
  "description": "Возвращает общие и оставшиеся данные родительского аккаунта для данного типа прокси, агрегированные по родительским заказам. В отличие от конечных точек субпользователя, здесь отражаются данные владельца учетной записи, а не субпользователя.",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Тип прокси (стандарт | премиум)",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Успех",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "type": "integer",
                "description": "Общее количество выделенных данных в байтах"
              },
              "data_remain": {
                "type": "integer",
                "description": "Оставшиеся данные в байтах"
              },
              "data_spent": {
                "type": "integer",
                "description": "Потребляемые данные в байтах"
              },
              "proxy_password": {
                "type": "string",
                "description": "Пароль прокси-сервера родительской учетной записи"
              }
            },
            "required": [
              "success",
              "data",
              "data_remain",
              "data_spent",
              "proxy_password"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Резидент пользователя не установлен/неверный тип прокси",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    },
    "401": {
      "description": "Требуется авторизация",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  }
}
```

## Список саб-пользователей

`GET /user/api/proxies/sub-users`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Список саб-пользователей",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Тип прокси (standart | premium)",
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "offset",
      "required": false,
      "schema": {
        "type": "integer"
      }
    },
    {
      "in": "query",
      "name": "limit",
      "required": false,
      "schema": {
        "type": "integer"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Успешно",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "count": {
                "type": "integer",
                "description": "Всего подпользователей до разбиения на страницы"
              },
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "user_id": {
                      "type": "string"
                    },
                    "first_name": {
                      "type": "string"
                    },
                    "proxy_password": {
                      "type": "string"
                    },
                    "data": {
                      "type": "integer"
                    },
                    "data_spent": {
                      "type": "integer"
                    },
                    "data_remain": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "user_id",
                    "first_name",
                    "proxy_password",
                    "data",
                    "data_spent",
                    "data_remain"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}
```

## Получить саб-пользователя по ID

`GET /user/api/proxies/sub-user/{user_id}`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Получить саб-пользователя по ID",
  "parameters": [
    {
      "in": "path",
      "name": "user_id",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Тип прокси (standart | premium)",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Успешно",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "first_name": {
                      "type": "string"
                    },
                    "proxy_password": {
                      "type": "string"
                    },
                    "data": {
                      "type": "integer"
                    },
                    "data_spent": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "first_name",
                    "proxy_password",
                    "data",
                    "data_spent"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}
```

## Удалить саб-пользователя

`DELETE /user/api/proxies/sub-user/{user_id}`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Удалить саб-пользователя",
  "parameters": [
    {
      "in": "path",
      "name": "user_id",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Успешно",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string",
                "example": "Sub user deleted successfully"
              }
            },
            "required": [
              "success",
              "message"
            ]
          }
        }
      }
    }
  }
}
```

## Редактировать саб-пользователя (имя/пакет)

`PATCH /user/api/proxies/sub-user/{user_id}`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Редактировать саб-пользователя (имя/пакет)",
  "parameters": [
    {
      "in": "path",
      "name": "user_id",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Тип прокси (standart | premium)",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/EditSubUserPayload"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Успешно",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string",
                "example": "Sub user edited successfully"
              }
            },
            "required": [
              "success",
              "message"
            ]
          }
        }
      }
    }
  }
}
```

## Создать саб-пользователя

`POST /user/api/proxies/sub-user`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Создать саб-пользователя",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Тип прокси (standart | premium)",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "data": {
              "type": "integer"
            }
          },
          "required": [
            "name",
            "data"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Успешно",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "user_id": {
                      "type": "string"
                    },
                    "first_name": {
                      "type": "string"
                    },
                    "proxy_password": {
                      "type": "string"
                    },
                    "data": {
                      "type": "integer"
                    },
                    "data_spent": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "user_id",
                    "first_name",
                    "proxy_password",
                    "data",
                    "data_spent"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}
```

## Добавить трафик саб-пользователю

`POST /user/api/proxies/sub-user/{user_id}/data/add`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Добавить трафик саб-пользователю",
  "parameters": [
    {
      "in": "path",
      "name": "user_id",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Тип прокси (standart | premium)",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "data": {
              "type": "integer",
              "description": "Объём в ГБ"
            }
          },
          "required": [
            "data"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Успешно",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string",
                "example": "Traffic added to sub user successfully"
              }
            },
            "required": [
              "success",
              "message"
            ]
          }
        }
      }
    }
  }
}
```

## Списать трафик у саб-пользователя

`POST /user/api/proxies/sub-user/{user_id}/data/subtract`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Списать трафик у саб-пользователя",
  "parameters": [
    {
      "in": "path",
      "name": "user_id",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Тип прокси (standart | premium)",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "data": {
              "type": "integer",
              "description": "Объём в ГБ"
            }
          },
          "required": [
            "data"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Успешно",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string",
                "example": "Traffic subtracted from sub user successfully"
              }
            },
            "required": [
              "success",
              "message"
            ]
          }
        }
      }
    }
  }
}
```

## Сменить пароль саб-пользователя

`POST /user/api/proxies/sub-user/{user_id}/password`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Сменить пароль саб-пользователя",
  "parameters": [
    {
      "in": "path",
      "name": "user_id",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Тип прокси (standart | premium)",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Успешно",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "message": {
                "type": "string",
                "example": "Sub user password changed successfully"
              }
            },
            "required": [
              "success",
              "message"
            ]
          }
        }
      }
    }
  }
}
```

## Список стран

`GET /user/api/proxies/countries`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Список стран",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Тип прокси (standart | premium)",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Успешно",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PagedCountriesResponse"
          }
        }
      }
    }
  }
}
```

## Список регионов

`GET /user/api/proxies/regions`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Список регионов",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Тип прокси (standart | premium)",
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "country_code",
      "required": true,
      "description": "ISO код страны",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Успешно",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PagedRegionsResponse"
          }
        }
      }
    }
  }
}
```

## Список городов

`GET /user/api/proxies/cities`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Список городов",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Тип прокси (standart | premium)",
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "country_code",
      "required": true,
      "description": "ISO код страны",
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "region_code",
      "required": true,
      "description": "Код региона (штата/провинции)",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Успешно",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PagedCitiesResponse"
          }
        }
      }
    }
  }
}
```

## Список интернет-провайдеров

`GET /user/api/proxies/isps`

```json
{
  "tags": [
    "Residential Proxies"
  ],
  "summary": "Список интернет-провайдеров",
  "description": "Интернет-провайдеры, доступные внутри города; четвертый уровень таргетинга после страны, региона и города. В отличие от других конечных точек местоположения, для этой требуется полная цепочка: `country_code`, `region_code` и `city_code` необходимы, поскольку вышестоящие интернет-провайдеры привязаны к городу. Только пакет «Премиум»: каталог интернет-провайдеров не поддерживается для стандартных и безлимитных пакетов, а любой другой `proxy_type` отклоняется с кодом 400. Интернет-провайдеры указаны только для крупных городов, поэтому пустой `results` с `count: 0` является нормальным ответом для меньшего города.",
  "parameters": [
    {
      "in": "query",
      "name": "proxy_type",
      "required": true,
      "description": "Должно быть `premium`; Таргетинг на интернет-провайдеров доступен только для премиум-класса.",
      "schema": {
        "type": "string",
        "enum": [
          "premium"
        ]
      }
    },
    {
      "in": "query",
      "name": "country_code",
      "required": true,
      "description": "Код страны ISO",
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "region_code",
      "required": true,
      "description": "Код региона или штата",
      "schema": {
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "city_code",
      "required": true,
      "description": "Код города из GET /user/api/proxy/cities.",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Успех",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PagedIspsResponse"
          }
        }
      }
    },
    "400": {
      "description": "proxy_type не `premium`, резидентность пользователя не установлена ​​или у пользователя нет активного заказа на пакет.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          },
          "examples": {
            "notPremium": {
              "value": {
                "success": false,
                "message": "ISP targeting is available for the premium package only"
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "Требуется авторизация",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      }
    }
  }
}
```