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

Авторизация пользователя
Получение информации о пользователе
Получение аватарки пользователя
Подтверждение данных пользователя
Отклонение данных пользователя
Получение списка документов
Получение информации о документе
Получение превью страницы документа
Получение факсимиле
Подписание документа
Массовое подписание документов
Отклонение документа
Скачивание документа

Авторизация пользователя

Метод используется для авторизации в КОМАН. Для авторизации требуется вызвать запрос 2 раза. При первом вызове вернется smsToken и код из смс, который требуется добавить в Headers.

Описание метода

Метод

URL

Headers

POST

https://coman.app/api-user/login/otp

`Authorization: Bearer `

`Content-Type: application/json`

Headers

Key	Обяз.	Комментарий
X-Otp-Code	Усл.*	Код из СМС
X-Otp-Token	Усл.*	Токен. из первого ответа на запрос

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

Поле	Тип	Обяз.	Комментарий
phoneNumber	Текст(12)	Усл*	Номер телефона
email	Текст(255)	Усл*	Электронная почта

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

Тело запроса (body)

{
   "phoneNumber": "+79998406909"
}

Формат ответа

Ответ в случае успешной обработки запроса

Первое сообщение до того, как придет код из смс:
{
    "code": "SMS_CONFIRMATION_REQUIRED",
    "translation": "{smsConfirmationRequired}",
    "requestUuid": "018eb9c2-2cc2-70d3-9705-266815f3f4db",
    "success": false,
    "smsToken": "eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE3MTI1MTM0OTQsImlkIjo0MjQ1LCJ0eXBlIjoiMyIsInV1aWQiOiIwMThlYjljMi0yZWU5LTc1YTQtOGM4MS1hNTMxYmJhZmFmNGMiLCJ2ZXJzaW9uIjoiMS4wIiwicHJvZHVjdE5hbWUiOiJjb21hbiIsImV4cCI6MTcxMzExMzQ5NH0.TtYISqyGq1qSjCWL6x4-aaYCTORMPOADxnJ0f8dV5OQ0zgQbaLyYO0Ww6gWYA3UWLOSl-nikZ1KFwNm5whKufg",
    "confirmationCodeLength": 4,
    "secondsUntilResend": 25
}


Первое сообщение при отправке по почте до того, как придет код по почте:
{
    "code": "EMAIL_CONFIRMATION_REQUIRED",
    "translation": "{emailConfirmationRequired}",
    "requestUuid": "018eb9cc-4f27-7ee1-9864-ec0371e7ee25",
    "success": false,
    "smsToken": "eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE3MTI1MTQxNTgsImlkIjo0MjQ3LCJ0eXBlIjoiMyIsInV1aWQiOiIwMThlYjljYy00ZmU5LTcxMzYtYWJmMC1hNWFjMDY1OWM3ZDUiLCJ2ZXJzaW9uIjoiMS4wIiwicHJvZHVjdE5hbWUiOiJjb21hbiIsImV4cCI6MTcxMzExNDE1OH0.WfhbNtR98JW2XGdryt8GkZc6mwZ41EEIYiMrmCLNBvZvdTZsCduFOQonjkXRtvt42amrAJSnRZH68CjmuQG4Iw",
    "confirmationCodeLength": 4,
    "secondsUntilResend": 25
}


Второе сообщение после успешной авторизации:
{
    "accessToken": "eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE3MTI1MTM3MTcsImlkIjoyMjY5LCJ0eXBlIjoiMSIsInV1aWQiOiIwMThlYjljNS05NTA4LTc0YTAtYTdmYy1iZmI3ODA3ZTM4NjkiLCJ2ZXJzaW9uIjoiMS4wIiwicHJvZHVjdE5hbWUiOiJjb21hbiIsImV4cCI6MTcyMzcyMzMxN30.5V0GVrH2A4GGpZRyzIovNNqH5l1qVtsd74c14uCsxNMZWEC87ePo0GM6s2Gw_FQWOXS0qPb27z4gualqlS5DuQ",
    "tokenType": "Bearer"
}

Ответ в случае, если телефон/почта не найдена

