Учётная запись

Регистрация

POST /register - создаёт аккаунт организации

Обязательные заголовки:

Content-Type: application/json

Параметры запроса:

Параметр Формат Обязательность Описание
username string Да Системное имя пользователя (имя его учётной записи). В качестве учётной записи должна использоваться электронная почта пользователя.
password string Да Пароль
password2 string Да Повторение пароля

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

POST https://azdoc.online/api/register
Content-Type: application/json

{
    "username":"company@company.ru", 
    "password":"abc123", 
    "password2":"abc123"
}

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

{
    "status": "Success", 
    "message": "Registered successfully."
}

Теперь у нас есть аккаунт организации, в котором будут храниться необходимые документы. Пользователь данного аккаунта имеет роль admin. После создания аккаунта Вам на почту придёт письмо со ссылкой для подтверждения адреса e-mail, не забудьте перейти по ссылке, иначе, через 24 часа аккаунт будет заблокирован.

Самостоятельная регистрация

После создания основного аккаунта организации, можно добавлять пользователей с помощью АПИ POST /user. В случае же, если требуется разрешить пользователям самостоятельно регистрироваться с привязкой к данной организации (например, пользователям Вашего мобильного приложения), то необходимо разрешить это в настройках аккаунта, установив параметр allowSelfRegistration: true (подробнее об изменении настроек см. раздел Настройки).

При установленном параметре allowSelfRegistration: true, пользователь может зарегстрироваться указав id организации, к которой он присоединяется:

POST /register - создаёт аккаунт организации

Обязательные заголовки:

Content-Type: application/json

Параметры запроса:

Параметр Формат Обязательность Описание
username string Да Системное имя пользователя, его учётная запись.
password string Да Пароль
password2 string Да Повторение пароля
organizationId string Нет Идентификатор организации

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

POST https://azdoc.online/api/register
Content-Type: application/json

{
    "username":"company@company.ru", 
    "password":"abc123", 
    "password2":"abc123",
    "organizationId":"1dfece35-e353-467c-8984-54896648fa9d"
}

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

{
    "status": "Success", 
    "message": "Registered successfully."
}

Пользователь данного аккаунта имеет роль reader. После создания аккаунта Вам на почту придёт письмо со ссылкой для подтверждения адреса e-mail, не забудьте перейти по ссылке, иначе, через 24 часа аккаунт будет заблокирован.

Подтверждение e-mail

После создания аккаунта на почту, указанную в качестве username, придёт письмо со ссылкой для подтверждения адреса e-mail вот такого вида: https://azdoc.online/confirm/msCq5y1Qptvg91ssY6SDVa70itNaaMa5KQa9C9ao4BbwYDH0RP
Необходимо перейти по ссылке, чтобы подтвердить аккаунт, иначе, через 24 часа он будет заблокирован.

Смена пароля

POST /pass/change - изменяет текущий пароль на новый.

Обязательные заголовки:

Content-Type: application/json

Параметры запроса:

Параметр Формат Обязательность Описание
username string Да Системное имя пользователя, его учётная запись.
currentPassword string Да Текущий пароль
password string Да Новый пароль
password2 string Да Повторение нового пароля

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

POST https://azdoc.online/api/pass/change
Content-Type: application/json

{
    "username":"company@company.ru", 
    "currentPassword": "abc123"
    "password":"xyz123", 
    "password2":"xyz123"
}

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

{
    "status": "Success", 
    "message": "Changed successfully."
}

Восстановление пароля

Восстановление пароля осуществляется в 2 шага:


POST /code/send - высылает код сброса на e-mail

Обязательные заголовки:

Content-Type: application/json

Параметры запроса:

Параметр Формат Обязательность Описание
username string Да Системное имя пользователя, его учётная запись.

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

POST https://azdoc.online/api/code/send
Content-Type: application/json

{
    "username":"company@company.ru"
}

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

{
    "status": "Sent", 
}


POST /pass/set - устанавливает новый пароль.

Обязательные заголовки:

Content-Type: application/json

Параметры запроса:

Параметр Формат Обязательность Описание
username string Да Системное имя пользователя, его учётная запись (e-mail).
code string Да Код сброса, присланный на e-mail
password string Да Новый пароль
password2 string Да Повторение нового пароля

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

POST https://azdoc.online/api/pass/set
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

{
    "username":"company@company.ru", 
    "code": "351665"
    "password":"xyz123", 
    "password2":"xyz123"
}

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

{
    "status": "Success", 
    "message": "Password set successfully."
}

Аутентификация запросов

Для аутентификации запросов используются токены: Access Token для доступа и Refresh Token для периодического обновления Access Token. Для чего в системе нужны эти два токена можно почитать в статье на Хабре "Зачем нужен Refresh Token, если есть Access Token?"

Access Token указывается в заголовке Authorization после ключевого слова Bearer.

Пример запроса c Access Token:

POST https://azdoc.online/api/user/add
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

{
    "username":"company@company.ru", 
    "group":"reader"
}


Для получения пары Access Token - Refres Token необходимо осуществить вход в систему:

POST /login - вход в систему.

Обязательные заголовки:

Content-Type: application/json

Параметры запроса:

Параметр Формат Обязательность Описание
username string Да Системное имя пользователя, его учётная запись (e-mail).
password string Да Новый пароль

