Подписание и проверка

Подпись файла

URL https://server_name/signapi/sjson

Request

• Method POST
• Content-type application/json
• Body JSON
  • key = полученный ключ доступа
  • filet = base64_encode( содержимое файла )
  • fname = имя файла
  • Идентификатор для определения подписанта файла:
  • user_email = email пользователя, подписывающего файл
  • user_ph = телефон пользователя, подписывающего файл
  • user_snils = СНИЛС пользователя, подписывающего файл
  • company_inn = ИНН компании, подписывающей файл
  • company_ogrn = ОГРН компании, подписывающей файл
  • company_kpp = КПП компании, подавать вместе с ИНН или ОГРН
  • Далее идут дополнительные параметры, которые не обязательно использовать:
  • md5 = хеш содержимого для проверки
  • url = адрес возврата после подписания
  • push_key = push_key = id ключа для отправки PUSH-уведомления в мобильное устройство, при переходе по которому сразу откроется экран подписания. Ключ должен быть мобильным, ID можно взять из АПИ "Сертификаты" - "Сертификаты пользователя"
  • noemail = 1, если нужно не высылать пользователю емеил
  • nopush = 1, если не нужно высылать пользователю push на устройство
  • forcesms = 1, если необходима двухфакторная авторизация при подписании серверный НКЭП
  • IF = 1, если необходимо уведомление на url-оповещения[^2] при каждом подписании [^3]

Response

• Success

  • Content-type text/plain
  • В ответ приходит добавочная часть url. В этот момент пользователь получает документ на подпись. Если подпись мобильная, вы можете сформировать ссылку вида https://server_name/signapi/sjson/добавочная_часть и открыть ее для отправки PUSH-уведомления. Если подпись серверная, вам нужно открывать ссылку вида https://server_name/signapi/sjson/добавочная_часть в браузере или iframe текущего окна для ввода логина и пароля для подписания.

• Error

  • Content-type text/plain
  • Коды ошибок

Внимание

При получении сообщения об ошибке не следует открывать с ним окно браузера

Подпись файла, передача через multipart/form-data

URL https://server_name/signapi/multipart

• Method POST
• Content-type multipart/form-data

Все ключи совпадают с sjson, только вместо filet нужно передавать файл в $_FILES["file"]

Подпись нескольких файлов

URL https://server_name/signapi/multijson/

Request

• Method POST
• Content-type application/json
• Body JSON
  • key = полученный ключ доступа
  • files = array of
    • filet = base64_encode( содержимое файла )
    • fname = имя файла
    • md5 = хеш содержимого для проверки
  • multiname = имя пакета для отображения в мобильном приложении
  • Идентификатор для определения подписанта файла:
  • user_email = email пользователя, подписывающего файл
  • user_ph = телефон пользователя, подписывающего файл
  • user_snils = СНИЛС пользователя, подписывающего файл
  • company_inn = ИНН компании, подписывающей файл
  • company_ogrn = ОГРН компании, подписывающей файл
  • company_kpp = КПП компании, подавать вместе с ИНН или ОГРН
  • Далее идут дополнительные параметры, которые не обязательно использовать:
  • url = адрес возврата после подписания
  • push_key = push_key = id ключа для отправки PUSH-уведомления в мобильное устройство, при переходе по которому сразу откроется экран подписания. Ключ должен быть мобильным, ID можно взять из АПИ "Сертификаты" - "Сертификаты пользователя"
  • noemail = 1, если нужно не высылать пользователю емеил
  • nopush = 1, если не нужно высылать пользователю push на устройство
  • forcesms = 1, если необходима двухфакторная авторизация при подписании серверный НКЭП
  • IF = 1, если необходимо уведомление на url-оповещения[^2] при каждом подписании [^3]

Response

• Success

  • Content-type text/plain
  • UUID (uuid1, строка 8-4-4-4-12 символов)В этот момент пользователь получает документ на подпись. Если подпись мобильная, вы можете сформировать ссылку вида https://server_name/signapi/multijson/UUID и открыть ее для отправки PUSH-уведомления. Если подпись серверная, вам нужно открывать ссылку вида https://server_name/signapi/multijson/UUID в браузере или iframe текущего окна для ввода логина и пароля для подписания.

• Error

  • Content-type text/plain
  • Коды ошибок

Проверка файла

URL https://server_name/signaturecheck/json Request

• Method POST
• Content-type application/json
• Body JSON
  • md5 = md5( содержимое файла )
  • Далее идут параметры, которые нужно передавать только для получения печатной формы (документ со штампом подписи):
  • filet = base64_encode( содержимое файла )
  • pdf = 1 - если подан filet и нужна печатная форма для поддерживаемых типов документов, на данный момент: *.pdf

Response