{
    "code": "WRONG_PHONE_NUMBER",
    "translation": "{wrongPhoneNumber}",
    "requestUuid": "018eb9c7-3d03-76e2-a34d-b05da22181aa",
    "success": false
}

{
    "code": "WRONG_EMAIL",
    "translation": "{wrongEmail}",
    "requestUuid": "018eb9d1-d859-736b-9512-83394364e264",
    "success": false
}

Ответ в случае ошибки обработки

{
    "code": "WRONG_SMS_CODE",
    "translation": "{wrongSmsCode}",
    "requestUuid": "018eb9c4-7f66-742a-bf9a-9fb8b741177b",
    "success": false
}

Перечень возможных кодов ошибок

Возможные значения поля "code", внутри массива "responseList":	Комментарии
WRONG_PHONE_NUMBER	Неправильный номер телефона
WRONG_EMAIL	Неправильная электронная почта
WRONG_FORMAT	Неправильный формат
TOO_MANY_REQUESTS	Слишком много запросов отправлено

Получение информации о пользователе

Метод

URL

Headers

GET

https://coman.app/api-user/me/info

`Authorization: Bearer `

`Content-Type: application/json`

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

Поле	Тип	Комментарий
info
uuid	Текст (255)	Уникальный идентификатор пользователя
firstName	Текст (255)	Имя пользователя
middleName	Текст (255)	Фамилия пользователя
lastName	Текст (255)	Отчество пользователя
snils	Текст (20)	СНИЛС пользователя
passportTypeCode	Текст (20)	Вид паспорта. Необязательное. Возможные значения: - RUSSIAN; - OTHER.
passportBatch	Текст (7)	Серия паспорта
passportNumber	Текст (15)	Номер паспорта
passportIssuingCenter	Текст (500)	Кем выдан паспорт
passportInfo	Текст (500)	Информация о паспорте (используется только если выбран тип паспорта OTHER)
passportIssueDate	Дата	Дата выдачи паспорта, формат (ГГГГ-ММ-ДД)
statusCode	Текст (255)	Расшифровка статуса пользователя
userPictureUrl	Текст (255)	URL для вызова и получения аватарки пользователя
currentVersionUuid	Текст (255)	UUID версии пользователя
phone	Текст (20)	Телефон
email	Текст (255)	Электронная почта
phoneIsVerified	Булево	Подтвержден ли номер телефона
emailsVerified	Булево	Подтверждена ли электронная почта
statusName	Текст (255)	Расшифровка статуса пользователя (На русском языке)
previousInfo	Массив	Массив появляется в статусе пользователя "Требуется проверка личных данных пользователем". Для сравнения новых данных с предыдущими

Формат ответа

Ответ в случае успешной обработки запроса

{
    "me": {
        "info": {
            "uuid": "018edd3b-ddf2-7538-a88f-b91078a276de",
            "firstName": "Прохор",
            "middleName": "Безумнович",
            "lastName": "Шаляпин",
            "snils": "30870893493",
            "passportTypeCode": "OTHER",
            "passportInfo": "Выдан 19.01.2016 Турецкий ID: 7827654998",
            "statusCode": "USER_DATA_CHECKING_BY_USER",
            "currentVersionUuid": "018edd3b-e06d-7ae0-bbd8-3a6bbfa9d7b4",
            "email": "leyay66482@acname.com",
            "emailIsVerified": true,
            "statusName": "Требуется проверка личных данных пользователем"
        },
        "roles": []
    }
}

Возможные статусы пользователя

statusCode	statusName
ACTIVE	Активный
USER_DATA_CHECKING_BY_USER	Требуется проверка личных данных пользователем
USER_DATA_REJECTED	Требуется исправление личных данных пользователя
CREATING_KEY	Создается УНЭП
USER_DATA_PRE_CHECK	Требуется предварительная проверка личных данных пользователя
PERSONAL_INFO_IS_EMPTY	Персональные данные не введены

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

Метод

URL

Headers

GET

https://coman.app/api-user/users/picture/{userPictureUrl}

`Authorization: Bearer `

`Content-Type: application/json`

Подтверждение данных пользователя

Метод

URL

Headers

POST

https://coman.app/api-user/me/confirm-data

`Authorization: Bearer `

