Описание методов API
Кодировка запроса #
Тело запроса в методах POST принимается в кодировке UTF8
Ответ возвращается также в кодировке UTF8
Обработка ошибок #
Если запрос обработан правильно, вернется стандартный HTTP код ответа
200 OK.
В случае возникновения ошибки возвращается код отличный от 200, в теле запроса будет указан внутренний код ошибки и сообщение с расшифровкой:
{
"code": 500,
"message": "Ошибка при загрузке документа с ID \"12837491723497\""
}
Диаграмма документа #
В диаграмме описывается граф состояний документа с указанием разрешений пользователей и внешних систем на выполняемые действия
Синие блоки — доступные действия над документом
Желтые блоки — состояния документа
Диаграмма взаимодействия #
Описывается пример взаимодействия клиентской системы с API LightDoc
Методы
#
GET /v1/documents #
Получение списка документов за период.
Входные параметры #
- dateFrom (query:datetimeoffset=now()-1 month) — начальная дата создания документа в формате даты/времени. Значение по умолчанию — текущая дата минус 1 месяц;
- dateTo (query:datetimeoffset=now()) — конечная дата создания документа в формате даты/времени. Значение по умолчанию — текущая дата/время;
- full (query:boolean=false) — выгружать документ целиком. При значении false выгружается массив, состоящий только из идентификаторов документов и их статусов. По умолчанию используется значение false;
❗Поддерживается указание даты, даты/времени и даты/времени с таймзоной по стандарту ISO8601. Пример: 2020-04-01T03:00:00.000+03:00
❗Интервал дат не должен превышать 31 день
Результат выполнения #
- При параметре full=false
[
{
"documentID": "66CA50FC-2D5C-401E-AA0C-C562633DD3CE",
"status": "Signing"
},
{
"documentID": "41387865-F19D-4626-9381-0A194BECF1A0",
"status": "Deleted"
},
{
"documentID": "2FF7B917-0F45-4ABA-9831-B05661C3D012",
"status": "Rejected"
},
{
"documentID": "A8BAA3A9-397A-4519-853D-4B7D01EF4DB2",
"status": "Signed"
}
]
- При параметре full=true
[
{
"id": "Реестр000018043",
"documentID": "677DE981-6612-4C6F-AC9A-A5DE6E6B8A92",
"name": "РеестрПВП_000018043_30_07_2021 8_51_33_6592 Иванов Иван Иванович",
"isSequential": false,
"status": "Signed",
"url": "https://beta.lightdoc.io/documents/677DE981-6162-6C6F-AC9A-A5DE6E6B8A96",
"created": "2021-10-15T14:14:09.5333333Z",
"author": "Петров Петр Петрович"
}
]
POST /v1/documents #
Регистрация документа.
Полученный в результате выполнения идентификатор
documentID используется в дальнейшем для загрузки файлов, получения статуса и других операций с документом, предполагается его сохранение в клиентской системы для выполнения других действий связанных с жизненным циклом документа.
Входные параметры #
- (body:object<document>) — метаданные документа
Описание #
id:string - идентификатор документа в клиентской системе
name:string - отображаемое наименование документа
isSequential:boolean=false - последовательность подписания (true - последовательно, false - параллельно)
signers:Array - массив подписантов
firstName:string - имя подписанта
lastName:string - фамилия подписанта
patronymic:string - отчество подписанта
email:string - Email адрес подписанта
number:int=0 - порядковый номер подписанта при последовательном подписании
approveType:string ["Bes", "BesVisual", "AesLightDoc", "QesRu"] - тип подписи (Bes - ПЭП цифровая , BesVisual - ПЭП графическая, AesLightDoc - УНЭП LightDoc, QesRu - УКЭП РФ). Тип BesVisual в данный момент не поддерживается в API
verificationRequire:boolean=false - требование верификации подписанта, при значении true подписать может только пользователь прошедший верификацию
Пример #
{
"id": "dogovor123",
"name": "Договор 123 от 01.01.2022г с Петров П.",
"isSequential": false,
"signers": [
{
"firstName": "Петр",
"lastName": "Петров",
"patronymic": "Петрович",
"email": "demo+petr@lightdoc.io",
"approveType": "Bes"
}
]
}
Результат выполнения #
Описание #
id:string - уникальный идентификатор документа в клиентской системе
documentID:string - уникальный идентификатор документа в системе LightDoc
url:string - ссылка на новый документ
Пример #
{
"id": "dogovor123",
"documentID": "EAD61586-9E50-4996-B3E4-64F6D8133D03",
"url": "https://beta.lightdoc.io/documents/EAD61586-9E50-4996-B3E4-64F6D8133D03"
}
POST /v1/documents/{documentID}/files #
Загрузка файлов документа.
Отправка документа на подписание происходит автоматически после успешной загрузки и обработки файлов. Максимальный суммарный размер загружаемых файлов не должен превышать 50Мбайт
Входные параметры #
documentID (path:string) — уникальный идентификатор документа в системе LightDoc Start
files (multipart/form-data:array) — массив файлов документа в бинарном формате передаваемый через содержимое html-формы. Формат загружаемых файлов PDF
Результат выполнения #
Описание #
count:integer - количество загруженных файлов
size:integer - общий размер файлов
Пример #
{
"count": 1,
"size": 48037
}
GET /v1/documents/{documentID}/status #
Получение актуального статуса документа
Коды статусов
- Draft — Черновик
- Signing — На подписании
- Signed — Подписан
- Rejected — Отклонен
- Deleted — Удален
Диаграмма состояний
Входные параметры #
- documentID (path:string) — уникальный идентификатор документа в системе LightDoc
Результат выполнения #
Описание #
documentID:string - уникальный идентификатор документа в системе LightDoc
status:string - код статуса документа (Draft/Signing/Signed/Rejected/Deleted)
Пример #
{
"documentID": "EAD61586-9E50-4996-B3E4-64F6D8133D03",
"status": "Signing"
}
GET /v1/documents/{documentID}/signed #
Скачивание файла подписанной версии документа с сертификатом
Входные параметры #
- documentID (path:string) — уникальный идентификатор документа в системе LightDoc
Результат выполнения #
Описание #
body:binary - содержимое скачиваемого файла
headers
content-length - размер файла в байтах
content-type - формат файла (строка "application/pdf")
content-disposition attachment; filename="{{filename.pdf}}"; filename*=UTF-8{{filename.pdf}} - метаданные файла
GET /v1/documents/{documentID} #
Актуальная информация о документе
Входные параметры #
- documentID (path:string) — уникальный идентификатор документа в системе LightDoc Start
Результат выполнения #
Описание #
id:string - идентификатор документа в клиентской системе
documentID:string - уникальный идентификатор документа в системе LightDoc
name:string - отображаемое наименование документа
isSequential:boolean - последовательность подписания (true - последовательно, false - параллельно)
signers:Array - массив подписантов
firstName:string - имя подписанта
lastName:string - фамилия подписанта
patronymic:string - отчество подписанта
email:string - Email адрес подписанта
number:int=null - порядковый номер подписанта при последовательном подписании
approveType:string ["Bes", "BesVisual", "AesLightDoc", "QesRu"] - тип подписи (Bes - ПЭП цифровая , BesVisual - ПЭП графическая, AesLightDoc - УНЭП LightDoc, QesRu - УКЭП РФ)
status:string ["Notified", "Opened", "Rejected", "Approved"] - статус подписания (Notified - подписант уведомлен, Opened - открыл документ, Rejected - отклонил, Approved - подписал документ)
files:Array - массив файлов
fileName:string - имя загруженного файла
number:int - порядковый номер файла в документе
pageCount:int - количество страниц
status:string ["Parsing", "Done", "Error", "Deleted"] - статус загруженного файла (Parsing - обработка, Done - обработано успешно, Error - ошибка обработки, Deleted - удален)
actions:Array<string> ["Revoke", "DeleteReleased"] - доступные действия над документом (Revoke - отозвать, DeleteReleased - удалить)
Пример #
{
"id": "Реестр000018043",
"documentID": "677DE981-6612-4C6F-AC9A-A5DE6E6B8A92",
"name": "РеестрПВП_000018043_30_07_2021 8_51_33_6592 Иванов Иван Иванович",
"isSequential": false,
"status": "Signing",
"url": "https://beta.lightdoc.io/documents/677DE981-6162-6C6F-AC9A-A5DE6E6B8A96",
"created": "2021-10-15T14:14:09.5333333Z",
"author": "Петров Петр Петрович",
"files": [
{
"fileName": "РеестрПВП_000018043_30_07_2021 8_51_33_6592 Иванов Иван Иванович.pdf",
"number": 1,
"pageCount": 1,
"status": "Done"
}
],
"signers": [
{
"firstName": "Петр",
"lastName": "Петров",
"patronymic": "Петрович",
"email": "demo+petr@lightdoc.io",
"number": null,
"approveType": "Agree",
"status": "Notified"
}
],
"actions": [
"Revoke",
"DeleteReleased"
]
}
POST /v1/documents/{documentID}/action #
Действие над документом.
Список доступных действий можно получить выполнив предыдущий метод GET /v1/documents/{documentID}
Доступные действия
- Send -отправить документ на подписание
- Revoke — отозвать документ
- DeleteReleased / DeleteDraft — удалить документ, отправленный на подписание
- EditRejected — редактировать отозванный документ
Входные параметры #
- documentID (path:string) — уникальный идентификатор документа в системе LightDoc
- action (query:string) — код действия над документом (Revoke, DeleteReleased)