API сервиса «Подпиши.Онлайн»

API загрузки документов в систему

API предназначено для автоматизированной загрузки документов из любой системы, которая генерирует электронные документы, требующие подписи.Загружаемые документы могут быть в любом удобном вам формате: txt, html, jpeg, doc, xls, docx, rtf, pdf или любые другие.

API позволяет:

загрузить документ в сервис для подписи
загрузить подписанный документ в сервис
проверить статус документа
загрузить подписи документа
загрузить входящие документы
подписать входящие документы

Кодировка текстовых полей воспринимается только как «UTF-8»

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

Входные параметры передаются только методом POST по адресу http://www.podpishi.kz/api.php или https://www.podpishi.kz/api.php в следующем составе:

login - ваш логин (email) в сервисе «Подпиши Онлайн», пример «some@email.com» (текстовое поле, не более 30 символов) – обязательное поле

apikey – ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример «7588ca38acc4ef76149caa0b0c115d94» (текстовое поле, 32 символа) – обязательное поле

nametxt – текстовое название документа,по которому вам будет удобно опознавать или искать документ, пример «Акт выполненных работ № 15 от 02/07/2017 ТОО Фирма (БИН 191919020202)» (текстовое поле, не более 250 символов) – необязательное поле. См. «Советы разработчику».

uniq_reference – уникальный номер документа, который присвоен документу внутри вашей компании, пример «A541158-ED» (текстовое поле, не более 100 символов) – необязательное поле. См. «Советы разработчику».

pack_reference – номер пакета, в состав которого может входить указанный документ, пример «2155881» (числовое поле, BIGINT) – необязательное поле. См. «Советы разработчику».

owner_bin – номер БИН вашей организации, от имени которой выставляется загружаемый документ на подпись, пример «169999070809» (текстовое поле, 12 цифровых символов) – обязательное поле.

receiver_bin – номер БИН организации, которая должна подписать загружаемый документ , пример «191919020202» (текстовое поле, 12 цифровых символов) – обязательное поле.

type_delegate – объем прав, которые вы разрешаете вашему партнеру производить с документом:
1 – разрешение просмотреть и подписать документ
2 – разрешение только просмотреть документ
(числовое поле, 1 символ) – обязательное поле.

receiver_mail – емейл получателя документа, на который будет отослано уведомление о необходимости подписи загруженного документа, пример «some@email2.com» (текстовое поле, не более 30 символов) – обязательное поле.

uf - загружаемый(е) файл(ы) – документ, который загружается в сервис

signature_pem - ЭЦП документа в base64-encoded формате (необязательный параметр)
«Подпиши Онлайн». См. «Советы разработчику».

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

В случае успешной загрузки документа будет возвращён XML-код следующего содержания:

<?xml version="1.0" encoding="UTF-8"?>
<resp err="no">
<doc num='31' reference='nkdyddddwd4' package='201707' nametxt='Новый документ' filetxt='Новый документ'>ok</doc>
</resp>

где поле <doc>ok</doc> означает успешную загрузку документа в сервис и аттрибут num=’31’ содержит уникальный номер документ в рамках в сервисе «Подпиши Онлайн».

В случае ошибки во время обработки загруженного документа будет возвращен XML-код следующего содержания:

<?xml version="1.0" encoding="UTF-8"?>
<resp err="no">
<doc num='' reference='nkdyddddwd4' package='201707' nametxt='Новый документ' filetxt='Новый офигенный документ' errtxt='Document already exist at DB'>err</doc>
</resp>

где поле <doc></doc> содержит тип ошибки, а аттрибут num=’’ содержит пустое значение уникального номера документа.

В случае ошибки во время обработки входных параметров будет возвращен XML-код следующего содержания:

<?xml version="1.0" encoding="UTF-8"?>
<resp err="yes">
<status>0</status>
<errdesc>Authorization error (code=0)</errdesc>
</resp>

Советы разработчику