В ответ приходит JSON, содержащий следующие поля:

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

POST https://azdoc.online/api/login
Content-Type: application/json

{
    "username":"company@company.ru", 
    "password":"xyz123"
}

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

{
    "access_token": "FnxFbhGRuBdGx7yYVYxatzd72O0nMfXugf2PazKv0RLll9OaAZ",
    "expires_on": 1623220341259,
    "refresh_token": "d1E71Ow8SmVVBadV1b89vlkioupjMPHrXflyGM8QpeeDDfRixV"
}


После истечения времени жизни Access Token, его необходимо обновить:

POST /token/refresh - обновление Access Token. При вызове этого АПИ до истечения срока жизни Access Token, текущий Access Token уничтожается.

Обязательные заголовки:

Content-Type: application/json

Параметры запроса:

Параметр Формат Обязательность Описание
refresh_token string Да Refresh Token, выданный ранее

В ответ приходит JSON, аналогичный получаемому в ответ на POST /login и содержащий следующие поля:

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

POST https://azdoc.online/api/token/refresh
Content-Type: application/json

{
    "refresh_token":"d1E71Ow8SmVVBadV1b89vlkioupjMPHrXflyGM8QpeeDDfRixV"
}

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

{
    "access_token": "FnxFbhGRuBdGx7yYVYxatzd72O0nMfXugf2PazKv0RLll9OaAZ",
    "expires_on": 1623220341259,
    "refresh_token": "d1E71Ow8SmVVBadV1b89vlkioupjMPHrXflyGM8QpeeDDfRixV"
}

Пользователи

Создание пользователя

POST /user - добавляет нового пользователя. Для добавления пользователей нужно обладать правами уровня admin.

Обязательные заголовки:

Content-Type: application/json
Authorization: Bearer <Token>

Параметры запроса:

Параметр Формат Обязательность Описание
username string Да Системное имя пользователя, его учётная запись (e-mail).
group string Нет Группа с уровнем доступа. Может иметь значения admin, author, reader. Значение по умолчанию - reader. Admin имеет права доступа ко всем АПИ. Author - права на все АПИ для работы с папками и документами. Reader - права на АПИ для получения (чтения) документов и папок. Все группы пользователей имеют доступ к АПИ авторизации и АПИ смены и воостановления пароля.

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

POST https://azdoc.online/api/user
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

{
    "username":"new.user@company.ru", 
    "group":"admin"
}

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

{
    "status": "Success",
    "message": "Created successfully.",
    "id": "447e6810-5047-47c5-b4dc-740132ede06c"
}

Получение пользователя

GET /user/{id} - чтение данных пользователя. Для использования данного АПИ нужно обладать правами уровня admin. Чтобы получить данные о собственном аккаунте используется АПИ GET /profile, который доступен всем авторизованным пользователям.

Обязательные заголовки:

Authorization: Bearer <Token>

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

GET https://azdoc.online/api/user/447e6810-5047-47c5-b4dc-740132ede06c
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

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

{
    "id": "447e6810-5047-47c5-b4dc-740132ede06c",
    "email": "ivan.pavlov@company.ru",
    "firstName": "Ivan",
    "lastName": "Pavlov",
    "group": "admin",
    "active": true
}

Получение списка пользователей

GET /user/list - получение списка пользователей. Для использования данного АПИ нужно обладать правами уровня admin.

Обязательные заголовки:

Authorization: Bearer <Token>

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

GET https://azdoc.online/api/user/list
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

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

[
    {
        "id": "85f1e232-9825-4fd4-b272-5f28cd20f186",
        "email": "super.user@company.ru",
        "firstName": "Иван",
        "lastName": "Павлов",
        "group": "admin",
        "active": true
    },
    {
        "id": "ffe8df10-06cd-43b1-95da-739fa806a9d4",
        "email": "second.user@company.ru",
        "firstName": "Александр",
        "lastName": "Попов",
        "group": "author",
        "active": true
    },
    {
        "id": "447e6810-5047-47c5-b4dc-740132ede06c",
        "email": "new.user@company.ru",
        "firstName": "Дмитрий",
        "lastName": "Менделеев",
        "group": "reader",
        "active": true
    }
]

Редактирование пользователя

PUT /user - редактирование пользователя. Для использования данного АПИ нужно обладать правами уровня admin.

Обязательные заголовки:

Content-Type: application/json
Authorization: Bearer <Token>

Параметры запроса:

Параметр Формат Обязательность Описание
id string Да Идентификатор пользователя
username string Нет Системное имя пользователя, его учётная запись (e-mail).
firstName string Нет Имя пользователя.
lastName string Нет Фамилия пользователя.
group string Нет Группа с уровнем доступа
active boolean Нет Статус пользователя: активный или деактивированный

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

PATCH https://azdoc.online/api/user
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

{
    "id": "447e6810-5047-47c5-b4dc-740132ede06c",
    "username":"new.user@company.ru", 
    "group":"author"
}

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

{
    "status": "Success",
    "message": "Updated successfully.",
    "id": "1a9b5d60-2a84-4edc-8751-ce0d28f153b6"
}

Удаление пользователя

DELETE /user - полное удаление данных пользователя из БД, восстановление данных невозмжно. Для деактивации пользователя с сохранением данных используется АПИ PATCH /user. Для использования данного АПИ нужно обладать правами уровня admin.

