account_divisions.md

Описание API загрузки подразделений

API предназначено для обновления иерархии подразделений.

Включает два метода: загрузка новой иерархии и метод для получения статуса выполнения задачи.

Метод для загрузки подразделений

POST /account/{account_id}/all_divisions

Метод принимает в теле запроса JSON со структурой подразделений.

JSON должен иметь следующий вид:

{
    "items": [
        {
            "name": "название подразделения",
            "foreign": "уникальный ключ подразделения",
            "meta": { ... структура с дополнительной информацией> },
            "items": [ ... список дочерних подразделений> ]
        },
        ...
    ]
}

Путь	Тип	Обязательный	Описание
name	string	Да	Название подразделения
foreign	string	Да	Уникальный идентификатор подразделения (как правило, это идентификатор подразделения во внутренней системе клиента)
meta	object	Нет	Произвольная структура с дополнительной информацией
items	array	Нет	Cписок с дочерними подразделениями

Ограничения

• foreign и name строки с ненулевой длиной.
• Максимальная вложенность подразделений - 5.
• foreign должны быть уникальными во всей передаваемой структуре данных. Если какое-то из этих условий нарушено, то сервер вернет ошибку валидации с HTTP статусом 400 (Bad request).
• нельзя создавать задания на обновление иерархии подразделений чаще одного раза в 20 минут (для одного и того же акаунта). Если будет произведена попытка обновления подразделений до истечения 20 минут с момента последнего успешного запроса, то сервер вернет ошибку с HTTP статусом 429.

Вызов метода создает фоновую задачу на обновление структуры подразделений и возвращает ее идентификатор.

Пример запроса

POST /account/3/all_divisions

{
    "items": [
        {
            "name": "Подразделение 1",
            "foreign": "d1",
            "meta": {
                "country": "RU",
                "comment": "some text"
            },
            "items": [
                {
                    "name": "Подразделение 1.1",
                    "foreign": "d1.1",
                    "meta": {
                        "country": "RU",
                        "comment": "some text"
                    }
                },
                {
                    "name": "Подразделение 1.2",
                    "foreign": "d1.2",
                    "meta": {
                        "country": "RU",
                        "comment": "some text"
                    }
                }
            ]
        },
        {
            "name": "Подразделение 2",
            "foreign": "d2",
            "meta": {
                "country": "RU",
                "comment": "some text"
            }
        }
    ]
}

Пример ответа

{
    "status": "ok",
    "meta": {
        "account_id": 3,
        "data": {
            "items": [
                {
                    "name": "Подразделение 1",
                    "foreign": "d1",
                    "meta": {
                        "country": "RU",
                        "comment": "some text"
                    },
                    "items": [
                        {
                            "name": "Подразделение 1.1",
                            "foreign": "d1.1",
                            "meta": {
                                "country": "RU",
                                "comment": "some text"
                            }
                        },
                        {
                            "name": "Подразделение 1.2",
                            "foreign": "d1.2",
                            "meta": {
                                "country": "RU",
                                "comment": "some text"
                            }
                        }
                    ]
                },
                {
                    "name": "Подразделение 2",
                    "foreign": "d2",
                    "meta": {
                        "country": "RU",
                        "comment": "some text"
                    }
                }
            ]
        }
    },
    "payload": {
      "task_id": "b5174006-b46f-49fd-a16b-6fc0baf69d5f"
    }
}

Если задание на обновление подразделений принято, то в ответе вернется payload.task_id – уникальный идентификатор задачи. Как отслеживать статус задачи.