Hint 1. При передаче поля «nametxt» удобно указывать тип документа и дату, а также название фирмы-партнера и БИН фирмы-партнера, которая должна подписать загруженный документ - тогда в случае необходимости будет удобно искать документ в интерфейсе сервиса «Подпиши Онлайн».

Hint 2. В поле «uniq_reference» удобно указывать поле из нескольких частей или секций– например 1С-5D43844, где первая часть обозначает, что документ был загружен из системы 1С, а вторая чаcть уникальный номер документа внутри 1С, или например [IT][17][DS22zwQ], где первая часть – обозначение департамента, вторая часть – номер сотрудника, который формировал документ, третья часть – номер документа внутри департамента. Поле «uniq_reference» должно быть уникальным, при загрузке документа с «uniq_reference», который был использован ранее, система выдаст ошибку.

Hint 3. В поле «pack_reference» указывается числовой код, по которому можно найти документ. Например, вы загружаете в сервис 6000 актов выполненных работ за июнь 2017 года, указав в поле «pack_reference» значение «201706». Или вы можете каждый документ, который отправляете в сервис на подпись, присваивать уникальный цифровой номер перед отправкой, а после получения от сервиса уникального регистрационного номера из поля num=’’ сопоставлять номер внутри вашей системы с внешним номером документа внутри сервиса, чтобы в дальнейшем по внешнему уникальному номеру документа запрашивать статус документа.

Hint 4. Образец программного кода на php с использованием модуля curl для загрузки документа в сервис:

$upload = '/путь/к/вашему/файлу/file.xls';