• Success
  • Content-type application/json
  • Body JSON
    • count
      • i - количество подписей
      • 0 - если файл не подписан
    • signature_i
      • value = base64_encode( значение подписи )
      • pkcs7 = web_link (Ссылка на скачивание pkcs7-контейнера)
      • pkcs64 = base64_encode( pkcs7 контейнер электронной подписи)
      • sigdate = дата подписи
      • timestamp = ссылка на метку доверенного времени
    • person
      • public_key = base64_encode( открытый ключ )
      • key_id = номер ключа
      • crt_id = номер сертификата
      • crt_status
        • 0 — действителен
        • 1 — ожидается
        • 2 — приостановлен
        • 3 — отозван
        • 4 — отсутствует
        • 5 — ошибка (чаще всего используются только 0 и 3)
      • cr_date = дата создания сертификата - dd.mm.yyyy
      • exp_date = дата истечения сертификата - dd.mm.yyyy
      • passport =
        • name = имя
        • lastname = отчество
        • surname = фамилия
      • phone_number = телефон
      • email_address = email
    • company если подпись от имени компании
      • name = название
      • inn = ИНН
      • ogrn = ОГРН
    • pdf = base64_encode(печатная форма если подан флаг pdf и файл filet)
• Error
  • Content-type application/json
  • Коды ошибок

Проверка файла через iframe

URL https://server_name/signaturecheck/request

Request

• Method POST
• Content-type application/json
• Body JSON
  • key = полученный ключ доступа
  • hash = md5( содержимое файла )

Response

• Success

  • Content-type text/plain
  • Ответ UUID (uuid1, строка 8-4-4-4-12 символов) Результаты проверки по адресам https://server_name/signaturecheck/result/UUID/1 страница в дизайне signme По этому адресу результат будет доступен для открытия только один раз. Для повторного открытия необходимо повторить процедуру повторно. https://server_name/signaturecheck/iframe/UUID javascript для отрисовки iframe

• Error

  • Content-type application/json
  • Коды ошибок

Проверка нескольких файлов через iframe

URL https://server_name/signaturecheck/multi

Request

• Method POST
• Content-type application/json
• Body JSON
  • key = полученный ключ доступа
  • files = array of
    • hash = md5( содержимое файла )
    • name = имя файла, необязательно

Response

• Success
  • Content-type text/plain
  • UUID (uuid1, строка 8-4-4-4-12 символов) Результаты проверки по адресам https://server_name/signaturecheck/result/UUID/1 страница в дизайне Sign.Me По этому адресу результат будет доступен для открытия только один раз. Для повторного открытия необходимо повторить процедуру повторно. https://server_name/signaturecheck/multiiframe/UUID javascript для отрисовки iframe
• Error
  • Content-type application/json
  • Коды ошибок

Быстрая проверка факта подписания запроса

URL https://server_name/signapi/check/добавочная_часть

Request

• Method GET

Response

• Success
  • Content-type application/json
  • Body JSON
    • status
      • "0" - не подписан
      • "1" - подписан
      • "2" - отклонен
      • "3" - файл удален
    • comment - причина отклонения, если есть
• Error
  • Content-type application/json
  • Коды ошибок

Быстрая проверка факта подписания нескольких файлов

URL https://server_name/signapi/multicheck/UUID

Request

• Method GET

Response

• Success
  • Content-type application/json
  • Body JSON
    • status
      • "0" - не подписан
      • "1" - подписан
      • "2" - отклонен
      • "3" - файл удален
      • "4" - подписаны не все файлы из запроса
    • comment” - причина отклонения, если есть
• Error
  • Content-type application/json
  • Коды ошибок

Отказ от подписи запроса

URL https://server_name/signapi/reject

Request

• Method POST
• Content-type application/json
• Body JSON
  • rid = id запроса (первая половина добавочной_части)
  • key = полученный ключ доступа
  • reason = текст причины отказа

Response

• Success
  • Content-type application/json
  • Body JSON
    • result = one of
    • already_rejected
    • already_signed
    • wrong_source
    • wrong_source_or_id
    • wrong_method
    • 0
    • date = дата отказа или подписания запроса(если already_rejected, already_signed или 0)
    • reason = причина отказа (если already_rejected или 0)
• Error
  • Content-type application/json
  • Коды ошибок

Отказ от подписи нескольких запросов

URL https://server_name/signapi/multireject/UUID

Request

• Method POST
• Content-type application/json
• Body JSON
• key = полученный ключ доступа
• reason = текст причины отказа

Response

• Success
  • Content-type application/json
  • Body JSON
    • result = one of
    • already_rejected
    • already_signed
    • wrong_source
    • wrong_source_or_id
    • wrong_method
    • 0
    • lastdate = дата отказа или подписания запроса для последнего файла из группы (если already_rejected, already_signed или 0)
    • lastreason = причина отказа для последнего файла из группы (если already_rejected или 0)
• Error
  • Content-type application/json
  • Коды ошибок

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

URL https://server_name/signaturecheck/precheck

Request

• Method POST
• Content-type application/json
• Body JSON
  • key = полученный ключ доступа
  • hash = хеш файла
  • user_id = идентификатор пользователя
  • company_id = идентификатор компании
  • key_id = идентификатор ключа подписания

Response

• Success
  • Content-type text/plain
  • Body TEXT
    • 1 - есть хотя бы одна подпись
    • 0 - нет подписей
• Error
  • Content-type text/plain
  • Body TEXT
    • 0 - при проверке произошла ошибка

Получение нескольких подписей по хешу файла

