# 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": "Повертає загальний і залишковий обсяг даних батьківського облікового запису для вказаного типу проксі, агрегований за замовленнями власника. На відміну від endpoint-ів субкористувача, тут показано дані власника облікового запису, а не субкористувача.",
  "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": "Тип проксі (standard | 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": "Тип проксі (standard | 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": "Тип проксі (standard | 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": "Тип проксі (standard | 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": "Тип проксі (standard | 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": "Тип проксі (standard | 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": "Тип проксі (standard | 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": "Тип проксі (standard | 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": "Тип проксі (standard | 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": "Тип проксі (standard | 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/proxies/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"
          }
        }
      }
    }
  }
}
```