Обязательные заголовки:

Content-Type: application/json
Authorization: Bearer <Token>

Параметры запроса:

Параметр Формат Обязательность Описание
id string Да Идентификатор пользователя

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

DELETE https://azdoc.online/api/user
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

{
    "id": "447e6810-5047-47c5-b4dc-740132ede06c",
}

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

{
    "status": "Success",
    "message": "Deleted successfully."
}

Папки

Создание папки

POST /folder - добавляет новую папку. Для использования данного АПИ нужно обладать правами уровня author.

Обязательные заголовки:

Content-Type: application/json
Authorization: Bearer <Token>

Параметры запроса:

Параметр Формат Обязательность Описание
name string Да Имя папки
order integer Нет Порядковый номер папки. Нумерация начинается с нуля. При получении списка папок они будут отсортированы по порядку. Нумерация под-папок внутри каждой папки своя, начинается с нуля.
parentId string Нет Идентификатор родительской папки, если не указан, то папка создаётся в корне.

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

POST https://azdoc.online/api/folder
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

{
    "name": "Folder name", 
    "order": "1", 
    "parentId": "iewoiojwe-kmslkglrk-j989f8wu9uf"
}

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

{
    "status": "Success",
    "message": "Created successfully.",
    "id": "a8d90a7a-5533-45d0-9fdc-47e5fbd8156a"
}

Получение списка папок

GET /folder/list - получение списка папок. Для использования данного АПИ нужно обладать правами уровня reader.

Обязательные заголовки:

Authorization: Bearer <Token>

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

GET https://azdoc.online/api/folder/list
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

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

[
    {
        "id": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5",
        "name": "Отдел ИТ",
        "order": 0,
        "parentId": null,
        "children": [
            {
                "id": "347b7fe2-0eab-40c5-b1c1-06f73fdeccad",
                "name": "Документация",
                "order": 0,
                "parentId": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5"
            },
            {
                "id": "d8f614ac-b74c-4da9-9be3-a0facbd23a6f",
                "name": "Список сотрудников",
                "order": 1,
                "parentId": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5"
            }
        ]
    },
    {
        "id": "f3386450-ed39-47fe-a0ea-05f876dc817b",
        "name": "Отдел маркетинга",
        "order": 2,
        "parentId": null
    },
    {
        "id": "a8d90a7a-5533-45d0-9fdc-47e5fbd8156a",
        "name": "folder name",
        "order": 1,
        "parentId": null
    }
]

Редактирование папки

PATCH /folder - редактирование папки. Для использования данного АПИ нужно обладать правами уровня author.

Обязательные заголовки:

Content-Type: application/json
Authorization: Bearer <Token>

Параметры запроса:

Параметр Формат Обязательность Описание
id string Да Идентификатор папки
name string Нет Имя папки
parentId string Нет Идентификатор родительской папки. Для перемещения под-папки в корневой раздел необходимо явно задать параметр равным пустой строке "parentId":""
order integer Нет Порядковый номер папки. Нужно указать желаемый порядковый номер папки внутри подпапки (или в корне, если это корневая папка). Порядковые номера остальных папок будут пересчитаны автоматически.
active string Нет Статус папки: активная или деактивированная.

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

PATCH https://azdoc.online/api/folder
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

{
    "id": "a8d90a7a-5533-45d0-9fdc-47e5fbd8156a",
    "name": "Folder name edited", 
    "order": "0", 
    "parentId": "e5ab2ojwe-kae9kglrw-g434f8wu7qa"
}

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

{
    "status": "Success",
    "message": "Updated successfully."
}

Удаление папки

DELETE /folder - полное удаление папки и её содержимого из БД. Для деактивации папки с сохранением данных в БД используется АПИ PATCH /folder. Для использования данного АПИ нужно обладать правами уровня author.

Обязательные заголовки:

Content-Type: application/json
Authorization: Bearer <Token>

Параметры запроса:

Параметр Формат Обязательность Описание
id string Да Идентификатор папки
deleteDescendents boolean Нет Требуется ли удалить папку включая все подпапки. Если папка имеет вложенные подпапки, то её удаление возможно только при установке данного параметра в true.

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

DELETE https://azdoc.online/api/folder
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

{
    "id": "a8d90a7a-5533-45d0-9fdc-47e5fbd8156a",
    "deleteDescendents":true
}

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

{
    "status": "Success",
    "message": "Deleted successfully."
}

Документы

Создание документа

POST /doc - добавляет новый документ. Для использования данного АПИ нужно обладать правами уровня author.

Обязательные заголовки:

Content-Type: application/json
Authorization: Bearer <Token>

Параметры запроса:

Параметр Формат Обязательность Описание
title string Да Заголовок документа
order integer Нет Порядковый номер документа. Нумерация начинается с нуля. При получении списка документов они будут отсортированы по порядку. Нумерация документов внутри каждой папки своя, начинается с нуля.
active boolean Нет Доступность документа: активный (доступный для просмотра и редактирования) или деактивированный.
folderId string Да Идентификатор родительской папки. Документы можно создавать только внутри папок.
status integer Нет Статус документа: 0 - черновик, 1 - опубликован. Значение по умолчанию - 0.
isPublic boolean Нет Является ли документ публичным (можно ли получить к нему доступ без авторизации). Значение по умолчанию - false.
type string Да Тип документа: json, html и т.д.
body string Да Тело документа

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

