Position

INFO

Каждый ответ приходит в общем конверте — code, message, messages, status_code, time — а полезная нагрузка лежит в data. Таблицы ниже описывают содержимое data.

GET /position/get-by-id/{id}

Get position using its _id

Параметры пути

Параметр	Тип	Обязательно	Описание
id	string	Да

Тело запроса

Тело запроса не требуется.

Ответ

Поле	Тип	Описание
_id	string
name	string
created_at	string
updated_at	string
is_deleted	boolean
completely_deleted	boolean
sections	object[]
sections[]._id	string
sections[].is_deleted	boolean
sections[].completely_deleted	boolean
sections[].name	string
organizations	object[]
organizations[]._id	string
organizations[].organization_id	string
organizations[].max_employee_count	number
organizations[].is_available	boolean

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": {
    "_id": "string",
    "name": "string",
    "created_at": "string",
    "updated_at": "string",
    "is_deleted": false,
    "completely_deleted": false,
    "sections": [
      {
        "_id": "string",
        "is_deleted": false,
        "completely_deleted": false,
        "name": "string"
      }
    ],
    "organizations": [
      {
        "_id": "string",
        "organization_id": "string",
        "max_employee_count": 0,
        "is_available": false
      }
    ]
  },
  "time": "2025-05-01T12:00:00Z"
}

POST /position/get-paging

Get positions by paging

Тело запроса

Поле	Тип	Обязательно	Описание
page	number	Да	По умолчанию: 1
limit	number	Да	По умолчанию: 20
search	string	Нет
section_id	string	Нет
organization_id	string	Нет
accessed_organization_ids	string[]	Нет

{
  "page": 1,
  "limit": 20,
  "search": "string",
  "section_id": "63f8b0c4e4b0d3a2f8e4b0c4",
  "organization_id": "63f8b0c4e4b0d3a2f8e4b0c4",
  "accessed_organization_ids": [
    "63f8b0c4e4b0d3a2f8e4b0c4"
  ]
}

Ответ

data.total — общее количество записей, data.data[] — записи текущей страницы. Таблица ниже описывает одну запись.

Поле	Тип	Описание
_id	string
name	string
created_at	string
updated_at	string
max_employee_count	number
employee_count	number

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": {
    "total": 0,
    "data": [
      {
        "_id": "string",
        "name": "string",
        "created_at": "string",
        "updated_at": "string",
        "max_employee_count": 0,
        "employee_count": 0
      }
    ]
  },
  "time": "2025-05-01T12:00:00Z"
}

POST /position/create

Create an HR position. name, section_ids (at least one existing section) and organizations (at least one entry) are required. Returns the created position aggregated with its sections. Fails with 400 if the name already exists in the account, or if a referenced section or organization does not exist.

Тело запроса

Поле	Тип	Обязательно	Описание
name	string	Да	Position name (required, 3–100 characters). Must be unique within the account.
section_ids	string[]	Да	Sections (departments) this position belongs to (required, at least one). Every id must reference an existing, non-deleted section.
organizations	object[]	Да	Per-organization availability of the position (required, at least one).
organizations[].organization_id	string	Да	Organization the position is opened in (required). Must exist.
organizations[].is_available	boolean	Да	Whether the position is currently open for hiring in this organization (required). A position whose every organization entry is is_available=false is auto soft-deleted by the backend.
organizations[].max_employee_count	number	Нет	Headcount cap for this organization. Defaults to 0 (uncapped) when omitted.

{
  "name": "Sales manager",
  "section_ids": [
    "63f8b0c4e4b0d3a2f8e4b0c4"
  ],
  "organizations": [
    {
      "organization_id": "63f8b0c4e4b0d3a2f8e4b0c4",
      "is_available": false,
      "max_employee_count": 0
    }
  ]
}

Ответ

Структура ответа совпадает с GET /position/get-by-id/{id}.

PUT /position/update/{id}

Update an HR position by ObjectId. name, section_ids and organizations are all required — this is a full replacement of those fields, not a patch. The organizations named in the payload are pulled and re-pushed; organizations not named keep their existing entry. Returns the updated position aggregated with its sections.

Параметры пути

Параметр	Тип	Обязательно	Описание
id	string	Да	Position ObjectId to update

Тело запроса

Поле	Тип	Обязательно	Описание
name	string	Да	Updated position name (required, 3–100 characters).
section_ids	string[]	Да	Sections (departments) this position belongs to (required, at least one). Every id must reference an existing, non-deleted section.
organizations	object[]	Да	Full replacement set of per-organization entries (required, at least one). The entries for the organizations named here are removed and re-added, so send every organization the position should remain open in — an organization left out keeps its previous entry untouched.
organizations[].organization_id	string	Да	Organization the position is opened in (required). Must exist.
organizations[].is_available	boolean	Да	Whether the position is currently open for hiring in this organization (required). A position whose every organization entry is is_available=false is auto soft-deleted by the backend.
organizations[].max_employee_count	number	Нет	Headcount cap for this organization. Defaults to 0 (uncapped) when omitted.

{
  "name": "Sales manager",
  "section_ids": [
    "63f8b0c4e4b0d3a2f8e4b0c4"
  ],
  "organizations": [
    {
      "organization_id": "63f8b0c4e4b0d3a2f8e4b0c4",
      "is_available": false,
      "max_employee_count": 0
    }
  ]
}

Ответ

Структура ответа совпадает с GET /position/get-by-id/{id}.

DELETE /position/delete/{id}

Soft-delete an HR position by ObjectId (sets is_deleted=true). Fails with 400 when at least one employee still holds the position — the error payload lists the blocking employees. Deleting an already-deleted position is a no-op.

Параметры пути

Параметр	Тип	Обязательно	Описание
id	string	Да	Position ObjectId to delete

Тело запроса

Тело запроса не требуется.

Ответ

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": "63f8b0c4e4b0d3a2f8e4b0c4",
  "time": "2025-05-01T12:00:00Z"
}

---

Эта страница сгенерирована из спецификации OpenAPI.