URL https://server_name/signaturecheck/get_pkcs/hash/[[filehash]]

Request

• Method GET

Response

• Success
  • Content-type application/json
  • Body JSON
    • signatures = array of
      • ссылка на pkcs контейнер подписи

Получение нескольких подписей по содержимому файла

URL https://server_name/signaturecheck/get_pkcs/file

Request

• Method POST
• Content-type multipart/form-data
• Body FORM
  • key = полученный ключ доступа
  • file = бинарное содержимое файла

Response

• Success
  • Content-type application/json
  • Body JSON
    • signatures = array of
      • ссылка на pkcs контейнер подписи

Получение групповой подписи по хешу файла

URL https://server_name/signaturecheck/get_grp_pkcs/hash/[[filehash]]/[[algorithm]]

Request

• Method GET
• Params
  • filehash - хеш подписанного файла
  • algorithm - алгоритм подписи. Может принимать одно из следующих значений:
    • 2 = ГОСТ-34.10-2012_256 УКЭП
    • 3 = ГОСТ-34.10-2012_512 УКЭП
    • 5 = ГОСТ-34.10-2012_256 НКЭП
    • 6 = ГОСТ-34.10-2012_512 НКЭП

Response

• Success
  • Content-type application/pkcs7-mime
  • Content-Disposition attachment

Получение групповой присоединенной подписи

URL https://server_name/signaturecheck/attach

Request

• Method POST
• Content-type multipart/form-data
• Body FORMDATA
  • key = полученный ключ доступа
  • file = бинарное содержимое файла

Response

• Success
  • Content-type application/pkcs7-mime
  • Content-Disposition attachment

Получение подписи в формате CADES T

URL https://server_name/signaturecheck/get_t_pkcs/hash/[[filehash]]/[[user_id]]

Request

• Method GET

Response

• Success
  • Content-type application/pkcs7-mime
  • Content-Disposition: attachment

Получение подписи в формате CADES XLT1

URL https://server_name/signaturecheck/get_xlt_pkcs/hash/[[filehash]]/[[user_id]] Request

• Method GET

Response

• Success
  • Content-type application/pkcs7-mime
  • Content-Disposition attachment

Сообщения об ошибках при подписи

HTTP status 200

• error 1: no file После раскодирования JSON пакета в нем не обнаружено элемента массива с ключем filet
• error 2: no filename После раскодирования JSON пакета в нем не обнаружено элемента массива с ключем fname
• error 3: wrong file Пришедшее в массиве содержимое по ключу filet не получается раскодировать base64_decode
• error 5: cant create file Не получается записать файл на сервер, возможно проблема в имени файла, иначе свяжитесь с разработчиками
• error 6: cant create request Не получается создать запрос на подпись файла на сервере - в любом случае свяжитесь с разработчиками
• error 6: wrong user phone или wrong user email Пользователь с таким номером телефона/email не зарегистрирован или не активирован
• error 6: wrong company inn или wrong company ogrn Компания с таким ИНН/ОГРН не зарегистрирована или не активирована
• error 7: get api key Апи ключ отсутствует или не найден в разрешенных

Сообщения об ошибках при проверке

HTTP status 200

• error 1: wrong base64 Пришедшее в запросе содержимое по ключу filet не получается раскодировать base64_decode
• error 2: wrong md5 Не получается вычислить md5 от раскодированного файла, свяжитесь с разработчиками
• error 3: wrong file Пришедшее в запросе содержимое по ключу filet не получается раскодировать base64_decode
• error 4: wrong hash Пришедшее в запросе значение md5 не совпадает с вычисленным на сервере
• error 5: no hash Значение md5 отсутствует в запросе

Сообщения об ошибках при запросе iframe

HTTP status 200

• error 1: wrong json Означает, что не получается раскодировать JSON пакет, пришедший в POST запросе
• error 2: wrong key Означает, что присланное значение в поле key не соответствует ключу для данной ИС, либо ИС не зарегистрирована
• error 3: wrong hash Означает, что md5 прислан в неправильном формате (не соответствует регулярному выражению a-zA-Z0-9, содержит недопустимые символы)
• error 4: request not created Не получается создать запрос на проверку файла на сервере - в любом случае свяжитесь с разработчиками

Возврат на url

Если указан url, то после подписи произойдет возврат на этот урл + добавочная часть вида ?signed=true или ?signed=false&error=%errno% (в случае, если в url уже есть символ ? часть будет начинаться с &)

errno

• 1 пароль неправильный
• 2 смс код неправильный
• 3 пользователь не имеет права подписывать
• 4 в компании стоит запрет первой подписи
• 5 запрос отклонен
• 6 внутренняя ошибка сервера, запишите точное время ошибки
• 7 попытка подписи от имени другой компании

Если url начинается с символов GET: (4 символа дословно), а далее идет сам url, например:

GET:https://test.sign.me/push

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

[^2]: url-оповещения задается один раз. Он сообщается сотрудникам Sign.Me [^3]: На url будет осуществляться GET запрос с параметрами 'apikey': ваш апи ключ, 'md5hash': md5 от содержимого файла, 'gosthash': ГОСТ 34.11 хеш от содержимого файла