POST https://azdoc.online/api/doc
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

{
    "title": "Doc title", 
    "order": "1", 
    "folderId": "iewoiojwe-kmslkglrk-j989f8wu9uf",
    "status":0,

}

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

{
    "status": "Success",
    "message": "Created successfully.",
    "id": "d476b3e3-cb3b-4ec7-a948-35580baeb7eb"
}

Получение документа

GET /doc/{id} - получение документа с идентификатором {id}. Возвращает последнюю версию документа (о версиях см. ниже). Для использования данного АПИ нужно обладать правами уровня reader.

Обязательные заголовки:

Authorization: Bearer <Token>

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

GET https://azdoc.online/api/doc/f7a817af-2b50-404e-a63f-771ee31be27a
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

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

{
    "id": "f7a817af-2b50-404e-a63f-771ee31be27a",
    "title": "Оферта для пользователей",
    "order": 0,
    "folderId": "f3386450-ed39-47fe-a0ea-05f876dc817b",
    "status": 1,
    "type": "html",
    "body": "текст оферты"
}

Версии документа

GET /doc/{id}/version - получение списка версий документа. При каждом обновлении документа с помощью АПИ /doc/edit сохраняется новая версия документа. Это позволяет, при необходимости, вернуться к ранним версиям документа. Для использования данного АПИ нужно обладать правами уровня reader.

Обязательные заголовки:

Authorization: Bearer <Token>

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

GET https://azdoc.online/api/doc/f7a817af-2b50-404e-a63f-771ee31be27a/version
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

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

[
    {
        "version": 1,
        "status": 0,
        "createdAt": "2021-05-18T18:53:58.879Z",
        "type": "text/plain"
    },
    {
        "version": 2,
        "status": 1,
        "createdAt": "2021-05-18T19:11:54.474Z",
        "type": "text/plain"
    },
    {
        "version": 3,
        "status": 1,
        "createdAt": "2021-05-18T19:28:03.404Z",
        "type": "text/plain"
    },
    {
        "version": 4,
        "status": 1,
        "createdAt": "2021-05-18T19:30:02.735Z",
        "type": "text/plain"
    }
]


GET /doc/{id}/version/{number} - получение конкретной версии документа. Для использования данного АПИ нужно обладать правами уровня reader.

Обязательные заголовки:

Authorization: Bearer <Token>

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

GET https://azdoc.online/api/doc/f7a817af-2b50-404e-a63f-771ee31be27a/version/3
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

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

{
    "version": 3,
    "status": 1,
    "createdAt": "2021-05-18T19:28:03.404Z",
    "type": "text/html",
    "body": "Третья редакция текста оферты"
}

Получение документа по статусу

GET /doc/{id}/status/{status} - получение документа с идентификатором {id} и статусом {status} (может иметь значения 0 или 1). Возвращает последнюю версию документа в указанном статусе. Можно использовать для получения последней опубликованной версии, при наличии более поздних версий в статусе "черновик". Для использования данного АПИ нужно обладать правами уровня reader.

Обязательные заголовки:

Authorization: Bearer <Token>

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

GET https://azdoc.online/api/doc/f7a817af-2b50-404e-a63f-771ee31be27a/status/1
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

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

{
    "id": "f7a817af-2b50-404e-a63f-771ee31be27a",
    "title": "Оферта для пользователей",
    "order": 0,
    "folderId": "f3386450-ed39-47fe-a0ea-05f876dc817b",
    "status": 1,
    "type": "html",
    "body": "текст оферты"
}

Получение списка документов

GET /doc/list - получение списка всех документов. Для использования данного АПИ нужно обладать правами уровня reader.

Обязательные заголовки:

Authorization: Bearer <Token>

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

GET https://azdoc.online/api/doc/list
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

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

[
    {
        "id": "f7a817af-2b50-404e-a63f-771ee31be27a",
        "title": "Оферта для пользователей",
        "order": 0,
        "active": true,
        "folderId": "f3386450-ed39-47fe-a0ea-05f876dc817b"
    },
    {
        "id": "a9506e6f-b519-4768-a1c1-4ed01f5c3282",
        "title": "Описание структуры отдела",
        "order": 1,
        "active": true,
        "FolderId": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5"
    },
    {
        "id": "9ebd51b0-d05b-44d9-bbae-8d9c9333218b",
        "title": "Описание структуры отдела",
        "order": 0,
        "active": true,
        "FolderId": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5"
    }
]

Редактирование документа

PATCH /doc - редактирование документа. Для использования данного АПИ нужно обладать правами уровня author.

Обязательные заголовки:

Content-Type: application/json
Authorization: Bearer <Token>

Параметры запроса:

Параметр Формат Обязательность Описание
id string Да Идентификатор папки
title string Нет Заголовок документа
folderId string Нет Идентификатор родительской папки.
order integer Нет Порядковый номер документа. Нужно указать желаемый порядковый номер папки внутри подпапки. Порядковые номера остальных документов будут пересчитаны автоматически.
active string Нет Статус документа: активнаый или деактивированный.
status integer Нет Статус документа: 0 - черновик, 1 - опубликован. Значение по умолчанию - 0.
type string Нет Тип документа: json, html и т.д.
body string Нет Тело документа

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