`Content-Type: application/json`

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

Поле	Тип	Обяз.	Комментарий
currentVersionUuid	Текст(38)	Да	Берется из объекта info запроса /api-user/me/info

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

Тело запроса (body)

{
    "currentVersionUuid": "018eba29-329c-7444-842b-7a36b01e95f7"
}

Формат ответа

Ответ в случае успешной обработки запроса

{
    "code": "OK",
    "requestUuid": "018eba3a-5d44-79aa-bf83-b337181a3967",
    "success": true
}

Отклонение данных пользователя

Метод

URL

Headers

POST

https://coman.app/api-user/me/reject-data

`Authorization: Bearer `

`Content-Type: application/json`

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

Поле	Тип	Обяз.	Комментарий
currentVersionUuid	Текст(38)	Да	Берется из объекта info запроса /api-user/me/info
comment	Текст(255)	Да	Комментарий

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

Тело запроса (body)

{
    "currentVersionUuid": "018eba29-329c-7444-842b-7a36b01e95f7",
    "comment": "Какие еще цифры?"
}

Формат ответа

Ответ в случае успешной обработки запроса

{
    "code": "OK",
    "requestUuid": "018eba5b-477b-7e36-aafa-5a54cd53703e",
    "success": true
}

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

Метод

URL

Headers

POST

https://coman.app/api-user/doc/list

`Authorization: Bearer `

`Content-Type: application/json`

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

Поле	Тип	Обяз.	Комментарий
offset	Текст(12)	Да	Офсет
limit	Массив	Да	Лимит
type	Текст (10)	Да	Возможные типы документа: - TO_SIGN - К подписанию пользователем - SIGNED - Подписанные пользователем - WAITING_FOR_SIGNER - Ждем подписанта - DRAFT - Черновики - INBOX - Входящие - REJECTED - Отклоненные - EXPIRED - Истекшие - SENT - Отправленные - ALL - Все документы

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

Тело запроса (body)

{
    "offset": 0, 
    "limit": 30, 
    "type": "TO_SIGN" 
}

Формат ответа

Ответ в случае успешной обработки запроса

{
    "count": 2,
    "requestedLimit": 30,
    "requestedOffset": 0,
    "maxLimit": 10000,
    "data": [
        {
            "uuid": "018dc753-248c-7aef-b3fc-f6750ce64c91",
            "pageCount": 1,
            "entityName": "ООО Калитеро",
            "statusName": "Подписание",
            "envelopeExternalTypeName": "Требование лица, которому отказано в заключении трудового договора",
            "envelopeExternalTypeCode": "01.003",
            "statusCode": "SIGNING",
            "creatorUserName": "Лапин Илюша Сергеевич"
        },
        {
            "uuid": "018c4995-cd02-71d7-9cf5-b0e6ff3c7af2",
            "pageCount": 1,
            "entityName": "Калитеро",
            "statusName": "Подписание",
            "envelopeExternalTypeName": "Требование лица, которому отказано в заключении трудового договора",
            "envelopeExternalTypeCode": "01.003",
            "statusCode": "SIGNING",
            "creatorUserName": "Иванов Михаил Дмитриевич",
            "creatorUserPictureUrl": "/api-user/users/picture/d8128581-23f6-4afe-8d0f-ddae9eff2b5a/1702046719106"
        }
    ],
    "requestUuid": "018eba68-7450-7edf-bc30-9e792943c126"
}

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

{
    "count": 0,
    "requestedLimit": 30,
    "requestedOffset": 0,
    "maxLimit": 10000,
    "data": [],
    "requestUuid": "018edd75-f62f-72ac-abc2-7417420f6351"
}

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

Метод

URL

Headers

GET

https://coman.app/api-user/doc/:uuid

`Authorization: Bearer `

`Content-Type: application/json`

Формат ответа

Ответ в случае успешной обработки запроса

