Инструкции и FAQ

Как выполнить типичные операции в LightDoc и ответы на часто задаваемые вопросы

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

Интеграции

Управление аккаунтами и оплата

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

Оглавление

Кодировка запроса
Обработка ошибок
Диаграмма документа
Диаграмма взаимодействия
Методы

Кодировка запроса #

Тело запроса в методах POST принимается в кодировке UTF8 Ответ возвращается также в кодировке UTF8

Обработка ошибок #

Если запрос обработан правильно, вернется стандартный HTTP код ответа 200 OK. В случае возникновения ошибки возвращается код отличный от 200, в теле запроса будет указан внутренний код ошибки и сообщение с расшифровкой:

{
  "code": 500,
  "message": "Ошибка при загрузке документа с ID \"12837491723497\""
}

Диаграмма документа #

В диаграмме описывается граф состояний документа с указанием разрешений пользователей и внешних систем на выполняемые действия Синие блоки — доступные действия над документом Желтые блоки — состояния документа

Диаграмма взаимодействия #

Описывается пример взаимодействия клиентской системы с API LightDoc

Методы #

GET /v1/documents #

Получение списка документов за период. Для токена API в момент выпуска требуется установить разрешение «Доступ к документам аккаунта».

Входные параметры #

dateFrom (query:datetimeoffset=now()-1 month) — начальная дата создания документа в формате даты/времени. Значение по умолчанию — текущая дата минус 1 месяц;
dateTo (query:datetimeoffset=now()) — конечная дата создания документа в формате даты/времени. Значение по умолчанию — текущая дата/время;
full (query:boolean=false) — выгружать документ целиком. При значении false выгружается массив, состоящий только из идентификаторов документов и их статусов. По умолчанию используется значение false;
filterTags(query:string = null) — поисковые фильтры, строковые значения через запятую. По умолчанию без фильтрации выгружается все документы по аккаунту токена. При использовании фильтрации для доступа к личным документам требуется разрешение «Доступ к личным документам». Допустимые значения:
- Income — входящие документы
- Outcome — исходящие документы
- WaitsMe — документы, ожидающие личной подписи
- WaitsOthers — документы, ожидающие личной подписи
- Completed — подписанные документы
- Rejected — отклоненные документы
- Draft — черновики документов
- Deleted — удаленные документы

❗Поддерживается указание даты, даты/времени и даты/времени с таймзоной по стандарту 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
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

Результат выполнения #

Описание #

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 - подписал документ)
  signature:Object
    status:string ["WaitsMe", "WaitsOthers"] - статус подписания (WaitsMe - ожидает моей подписи, WaitsOthers - ожидает подписания другим подписантом)
    context:int - контекст подписания, который передается в метод API для подписи документа
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": "petr@lightdoc.io",
      "number": 1,
      "approveType": "Agree",
      "status": "Opened",
      "signature: {
        "status": "WaitsMe",
        "context: {
          "id": 918431
        }
      }
    },
    {
       "firstName": "Иван",
       "lastName": "Иванов",
       "patronymic": "Иванович",
       "email": "ivan@lightdoc.io",
       "number": 2,
       "approveType": "AesLightDoc",
       "status": "Notified"
       "signature: {
         "status": "WaitsOthers",
         "context: {
           "id": 918432
         }
       }
    }
  ],
  "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)

POST /v1/documents/{documentID}/sign/aes #

Подписание документа электронной подписью УНЭП LightDoc. Для токена API в момент выпуска требуется установить разрешение «Подписание документов».

Входные параметры #

documentID (path:string) — уникальный идентификатор документа в системе LightDoc
(body:object) — контекст подписания

Описание #

context:Object - контекстом подписания из метода GET /v1/documents/{documentID}
signature:Object - объект УНЭП AesLightDoc из метода POST /v1/signature/aes/confirm
  thumbprint:string - отпечаток подписи УНЭП AesLightDoc
  key:string - ключ подписи УНЭП AesLightDoc

Пример #

{
  "context": {
    "id": 918431
  },
  "signature": {
    "thumbprint": "FAB6BC2787A41E5D488662C819..."
    "key": "MIIEvQIBADANBgkqhkiG9w0BAQEFAA..."
  }
}

POST /v1/signature/aes/issue #

Запрос выпуска электронной подписи УНЭП LightDoc для пользователя, от имени которого был выпущен токен API. При успешном выполнении метода на Email пользователя отправляется код подтверждения. Для токена API в момент выпуска требуется установить разрешение «Выпуск подписи».

Результат выполнения #

Описание #

issue:Object - контекст запроса выпуска подписи УНЭП LightDoc
confirmation:Object - требования к запросу
  remainingSeconds:int - период действия запроса в секундах
  expiry:datatime - время завершения действия запроса
  maxAttempts:int - максимальное количество попыток

Пример #

{
  "issue": {
    "id": 394752
  },
  "confirmation": {
    "remainingSeconds": 600,
    "expiry": "2024-06-16T17:00:16.0200000Z",
    "maxAttempts": 3
  }
}

POST /v1/signature/aes/confirm #

Подтверждение выпуска электронной подписи УНЭП LightDoc.

Входные параметры #

Описание #

issue:Object - контекст запроса выпуска подписи УНЭП LightDoc
code:string - код подтверждения выпуска подписи, который отправляется на Email при выполнении метода POST /v1/signature/aes/issue

Пример #

{
  "issue": {
    "id": 394752
  },
  "code": "123..."
}

Результат выполнения #

Описание #

commonName:string - наименование сертификата 
key:string - ключ подписи УНЭП AesLightDoc
thumbprint:string - отпечаток подписи УНЭП AesLightDoc
validFromDate:datetime - дата создания подписи
validToDate:datetime - дата окончания действия подписи

Пример #

{
  "commonName": "Иванов Иван Иванович at the Chrome/Mac OS X 10 (Mac)",
  "key": "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwg..",
  "thumbprint": "FAB6BC2787A41E5D488662C81..",
  "validFromDate": "2024-06-10T17:13:00Z",
  "validToDate": "2025-06-10T17:13:00Z"
}

Частые проблемы и способы решения:

Подписанту документа Отправителю документа Регистрация своей компании и оплата

Инструкции и FAQ

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

Кодировка запроса #

Обработка ошибок #

Диаграмма документа #

Диаграмма взаимодействия #

Методы #

GET /v1/documents #

Входные параметры #

Результат выполнения #

POST /v1/documents #

Входные параметры #

Описание #

Пример #

Результат выполнения #

Описание #

Пример #

POST /v1/documents/{documentID}/files #

Входные параметры #

Результат выполнения #

Описание #

Пример #

GET /v1/documents/{documentID}/status #

Входные параметры #

Результат выполнения #

Описание #

Пример #

GET /v1/documents/{documentID}/signed #

Входные параметры #

Результат выполнения #

Описание #

GET /v1/documents/{documentID} #

Входные параметры #

Результат выполнения #

Описание #

Пример #

POST /v1/documents/{documentID}/action #

Входные параметры #

POST /v1/documents/{documentID}/sign/aes #

Входные параметры #

Описание #

Пример #

POST /v1/signature/aes/issue #

Результат выполнения #

Описание #

Пример #

POST /v1/signature/aes/confirm #

Входные параметры #

Описание #

Пример #

Результат выполнения #

Описание #

Пример #

FAQ - Часто задаваемые вопросы