PATCH https://azdoc.online/api/doc
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

{
    "id": "f7a817af-2b50-404e-a63f-771ee31be27a",
    "title": "Новый заголовок", 
    "body": "Новое тело документа"
}

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

{
    "status": "Success",
    "message": "Updated successfully."
}

Удаление документа

DELETE /doc - полное удаление документа из БД. Для деактивации документа с сохранением данных в БД используется АПИ PATCH /doc. Для использования данного АПИ нужно обладать правами уровня author.

Обязательные заголовки:

Content-Type: application/json
Authorization: Bearer <Token>

Параметры запроса:

Параметр Формат Обязательность Описание
id string Да Идентификатор документа

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

DELETE https://azdoc.online/api/doc
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

{
    "id": "f7a817af-2b50-404e-a63f-771ee31be27a"
}

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

{
    "status": "Success",
    "message": "Deleted successfully."
}

Получение контента

GET /content/doc/{id} - метод возвращает контент документа (body), в отличии от метода GET /doc/{id}, который возвращает json со всеми данными документа. Заголовок Content-Type, при этом, равен полю type. В ответе присылается старшая версия документа в статусе "чистовик" (status=1). Если у документа нет "чистовых" версий, то в ответе будет ошибка 404 Not Found с описанием "No published version found". Если в настройках определены стадии публикации, то в ответе будет приходить контент старшей "чистовой" версии (status=1) опубликованной на стадии с максимльным Порядком (order). Если на стадии с максимальным Порядком нет версий докумета в статусе "чистовик", либо нет чистовиков, которые согласованы и опубликованы, то в ответе будет ошибка 404 Not Found.

Обязательные заголовки:

Authorization: Bearer <Token>

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

GET https://azdoc.online/api/content/doc/f7a817af-2b50-404e-a63f-771ee31be27a

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

Третья редакция текста оферты

Получение контента на указанной стадии

GET /content/doc/{id}/stage/{name} - метод аналогичен методу GET /content/doc/{id}, с той разницей, что возвращает контент для конкретной стадии публикации, а не для стадии с максимальным порядком. Данный метод используется для отображения документа на выбранной среде (dev, stage, prod). Подробнее об этом рассказано в примере.

Обязательные заголовки:

Authorization: Bearer <Token>

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

GET https://azdoc.online/api/content/doc/f7a817af-2b50-404e-a63f-771ee31be27a/stage/Dev

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

Третья редакция текста оферты

Публичный доступ к документу

GET /public/doc/{id} - если у документа установлено свойство isPublic равное true, то при добавлении /public в URL path к документу, его можно будет получить без авторизации. В остальном его работа аналогична методу GET /content/doc/{id}

Обязательные заголовки:

Отсутствуют.

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

GET https://azdoc.online/api/public/doc/f7a817af-2b50-404e-a63f-771ee31be27a

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

Третья редакция текста оферты

Отправка на публикацию

PUT /doc/{id}/version/{number}/status/1 - отправка указанной версии документа на публикацию. Для использования данного АПИ нужно обладать правами уровня author. Если в настройках не определены стадии публикации, то документ сразу становится доступным по ссылке GET /doc/{id}/content. Если стадии публикации определены в настройках, то для каждой стадии необходимо пройти процесс согласования и публикации, после чего документ становится доступен по ссылке GET /doc/{id}/content/stage/{stageName}. Подробнее о стадиях - тут

Обязательные заголовки:

Authorization: Bearer <Token>

Параметры запроса:

Параметр Формат Обязательность Описание
id string Да Номер версии документа
number integer Да Идентификатор документа

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

PUT https://azdoc.online/api/doc/d5f7e857-6bd2-421f-857d-7cbaa42a36c6/version/1/status/1
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

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

{
    "status":"Success",
    "message":"Updated successfully.",
    "id":"d5f7e857-6bd2-421f-857d-7cbaa42a36c6"
}

Согласование публикации

POST /doc/approval - согласование публикации указанной версии документа. Для согласования пользователь должен быть указан в качестве согласующего в настройках стадии публикации.

Обязательные заголовки:

Content-Type: application/json
Authorization: Bearer <Token>

Параметры запроса:

Параметр Формат Обязательность Описание
documentId string Да Идентификатор документа.
version integer Да Версия документа, публикацию которой мы согласовываем.
stageId string Да Идентификатор стадии публикации.

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

POST https://azdoc.online/api/doc/approval
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

{
    "documentId":"c6d198f8-4c1b-4926-a0e7-eaad27d3e869",
    "version":12,
    "stageId":"aa977885-7a2f-4b54-b046-8c3353e400a7"
}

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

{
    "status": "Success",
    "message": "Approved successfully."
}

Отмена согласования публикации

DELETE /doc/approval - отмена согласования публикации. Права на отмену согласования есть у пользователя, который поставил согласование, и у админа. Отменить согласование возможно только до момента публикации документа. Чтобы отменить согласование уже опубликованного документа, необходимо сначала отменить публикацию.

Обязательные заголовки:

Content-Type: application/json
Authorization: Bearer <Token>

Параметры запроса:

Параметр Формат Обязательность Описание
id string Да Идентификатор согласования.

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

DELETE https://azdoc.online/api/doc/approval
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