{
    "uuid": "018e51e1-6b74-7d4e-b202-b46937963c29",
    "pageCount": 1,
    "entityName": "ООО Калитеро",
    "statusName": "Подписан",
    "envelopeExternalTypeName": "Арбитражное соглашение",
    "envelopeExternalTypeCode": "08.001",
    "statusCode": "COMPLETED",
    "fileProcessingStatusCode": "READY",
    "creatorUserName": "Иванов Михаил Дмитриевич",
    "creatorUserPictureUrl": "/api-user/users/picture/d8128581-23f6-4afe-8d0f-ddae9eff2b5a/1702046719106",
    "stages": [
        {
            "signOrder": 1,
            "statusCode": "FINISHED",
            "allUsers": false,
            "includesAuthor": false,
            "authorIsQualified": false,
            "includesManager": false,
            "managerIsQualified": false,
            "includesSelectedOnSending": true,
            "selectedOnSendingIsQualified": false,
            "statusName": "Этап завершен",
            "signers": [
                {
                    "statusCode": "SIGNED",
                    "qualified": false,
                    "statusName": "Подписано",
                    "userUuid": "d8128581-23f6-4afe-8d0f-ddae9eff2b5a",
                    "userFullName": "Иванов Михаил Дмитриевич"
                }
            ]
        }
    ]
}

Получение превью страницы документа

Метод

URL

Headers

GET

https://coman.app/api-user/doc/:uuid/page/:number

`Authorization: Bearer `

`Content-Type: application/json`

При вызове запроса вернется выбранная страница по порядковому номеру документа в формате PNG.

Получение факсимиле

Метод

URL

Headers

GET

https://coman.app/api-user/me/facsimile

`Authorization: Bearer `

`Content-Type: application/json`

При вызове запроса вернется факсимиле пользователя в формате SVG.

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

Метод

URL

Headers

POST

https://coman.app/api-user/doc/sign

`Authorization: Bearer `

`Content-Type: application/json`

Headers

Key	Обяз.	Комментарий
X-Otp-Code	Усл.*	Код из СМС
X-Otp-Token	Усл.*	Токен. из первого ответа на запрос

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

Поле	Тип	Обяз.	Комментарий
documentUuid	Текст(12)	Да	UUID документа
facsimiles	Массив	Усл*	Массив, с данными факсимиле
x	Дробное число	Усл*	Данные по координате X (например, 218.261)
y	Дробное число	Усл*	Данные по координате Y (например, 1051.493)
pageNumber	Число	Усл*	Номер страницы для простановки факсимиле

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

Тело запроса (body)

{
"documentUuid": "018ebf91-7c88-7905-b4c7-49198a52f266",
"facsimiles": [
{
"x": 765.8008595988538, 
"y": 144.90544412607449,
"pageNumber": 1
}
]
}

Формат ответа

Ответ в случае успешной обработки запроса

Первое сообщение до того, как придет код из смс/email:
{
    "code": "SMS_CONFIRMATION_REQUIRED",
    "translation": "{smsConfirmationRequired}",
    "requestUuid": "018edd84-8e7d-7881-b2a3-e2fdc687ed85",
    "success": false,
    "smsToken": "eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE3MTMxMTM0MzUsImlkIjo0NDMzLCJ0eXBlIjoiMyIsInV1aWQiOiIwMThlZGQ4NC04ZjQ5LTdjNmUtOWIxMC0yNDQyN2FlNjg4OTUiLCJ2ZXJzaW9uIjoiMS4wIiwicHJvZHVjdE5hbWUiOiJjb21hbiIsImV4cCI6MTcxMzcxMzQzNX0.IiPgBAT0zdd0DGxf3YN-j0GTpghwj9SYhmu32S_wyDm9TAlYKzExkP5ZyKF7PGIZWPXEuufyRQ4GQJln7AiPDw",
    "confirmationCodeLength": 4,
    "secondsUntilResend": 25
}

Второе сообщение после того как проставили в headers x-otp-code и x-otp-token:

{
    "code": "OK",
    "requestUuid": "018edd87-24db-7504-8db1-4649424efb1b",
    "success": true
}

Массовое подписание документов

Метод

URL

Headers

POST

https://coman.app/api-user/doc/sign-list

`Authorization: Bearer `

`Content-Type: application/json`

Headers

Key	Обяз.	Комментарий
X-Otp-Code	Усл.*	Код из СМС
X-Otp-Token	Усл.*	Токен. из первого ответа на запрос

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