$postdata = array(
'login' => 'some@email.com',
'apikey' => '7588ca38acc4ef76149caa0b0c115d94',
'nametxt' => 'Новый документ',
'uniq_reference' => '(SECTRETAR)(20170629)(LETTER-2948)',
'pack_reference' => '201707',
'owner_bin' => '169999070809',
'receiver_bin' => '191919020202',
'type_delegate' => '1',
'receiver_mail' => ' some@email2.com',
'uf' => "@".$upload
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://www.podpishi.kz/api.php');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postdata);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 30);
$answer = curl_exec($ch);
curl_close($ch);

echo $answer;

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

При успешной загрузке документов в систему в ответ возвращается уникальный идентификатор документа в рамка всего сервиса «Подпиши Онлайн». Этот идентификатор необходимо использовать при запросе статуса документа

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

Входные параметры передаются только методом POST по адресу http://www.podpishi.kz/apistatus.php или https://www.podpishi.kz/apistatus.php в следующем составе:

login - ваш логин (email) в сервисе «Подпиши Онлайн», пример «some@email.com» (текстовое поле, не более 30 символов) – обязательное поле

command – xml-код, закодированный в base64-кодировке, имеющий следующую структуру:

<data>
<oper>getstatus</oper>
<docuniq></ docuniq > - уникальный номер документа в сервисе «Подпиши Онлайн»
…….
<docuniq></ docuniq > - уникальный номер документа в сервисе «Подпиши Онлайн»
<time></time> - время создания запроса в виде 20150130162514
</data>

В ответ система вернет xml-код, содержащий следующие данные:

<?xml version="1.0" encoding="UTF-8"?>
<resp err="no" command="getstatus">
<docnum>
<id>2</id>
<signinfo>
<permission i='' is_own_doc='' created='' signed_type='' must_signed_by_bin='' signed='' signed_bin='' signed_fio='' signed_firm='' signed_policy='' signed_date='' sign_deleted='' /></signinfo>
</docnum>
</resp>

Список атрибутов:

id - уникальный номер документа в сервисе «Подпиши Онлайн»,

i – внутренний индекс документа (целое число)

is_own_doc – признак принадлежности документа (1 - собственный документ, 0 - входящий документ)

created – дата создания документа в системе

signed_type – тип делегирования подписи (1 - владелец документа, 2 - документ делегирован на подпись, 3 - документ делегирован на просмотр)

must_signed_by_bin – БИН, от имени которого должен быть подписан документ

signed – 0/1 – статус документа: 0 - не подписан, 1 – подписан

signed_bin – БИН подписавшего документ

signed_fio – ФИО подписавшего документ

signed_firm – Название компании, подписавшей документ

signed_policy – тип права подписи (1 - Первый руководитель предприятия, 2 - Сотрудник с правом подписи, 3-5 - прочие сотрудники.)

signed_date – дата получения подписи документа

sign_deleted – признак удаления документа

API получения списка доступных документов в системе.

Система по данной команде позволяет получить список доступных документов. Команда используется для сверки собственных документов в сервисе со списком документов на стороне клиента, а так же для получения входящих документов, которые были направлены вам через сервис вашими партнерами.

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

command – xml-код, закодированный в base64-кодировке, имеющий следующую структуру:

<data>
<oper>getlistdocs</oper>
<time1></time1> - дата начала периода выборки документов, в виде 20170825162514
<time2></time2> - дата окончания периода выборки документов, в виде 20170830235959
<owner_bin></owner_bin> - БИН компании, для которой запрашивается список документов, при отсутствии берется БИН текущего шаблона
<time></time> - время создания запроса в виде 20170902162514
</data>

В ответ система вернет xml-код, содержащий следующие данные:

<?xml version="1.0" encoding="UTF-8"?>
<resp err="no" command="getlistdocs">
<permission id='' i='' api_reference='' name='' is_own_doc='' created='' signed_type='' must_signed_by_bin='' signed='0' signed_bin='' signed_fio='' signed_firm='' signed_policy='0' signed_date='' sign_deleted='0' />
</resp>

Список атрибутов аналогичен аттрибутам ответа в предыдущей команде, дополнительно используются следующие параметры:

api_reference - референс документа, используемый при загрузке документа в систему через API

name – имя документа, отображаемое внутри личного кабинета.

API получения количества доступных к загрузке документов.

Система по данной команде позволяет получить количество документов, которые доступны пользователю к загрузке.

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

command – xml-код, закодированный в base64-кодировке, имеющий следующую структуру:

<data>
<oper>getavailabledocs</oper>
<owner_bin></owner_bin> - БИН компании, для которой запрашивается количество документов, при отсутствии берется БИН текущего шаблона
<time></time> - время создания запроса в виде 20170902162514
</data>

В ответ система вернет xml-код, содержащий следующие данные:

<?xml version="1.0" encoding="UTF-8"?>
<resp err="no" command="getavailabledocs" counts=""></resp>

В поле counts будет возвращено количество документов, доступных к загрузке в системе. Значение может быть отрицательным.

API создания счета на оплату тарифного плана.

Система по данной команде позволяет создать счет на оплату для дополнительного количества документов для случаев, когда пользователь исчерпал доступное к загрузке количество документов.

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

command – xml-код, закодированный в base64-кодировке, имеющий следующую структуру:

<data>
<oper>getcreateinvoice</oper>
<tarif></tarif> - номер тарифного плана, берется из команды gettarifplan
<owner_bin></owner_bin> - БИН компании, для которой запрашивается количество документов, при отсутствии берется БИН текущего шаблона
<time></time> - время создания запроса в виде 20170902162514
</data>

В ответ система вернет xml-код, содержащий следующие данные:

<?xml version="1.0" encoding="UTF-8"?>
<resp err="no" command="getcreateinvoice" ></resp>

В результате этой команды будет создан электронный документ, который будет содержать простой счет на оплату по выбранному тарифному плану. После получения положительного ответа на команду создания счета имеет смысл проверить входящие документы и загрузить с сервера уже подписанный с помощью ЭЦП счет от сервиса.

API получения списка тарифных планов.

Система по данной команде позволяет получить список тарифных планов, которые доступны пользователю для выписки счета на дополнительное количество документов.

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

command – xml-код, закодированный в base64-кодировке, имеющий следующую структуру:

<data>
<oper>gettarifplan</oper>
<time></time> - время создания запроса в виде 20170902162514
</data>

В ответ система вернет xml-код, содержащий следующие данные:

<resp err='no' command='gettarifplan'>
<tarif></tarif><name></name><counts></counts><price></price>
...
<tarif></tarif><name></name><counts></counts><price></price>
</resp>
где
<tarif></tarif> - номер тарифного плана
<name></name> - название тарифного плана
<counts></counts> - количество документов в тарифном плане
<price></price> - стоимость тарифного плана

API получения документа из личного кабинета.

Система по данной команде позволяет загрузить физический документ, как собственный документ, так и документ, который был прислан от партнера.

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

command – xml-код, закодированный в base64-кодировке, имеющий следующую структуру:

<data>
<oper>getdoc</oper>
<docnum></docnum> - уникальный номер документа в сервисе «Подпиши Онлайн»
<time></time> - время создания запроса в виде 20150130162514
</data>

В ответ система вернет архив в формате .ZIP, который будет содержать запрашиваемый файл и файлы подписей для этого документа.

API добавления ЭЦП к документу.

Система по данной команде позволяет загрузить ЭЦП к любому неподписанному документу из личного кабинета, который требует подписи.

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

command – xml-код, закодированный в base64-кодировке, имеющий следующую структуру:

<data>
<oper>addsignature</oper>
<docnum></docnum> - уникальный номер документа в сервисе «Подпиши Онлайн»
<indexnum></indexnum> - внутренний индекс документа
<signature_pem></signature_pem> - ЭЦП документа в base64-encoded формате
<time></time> - время создания запроса в виде 20150130162514
</data>

В ответ система вернет результат отсутствия ошибки при добавлении подписи к документу:

<?xml version="1.0" encoding="UTF-8"?>
<resp err="no" command="addsignature">
</resp>

API удаления права подписи ЭЦП к документу.

Система по данной команде позволяет удалить право подписи для неподписанного документа из личного кабинета, который требует подписи.

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

command – xml-код, закодированный в base64-кодировке, имеющий следующую структуру:

<data>
<oper>delpermission</oper>
<docnum></docnum> - уникальный номер документа в сервисе «Подпиши Онлайн»
<indexnum></indexnum> - внутренний индекс документа
<time></time> - время создания запроса в виде 20150130162514
</data>

В ответ система вернет результат отсутствия ошибки при удалении права подписи к документу:

<?xml version="1.0" encoding="UTF-8"?>
<resp err="no" command="delpermission">
</resp>

API добавления партнером тарифного плана на клиента.

Система по данной команде позволяет добавить клиенту количество документов в соответствии с тарифным планом, который оплатил клиент.

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

command – xml-код, закодированный в base64-кодировке, имеющий следующую структуру:

<data>
<oper>addpackage2client</oper>
<refnum></refnum> - уникальный номер распоряжения на стороне партнера, целое число
<bin2client></bin2client> - БИН клиента. которому зачисляется пакет
<packet></packet> - номер тарифного пакета, целое число (из команды gettarifplan).
<time></time> - время создания запроса в виде 20150130162514
</data>

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

<?xml version="1.0" encoding="UTF-8"?>
<resp err="no" command="addpackage2client">
</resp>

API получения списка транзакций на добавление партнером тарифных планов.

Система по данной команде позволяет партнеру получить за указанный период информацию о том, сколько партнер добавил документов и для какого БИН. Команда предназначена для сверки транзакций партнера между партенром и сервером.

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

command – xml-код, закодированный в base64-кодировке, имеющий следующую структуру:

<data>
<oper>getlistpartnertrn</oper>
<owner_bin></owner_bin> - БИН партнера, на который заключен партнерский договор (если в аккаунте партнера существует более одного шаблона ЭЦП)
<time1></time1> - дата начала периода выборки документов, в виде 20170825162514
<time2></time2> - дата окончания периода выборки документов, в виде 20170830235959
<time></time> - время создания запроса в виде 20150130162514
</data>

В ответ система вернет листинг транзакций за указанный период:

<?xml version="1.0" encoding="UTF-8"?>
<resp err="no" command="getlistpartnertrn">
<id></id><bin2client></bin2client><date></date><count></count><refnum></refnum>
...
<id></id><bin2client></bin2client><date></date><count></count><refnum></refnum>
</resp>
, где

<id></id> - номер транзакции
<bin2client></bin2client> - БИН клиента, для которого было зачисление документов
<date></date> - дата операции, в виде 20170830235959
<count></count> - количество зачисленных документов, целое число
<refnum></refnum> - уникальный номер распоряжения на стороне партнера, целое число

API блокировки возможности добавления клиентом новых документов в сервисе.

Система по данной команде позволяет партнеру заблокировать для клиента возможность добавления документов в систему. Применяется в случае, если клиент запросил у партнера возврат остатка по услуге и приостанавливает пользование услугами сервиса.

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

command – xml-код, закодированный в base64-кодировке, имеющий следующую структуру:

<data>
<oper>setblockuser</oper>
<owner_bin></owner_bin> - БИН партнера, на который заключен партнерский договор (если в аккаунте партнера существует более одного шаблона ЭЦП)
<bin2client></bin2client> - БИН клиента. который будет заблокирован, если данный клиент ранее зарегистрирован партнером
<time></time> - время создания запроса в виде 20150130162514
</data>

В ответ система вернет результат успешного выполнения команды:

<?xml version="1.0" encoding="UTF-8"?>
<resp err="no" command="setblockuser">
</resp>

API регистрации партнером клиентского аккаунта в сервисе.

Система по данной команде позволяет партнеру зарегистировать клиента в сервисе. Применяется в случае, если партнер настроил регистрацию клиентов на своей стороне.

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

command – xml-код, закодированный в base64-кодировке, имеющий следующую структуру:

<data>
<oper>reguserbypartner</oper>
<email></email> - емейл клиента, который будет зарегистрирован
<remoteid></remoteid> - порядковый номер клиента в системе партнера, целое число
<owner_bin></owner_bin> - БИН партнера, на который заключен партнерский договор (если в аккаунте партнера существует более одного шаблона ЭЦП)
<time></time> - время создания запроса в виде 20150130162514
</data>

В ответ система вернет результат успешного выполнения команды:

<?xml version="1.0" encoding="UTF-8"?>
<resp err="no" command="reguserbypartner">
<flag_newreg></flag_newreg> - флаг осуществления регистрации пользователя 0/1 (0 - регистрация не осуществлялась, 1 - была создана новая регистрация)
<partner_owner></partner_owner> - флаг принадлежности регистрации клиента партнеру 0/1 (0 - клиент регистрировался не через партнера, 1 - клиент был зарегистирован партнером)
<serviceid></serviceid> - уникальный порядковый номер клиента в сервисе, целое число
</resp>

Если партнер пытается сделать регистрацию клиента, который уже был ранее зарегистрирован партнером с такими параметрами - система вернет данные ранней регистрации.

API удаленной авторизации клиента через систему партнера.

Система по данной команде позволяет партнеру получить авторизационную сессию для клиента партнера, после чего переадресовать клиента в сервис с полученными данными авторизации.

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

command – xml-код, закодированный в base64-кодировке, имеющий следующую структуру:

<data>
<oper>authuserbypartner</oper>
<serviceid></serviceid> - уникальный порядковый номер клиента в сервисе, целое число
<remoteid></remoteid> - уникальный порядковый номер клиента в системе партнера, целое число
<userip></userip> - ip клиента, который будет авторизован
<owner_bin></owner_bin> - БИН партнера, на который заключен партнерский договор (если в аккаунте партнера существует более одного шаблона ЭЦП)
<time></time> - время создания запроса в виде 20150130162514
</data>

В ответ система вернет результат успешного выполнения команды:

<?xml version="1.0" encoding="UTF-8"?>
<resp err="no" command="authuserbypartner">
<sessid></sessid> - номер сессии, целое число
<sesspass></sesspass> - пароль сессии, текстовая строка
<serviceid></serviceid> - уникальный порядковый номер клиента в сервисе, целое число
</resp>