{
    "id":"330e1449-8eb7-4691-8556-1484cad9059b"
}

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

{
    "status": "Success",
    "message": "Approval has been cancelled successfully."
}

Получение списка согласований для указанной версии

GET /doc/{id}/version/{number}/approval - получение списка согласований для указанной версии. Для использования данного АПИ нужно обладать правами уровня author.

Обязательные заголовки:

Content-Type: application/json
Authorization: Bearer <Token>

Параметры запроса:

Параметр Формат Обязательность Описание
id string Да Идентификатор документа.
number integer Да Номер версии документа.

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

GET https://azdoc.online/doc/1cac7c0b-5501-4ae9-8dad-830f6612452f/version/20/approval
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

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

[
        {
            "approvalId": "5ac7c452-8aa2-42b2-9ddc-d51b0867dee9",
            "approvedAt": "2020-04-16T19:42:42.934Z",
            "userId": "b850a4cc-071d-4b6a-9692-caec0db28429",
            "userFirstName": "Иван",
            "userLastName": "Павлов",
            "publishStage": {
                "id":"aa977885-7a2f-4b54-b046-8c3353e400a7",
                "name":"Dev",
                "order":1,
                "autoPublish":false
            }
        },
        {
            "approvalId": "7b725389-fdc4-483d-8046-83ef79da7d61",
            "approvedAt": "2020-04-17T08:32:11.459Z",
            "userId": "451ca4c0-88bd-4a8d-523e-abc2a9928783",
            "userFirstName": "Дмитрий",
            "userLastName": "Менделеев",
            "publishStage": {
                "id":"aa977885-7a2f-4b54-b046-8c3353e400a7",
                "name":"Dev",
                "order":1,
                "autoPublish":false
            }
        }
]

Публикация

POST /doc/approval - публикация указанной версии документа. Для публикации пользователь должен быть указан в качестве публикующего в настройках стадии публикации. Для публикации версия должна быть предварителльно согласована, в противном случае, АПИ вернёт ошибку.

Обязательные заголовки:

Content-Type: application/json
Authorization: Bearer <Token>

Параметры запроса:

Параметр Формат Обязательность Описание
documentId string Да Идентификатор документа.
version integer Да Версия документа, которую мы публикуем.
stageId string Да Идентификатор стадии публикации.

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

POST https://azdoc.online/api/doc/publication
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

{
    "documentId":"c6d198f8-4c1b-4926-a0e7-eaad27d3e869",
    "version":12,
    "stageId":"aa977885-7a2f-4b54-b046-8c3353e400a7"
}

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

{
    "status": "Success",
    "message": "Published successfully."
}

Отмена публикации

DELETE /doc/publication - отмена публикации. Права на отмену публикации есть у пользователя, который опубликовал, и у админа.

Обязательные заголовки:

Content-Type: application/json
Authorization: Bearer <Token>

Параметры запроса:

Параметр Формат Обязательность Описание
id string Да Идентификатор публикации.

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

DELETE https://azdoc.online/api/doc/publication
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

{
    "id":"330e1449-8eb7-4691-8556-1484cad9059b"
}

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

{
    "status": "Success",
    "message": "Publication has been cancelled successfully."
}

Получение списка публикаций для указанной версии

GET /doc/{id}/version/{number}/publication - получение списка публикаций для указанной версии. Для использования данного АПИ нужно обладать правами уровня author.

Обязательные заголовки:

Content-Type: application/json
Authorization: Bearer <Token>

Параметры запроса:

Параметр Формат Обязательность Описание
id string Да Идентификатор документа.
number integer Да Номер версии документа.

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

GET https://azdoc.online/doc/1cac7c0b-5501-4ae9-8dad-830f6612452f/version/20/publication
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

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

[
        {
            "publicationId": "aa71dbd9-1609-4ff4-a097-40222933b9cf",
            "publishedAt": "2020-04-16T20:14:12.723Z",
            "userId": "b850a4cc-071d-4b6a-9692-caec0db28429",
            "userFirstName": "Иван",
            "userLastName": "Павлов",
            "publishStage": {
                "id":"aa977885-7a2f-4b54-b046-8c3353e400a7",
                "name":"Dev",
                "order":1,
                "autoPublish":false
            }
        },
        {
            "publicationId":"5a7b0c34-c776-4283-a6a7-c9d8dca6dbfa",
            "publishedAt": "2020-04-20T12:45:51.309Z",
            "userId": "451ca4c0-88bd-4a8d-523e-abc2a9928783",
            "userFirstName": "Дмитрий",
            "userLastName": "Менделеев",
            "publishStage": {
                "id":"aa977885-7a2f-4b54-b046-8c3353e400a7",
                "name":"Stage",
                "order":2,
                "autoPublish":false
            }
        }
]

Настройки

Получение настроек

GET /setting/list - получение списка настроек текущего аккаунта организации. Для использования данного АПИ нужно обладать правами уровня admin.

Обязательные заголовки:

Authorization: Bearer <Token>

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

GET https://azdoc.online/api/setting/list
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

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

[
        {
            "id":"allowSelfRegistration",
            "title":"Самостоятельная регистация"
        },
        {
            "id":"publishStage",
            "title":"Настройки согласования и публикации"
        }
    ]

Получение настроек самостоятельной регистрации