Поле	Тип	Обяз.	Комментарий
documents	Массив	Да	Массив с документами
documentUuid	Текст(12)	Да	UUID документа
facsimiles	Массив	Усл*	Массив, с данными факсимиле
x	Дробное число	Усл*	Данные по координате X (например, 218.261)
y	Дробное число	Усл*	Данные по координате Y (например, 1051.493)
pageNumber	Число	Усл*	Номер страницы для простановки факсимиле

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

Тело запроса (body)

{
    "documents":[    {
        "documentUuid": "018edd93-8e88-754f-8be6-ca8e5d49fc25",
        "facsimiles": [
            {
                "x": 844.4156626506025,
                "y": 96.70223752151463,
                "pageNumber": 1
            },
            {
                "x": 878.5912220309812,
                "y": 122.33390705679862,
                "pageNumber": 8
            }
        ]
    },
    {
        "documentUuid": "018edd92-f764-71fa-b21c-c23a66f6d737",
        "facsimiles": [
            {
                "x": 850.8235800344235,
                "y": 212.0447504302926,
                "pageNumber": 1
            }
        ]
    }
]}

Формат ответа

Ответ в случае успешной обработки запроса

Первое сообщение до того, как придет код из смс/email:
{
    "code": "SMS_CONFIRMATION_REQUIRED",
    "translation": "{smsConfirmationRequired}",
    "requestUuid": "018edd84-8e7d-7881-b2a3-e2fdc687ed85",
    "success": false,
    "smsToken": "eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE3MTMxMTM0MzUsImlkIjo0NDMzLCJ0eXBlIjoiMyIsInV1aWQiOiIwMThlZGQ4NC04ZjQ5LTdjNmUtOWIxMC0yNDQyN2FlNjg4OTUiLCJ2ZXJzaW9uIjoiMS4wIiwicHJvZHVjdE5hbWUiOiJjb21hbiIsImV4cCI6MTcxMzcxMzQzNX0.IiPgBAT0zdd0DGxf3YN-j0GTpghwj9SYhmu32S_wyDm9TAlYKzExkP5ZyKF7PGIZWPXEuufyRQ4GQJln7AiPDw",
    "confirmationCodeLength": 4,
    "secondsUntilResend": 25
}

Второе сообщение после того как проставили в headers x-otp-code и x-otp-token:

{
    "responseList": [
        {
            "code": "OK",
            "requestUuid": "018edda2-9b2a-7172-a9bc-edb42f5a0396",
            "success": true,
            "needAnotherSigning": false
        },
        {
            "code": "OK",
            "requestUuid": "018edda2-9b2a-7172-a9bc-edb42f5a0396",
            "success": true,
            "needAnotherSigning": false
        }
    ],
    "totalCount": 2,
    "successCount": 2,
    "badCount": 0
}

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

Метод

URL

Headers

POST

https://coman.app/api-user/doc/reject-or-delete

`Authorization: Bearer `

`Content-Type: application/json

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

Поле	Тип	Обяз.	Комментарий
documentUuid	Текст(12)	Усл*	UUID документа
comment	Массив	Усл*	Массив, с данными факсимиле

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

Тело запроса (body)

{
    "documentUuid": "018ebf86-e14c-7eba-8543-dbf058e4e7fd",
    "comment": "Не буду такое подписывать"
}

Формат ответа

Ответ в случае успешной обработки запроса

{
    "code": "OK",
    "requestUuid": "018edda8-fb69-74db-86e5-8bdc78887e55",
    "success": true
}

Скачивание документа

Метод	URL	Комментарий	Headers
GET	https://coman.app/api-user/doc/:uuid/doc-pdf	Электронный документ	`Authorization: Bearer ` `Content-Type: application/json
	https://coman.app/api-user/doc/:uuid/info-pdf	Сертификат документа
	https://coman.app/api-user/doc/:uuid/doc-with-info-pdf	Документ с сертификатом
	https://coman.app/api-user/doc/:uuid/archive	Архив с оригиналом и подписями
	https://coman.app/api-user/doc/:uuid/mintrud-archive	Архив с xml

При вызове запроса вернется документ в формате .pdf, либо архив в формате .zip