GET /setting/allowSelfRegistration - получение настроек самостоятельной регистрации. Для использования данного АПИ нужно обладать правами уровня admin.

Обязательные заголовки:

Authorization: Bearer <Token>

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

GET https://azdoc.online/api/setting/allowSelfRegistration
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

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

{
    "organizationId": "1dfece35-e353-467c-8984-54896648fa9d", 
    "allowSelfRegistration": true,
    "id": "allowSelfRegistration"
}

Параметры ответа:

Параметр Формат Обязательность Описание
organizationId string Да Идентификатор организации
allowSelfRegistration boolean Да Разрешена ли самостоятельная регистрация пользователей. При создании аккаунта организации, значение по умолчанию - false.
id string Да Идентификатор настройки. Является человекопонимаемой строкой.

Изменение настроек самостоятельной регистрации

PUT /setting/allowSelfRegistration - изменение настроек самостоятельной регистрации. Для использования данного АПИ нужно обладать правами уровня admin.

Обязательные заголовки:

Content-Type: application/json
Authorization: Bearer <Token>

Параметры запроса:

Параметр Формат Обязательность Описание
allowSelfRegistration boolean Да Разрешена ли самостоятельная регистрация пользователей. При создании аккаунта организации, значение по умолчанию - false.

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

PUT https://azdoc.online/api/setting/allowSelfRegistration
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

{
    "allowSelfRegistration": true
}

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

{
    "status": "Success", 
    "message": "Updated successfully.",
    "id": "allowSelfRegistration"
}

Стадии публикации. Введение.

Стадии публикации определяют этапы (стадии) через которые проходит документ прежде чем он оказывается опубликованным на боевом сервере. Изначально никаких стадий в настройках организации не определено. Это значит, что документ после публикации может сразу быть доступен на боевом сервере.

Публикация - это изменение статуса документа (точнее, определённой версии документа) с черновика (status=0) на опубликованный (status=1). Если никаких стадий публикации в настройках не определено, то данная версия сразу после изменения статуса становится доступна через АПИ GET /doc/{id}/content. При этом, в ответе приходит не json с мета данными о документе, а сам документ (контент) с заголовком Content-type, равным значению, указанному в поле type при создании/редактировании документа.

Этот АПИ можно использовать в сторонней системе, чтобы отобразить документ конечному пользователю. Например, по этой ссылке можно отобразить Пользовательское соглашение. Пока документ редактируется, новые версии создаются с статусе "черновик", если какую-то версию (необязательно последнюю) переввести в статус "опубликовано", то она становится доступна через АПИ GET /doc/{id}/content. АПИ возвращает самую большую из опубликованных версий.

Если нам необходимо, чтобы документ перед тем, как стать доступным в АПИ, был согласован кем-то из сотрудников, то мы создаём стадию. Для стадии можно определить несколько согласующих. Только после того, как все согласующие согласуют документ, он может быть опубликован. Для публикации можно также назначить сотрудника, либо указать, что публикация происходит автоматически, после получения всех согласований. При наличии стадии документ проходит следующие этапы:

После публикации документ становится доступен по АПИ GET /doc/{id}/content/stage/{stageName}, при этом АПИ GET /doc/{id}/content будет возвращать ошибку "Необходимо указать стадию".

Если нам необходимо иметь возможность раздельной публикации документа на нескольких серверах, например, нужно проверять документ на тестовом сервере, прежде чем публиковать на боевом, то необходимо определить несколько стадий. Например, test и prod. У каждой стадии будут назначены свои согласующие и свои публикующие сотрудники. В этом случае, документ будет проходить следующие этапы:

На серверах test и prod формат ссылки определяется в конфиге.

Таким образом, процесс для сотрудников может выглядеть так:

Количество стадий не ограничено.

Создание стадии публикации

POST /setting/publishStage - cоздание стадии публикации. Для использования данного АПИ нужно обладать правами уровня admin.

Обязательные заголовки:

Authorization: Bearer <Token>

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

POST https://azdoc.online/api/setting/publishStage
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

{
    "name":"test",
    "order":"1",
    "approvers":[
        {"userId":"fa312064-2af5-4d3b-9961-a3bd235ebdf8"},
        {"userId":"fa312064-2af5-4d3b-9961-a3bd235ebdf8"}
    ],
    "publishers":[
        {"userId":"b850a4cc-071d-4b6a-9692-caec0db28429"}
    ]
}

Параметры запроса:

Параметр Формат Обязательность Описание
name string Да Название стадии.
order integer Да Порядок следования стадий.
approvers array Нет Список согласующих. Список представляет из себя массив объектов, в каждом объекте - id пользователя.
publishers array Нет Список публикующих. Список представляет из себя массив объектов, в каждом объекте - id пользователя.
autoPublish boolean Нет Автоматическая публикация. Документ автоматически публикуется сразу после получения всех согласований.

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

{
    "status": "Success",
    "message": "Added successfully.",
    "id": "7b725389-fdc4-483d-8046-83ef79da7d61"
}

Редактирование стадии публикации

PUT /setting/publishStage/{id} - редактирование стадии публикации. Для использования данного АПИ нужно обладать правами уровня admin.

Обязательные заголовки:

Authorization: Bearer <Token>

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

PUT https://azdoc.online/api/setting/publishStage/35d8b3c7-edd3-4adf-9043-bc9693e77d44
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

{
    "name":"test",
    "order":"1",
    "approvers":[
        {"userId":"fa312064-2af5-4d3b-9961-a3bd235ebdf8"},
        {"userId":"fa312064-2af5-4d3b-9961-a3bd235ebdf8"}
    ],
    "publishers":[],
    "autoPublish": true
}

Параметры запроса:

Параметр Формат Обязательность Описание
name string Да Название стадии.
order integer Да Порядок следования стадий.
approvers array Нет Список согласующих. Список представляет из себя массив объектов, в каждом объекте - id пользователя.
publishers array Нет Список публикующих. Список представляет из себя массив объектов, в каждом объекте - id пользователя.
autoPublish boolean Нет Автоматическая публикация. Документ автоматически публикуется сразу после получения всех согласований.

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

{
    "status": "Success",
    "message": "Updated successfully.",
    "id": "35d8b3c7-edd3-4adf-9043-bc9693e77d44"
}

Получение списка стадий публикации

GET /setting/publishStage/ - получение списка стадий публикации. Для использования данного АПИ нужно обладать правами уровня admin.

Обязательные заголовки:

Authorization: Bearer <Token>

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

GET https://azdoc.online/api/setting/publishStage/
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

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


[
    {
        "id": "35d8b3c7-edd3-4adf-9043-bc9693e77d44",
        "name": "Test",
        "order": "1",
        "approvers": [
            {
                "id": "fa312064-2af5-4d3b-9961-a3bd235ebdf8",
                "email": "alexander.popov@company.ru",
                "firstName": "Alexander",
                "lastName": "Popov"
            },
            {
                "id": "fa312064-2af5-4d3b-9961-a3bd235ebdf8",
                "email": "ivan.pavlov@company.ru",
                "firstName": "Ivan",
                "lastName": "Pavlov"
            }
        ],
        "publishers": [],
        "autoPublish": true
    },
    {
        "id": "b98dc36d-1d8f-4bac-8c1f-8c6087dc1929",
        "name":"Prod",
        "order":"2",
        "approvers":[
            {
                "id": "fa312064-2af5-4d3b-9961-a3bd235ebdf8",
                "email": "alexander.popov@company.ru",
                "firstName": "Alexander",
                "lastName": "Popov"
            },
            {
                "id": "fa312064-2af5-4d3b-9961-a3bd235ebdf8",
                "email": "ivan.pavlov@company.ru",
                "firstName": "Ivan",
                "lastName": "Pavlov"
            }
        ],
        "publishers":[
            {
                "id": "fa312064-2af5-4d3b-9961-a3bd235ebdf8",
                "email": "ivan.pavlov@company.ru",
                "firstName": "Ivan",
                "lastName": "Pavlov"
            }
        ],
    }
]

Параметры ответа:

Параметр Формат Обязательность Описание
name string Да Название стадии.
order integer Да Порядок следования стадий.
approvers array Нет Список согласующих. Список представляет из себя массив объектов, в каждом объекте - id пользователя, email, имя и фамилия согласующего.
publishers array Нет Список публикующих. Список представляет из себя массив объектов, в каждом объекте - id пользователя, email, имя и фамилия согласующего.
autoPublish boolean Нет Автоматическая публикация. Документ автоматически публикуется сразу после получения всех согласований.

Получение стадии публикации

GET /setting/publishStage/{id} - получение стадии публикации. Для использования данного АПИ нужно обладать правами уровня admin.

Обязательные заголовки:

Authorization: Bearer <Token>

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

GET https://azdoc.online/api/setting/publishStage/35d8b3c7-edd3-4adf-9043-bc9693e77d44
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

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


{
    "id": "35d8b3c7-edd3-4adf-9043-bc9693e77d44",
    "name": "Test",
    "order": "1",
    "approvers": [
        {
            "id": "fa312064-2af5-4d3b-9961-a3bd235ebdf8",
            "email": "alexander.popov@company.ru",
            "firstName": "Alexander",
            "lastName": "Popov"
        },
        {
            "id": "fa312064-2af5-4d3b-9961-a3bd235ebdf8",
            "email": "ivan.pavlov@company.ru",
            "firstName": "Ivan",
            "lastName": "Pavlov"
        }
    ],
    "publishers": [],
    "autoPublish": true
}

Параметры ответа:

Параметр Формат Обязательность Описание
name string Да Название стадии.
order integer Да Порядок следования стадий.
approvers array Нет Список согласующих. Список представляет из себя массив объектов, в каждом объекте - id пользователя, email, имя и фамилия согласующего.
publishers array Нет Список публикующих. Список представляет из себя массив объектов, в каждом объекте - id пользователя, email, имя и фамилия согласующего.
autoPublish boolean Нет Автоматическая публикация. Документ автоматически публикуется сразу после получения всех согласований.

Удаление стадии публикации

DELETE /setting/publishStage/ - удаление стадии публикации. Для использования данного АПИ нужно обладать правами уровня admin.

Обязательные заголовки:

Authorization: Bearer <Token>

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

DELETE https://azdoc.online/api/setting/publishStage/
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

{
    "id":"35d8b3c7-edd3-4adf-9043-bc9693e77d44"
}

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


{
    "status": "Success",
    "message": "Deleted successfully."
}