API загрузки документов в систему
API предназначено для автоматизированной загрузки документов из любой системы, которая генерирует электронные документы, требующие подписи. Загружаемые документы могут быть в любом удобном вам формате: txt, html, jpeg, doc, xls, docx, rtf, pdf или любые другие.
API позволяет:
- загрузить документ в сервис для подписи;
- загрузить подписанный документ в сервис;
- проверить статус документа;
- загрузить подписи документа;
- загрузить входящие документы;
- подписать входящие документы.
Кодировка текстовых полей воспринимается только как UTF-8.
Содержание
- ЗАГРУЗКА ДОКУМЕНТА: Входные параметры
- ЗАГРУЗКА ДОКУМЕНТА: Выходные параметры
- Советы разработчику
- Тестовая среда
- НАБОР ГОТОВЫХ СКРИПТОВ ДЛЯ УСТАНОВКИ НА САЙТ
- Постановка задачи для написания модуля
- API получение статуса документа в системе
- API получения списка доступных документов в системе
- API получения количества доступных к загрузке документов
- API создания счета на оплату тарифного плана
- API получения списка тарифных планов
- API получения документа из личного кабинета
- API добавления ЭЦП к документу
- API добавления права подписи ЭЦП к документу
- API удаления права подписи ЭЦП к документу
- API добавления партнером тарифного плана на клиента
- API получения списка транзакций на добавление партнером тарифных планов
- API блокировки возможности добавления клиентом новых документов в сервисе
- API регистрации партнером клиентского аккаунта в сервисе
- API удаленной авторизации клиента через систему партнера
- API регистрации QR-кода для добавления в документ клиента до его подписи.
- API создания предоплаченного кода.
- API получения списка созданных предоплаченных кодов.
- API создания ссылки на подписание документа
- API получения расширенных данных из подписанного документа
- API повторной отправки кода согласия на GSM-номер
- API создания ссылки на подписание нескольких документов через SMS
ЗАГРУЗКА ДОКУМЕНТА: Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/api.php или https://api.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 цифровых символов), пример для номера телефона+77050000000(знак "+" и 11 цифр);
- type_delegate обязательное поле
- объем прав, которые вы разрешаете вашему партнеру производить с документом:
1— разрешение просмотреть и подписать документ;2— разрешение только просмотреть документ;
(числовое поле, 1 символ);
- receiver_mail необязательное поле
- емейл получателя документа, на который будет отослано уведомление о необходимости подписи загруженного документа (текстовое поле, не более 50 символов);
- uf
- загружаемый(е) файл(ы) — документ, который загружается в сервис;
- signature_pem необязательное поле
- ЭЦП документа в base64-encoded формате «Подпиши.Онлайн». См. «Советы разработчику».
- preregid необязательное поле
- Номер предварительной регистрации документа в системе «Подпиши.Онлайн» - идентификатор id1 из команды reglink4qrcode. См. «API регистрации QR-кода для добавления в документ клиента до его подписи».
- ownernosign необязательное поле
- флаг указания системе поставить владельцу документа только право ознакомления с документом без необходимости подписи в системе «Подпиши.Онлайн» (0/1).
- qrparse необязательное поле
- Указание системе вставить QR-код в загружаемый документ. Правила добавления QR доступны по ссылке.
- nosendgsmmsg необязательное поле
- Указание системе не отсылать SMS при делегировании документа на мобильный номер.
ЗАГРУЗКА ДОКУМЕНТА: Выходные параметры
Успешная загрузка
В случае успешной загрузки документа будет возвращён 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://api.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;Тестовая среда
Тестовая среда доступна по адресу
https://testzone.podpishi.kz/authbykey.phpУсловия работы тестовой среды:
- Общее количество возможных документов - 300 штук, при превышении лимита обратитесь в поддержку;
- Раз в неделю в понедельник утром все загруженные документы удаляются;
- размер документа не может превышать 200 килобайт;
- при проверке тестовой подписи система всегда считает тестовые сертификаты валидными, даже если они отозваны или закончился их срок;
Пароль на все сертификаты: Qwerty12, архив с тестовыми сертификатами доступен к загрузке по ссылке
К содержаниюНабор готовых скриптов для установки на сайт
Готовые решения помогут быстро настроить все этапы заключения договора:
- ввод данных клиентом;
- проверка введенных данных;
- проверка текста договора, который подписывает клиент;
- формирование договора и счета на оплату в электронном виде;
- подпись документа на сайте с помощью ключа ЭЦП владельца сайта;
- загрузка сформированного документа в сервис «Подпиши.Онлайн» для подписи договора партнером.
🕐 Время установки: 3–5 минут.
Узнайте больше:
- Настройка PHP-скриптов. Краткое руководство
- Скриншоты процесса заключения договора
- Живая демонстрация заключения договора
Постановка задачи для модульной интеграции
Если вы хотите написать модуль для внутренних нужд под конкретную систему - вы можете использовать как каркас постановку задачи, которую мы использовали для написания модуля 1С, это поможет вам формализовать требования к вашему продукту
К содержаниюAPI получение статуса документа в системе
При успешной загрузке документов в систему в ответ возвращается уникальный идентификатор документа в рамка всего сервиса «Подпиши.Онлайн». Этот идентификатор необходимо использовать при запросе статуса документа
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- 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='' smslinkhash='' /></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
- признак удаления документа.
- smslinkhash
- хэш-параметр для создания ссылки на смс-подписание, если документ предусматривает данную опцию, формат ссылки
http://api.podpishi.kz/sms.php?q={smslinkhash}
API получения списка доступных документов в системе
Система по данной команде позволяет получить список доступных документов. Команда используется для сверки собственных документов в сервисе со списком документов на стороне клиента, а так же для получения входящих документов, которые были направлены вам через сервис вашими партнерами.
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- 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 получения количества доступных к загрузке документов
Система по данной команде позволяет получить количество документов, которые доступны пользователю к загрузке.
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- 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 создания счета на оплату тарифного плана
Система по данной команде позволяет создать счет на оплату для дополнительного количества документов для случаев, когда пользователь исчерпал доступное к загрузке количество документов.
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- 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 получения списка тарифных планов
Система по данной команде позволяет получить список тарифных планов, которые доступны пользователю для выписки счета на дополнительное количество документов.
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- command
- xml-код, закодированный в base64-кодировке, имеющий следующую структуру:
<data> <oper>gettarifplan</oper> <time></time> <!-- время создания запроса в виде 20170902162514 --> </data>
В ответ система вернет xml-код, содержащий следующие данные:
<?xml version="1.0" encoding="UTF-8"?>
<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 получения документа из личного кабинета
Система по данной команде позволяет загрузить физический документ, как собственный документ, так и документ, который был прислан партнером.
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- command
- xml-код, закодированный в base64-кодировке, имеющий следующую структуру:
<data> <oper>getdoc</oper> <docnum></docnum> <!-- уникальный номер документа в сервисе «Подпиши.Онлайн» --> <visualoff>0</visualoff> <!-- признак необходимости формирования архива без визуальной версии документа, допустимые значения: 0/1, по умолчанию 1 --> <needlang></needlang> <!-- в случае, если visualoff=1 - указывает язык формирования информации о подписях, допустимые значения: RU/KZ/UA --> <time></time> <!-- время создания запроса в виде 20150130162514 --> </data>
В ответ система вернет архив в формате .ZIP, который будет содержать запрашиваемый файл и файлы подписей для этого документа.
К содержаниюAPI добавления ЭЦП к документу
Система по данной команде позволяет загрузить ЭЦП к любому неподписанному документу из личного кабинета, который требует подписи.
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- 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 добавления права подписи к документу
Система по данной команде позволяет добавить право подписи к любому документу из личного кабинета, который требует подписи.
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- command
- xml-код, закодированный в base64-кодировке, имеющий следующую структуру:
<data> <oper>addpermission</oper> <docnum></docnum> <!-- уникальный номер документа в сервисе «Подпиши.Онлайн» --> <type_delegate></type_delegate> <!-- объем прав (из команды добавления документа) --> <receiver_bin></receiver_bin> <!-- БИН/ИИН лица, которое должно подписать документ --> <receiver_mail></receiver_mail> <!-- email лица, которое должно подписать документ --> <senddoc2bin></senddoc2bin> <!-- признак отправки документа только на БИН/ИИН (из команды добавления документа) --> <time></time> <!-- время создания запроса в виде 20150130162514 --> </data>
В ответ система вернет результат отсутствия ошибки при добавлении подписи к документу:
<?xml version="1.0" encoding="UTF-8"?>
<resp err="no" command="addpermission">
</resp>API удаления права подписи ЭЦП к документу
Система по данной команде позволяет удалить право подписи для неподписанного документа из личного кабинета, который требует подписи.
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- 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 добавления партнером тарифного плана на клиента
Система по данной команде позволяет добавить клиенту количество документов в соответствии с тарифным планом, который оплатил клиент.
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- 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 получения списка транзакций на добавление партнером тарифных планов
Система по данной команде позволяет партнеру получить за указанный период информацию о том, сколько партнер добавил документов и для какого БИН. Команда предназначена для сверки транзакций партнера между партенром и сервером.
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- 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 блокировки возможности добавления клиентом новых документов в сервисе
Система по данной команде позволяет партнеру заблокировать для клиента возможность добавления документов в систему. Применяется в случае, если клиент запросил у партнера возврат остатка по услуге и приостанавливает пользование услугами сервиса.
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- 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 регистрации партнером клиентского аккаунта в сервисе
Система по данной команде позволяет партнеру зарегистировать клиента в сервисе. Применяется в случае, если партнер настроил регистрацию клиентов на своей стороне.
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- 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 удаленной авторизации клиента через систему партнера
Система по данной команде позволяет партнеру получить авторизационную сессию для клиента партнера, после чего переадресовать клиента в сервис с полученными данными авторизации.
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- 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>API регистрации QR-кода для добавления в документ клиента до его подписи.
Система по данной команде создает уникальные идентификаторы, с помощью которых будет сформирован QR-код для дальнейшего использования в документе, который будет создан и загружен для подписи в систему Подпиши.
Порядок использования:
- получение регистрационных идентификаторов id1 и id2
- создание уникальной ссылки для QR-кода по формату: http://api.podpishi.kz/qr.php?id1=id1&id2=id2
- создание QR-кода с полученной уникальной ссылкой
- вставка полученного изображения QR-кода в документ, который будет подписываться и загружаться в сервис «Подпиши.Онлайн»
- загрузка документа в сервис «Подпиши.Онлайн» через API с ОБЯЗАТЕЛЬНЫМ указанием параметра preregid, значение которого равно id1.
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- command
- xml-код, закодированный в base64-кодировке, имеющий следующую структуру:
<data> <oper>reglink4qrcode</oper> <time></time> <!-- время создания запроса в виде 20150130162514 --> </data>
В ответ система вернет результат отсутствия ошибки и регистрационные идентификаторы для создания QR-кода
<?xml version="1.0" encoding="UTF-8"?>
<resp err="no" command="reglink4qrcode">
</resp><id1>148554</id1><id2>2a3a436c50b418d9eca1e90071cab76b</id2>API создания предоплаченного кода.
Система по данной команде создает предоплаченный код, который можно выдать клиенту для пополнения баланса доступных документов.
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- command
- xml-код, закодированный в base64-кодировке, имеющий следующую структуру:
<data> <oper>createvouchercode</oper> <tarif>2</tarif> <!-- номер тарифного плана --> <vouchertype>1</vouchertype> <!-- тип ваучера (1/2) --> <voucherref>24</voucherref> <!-- уникальный референс команды на получение ваучера, целое число --> <time></time> <!-- время создания запроса в виде 20150130162514 --> </data>
В ответ система вернет номер вачера и пин-код ваучера
<?xml version="1.0" encoding="UTF-8"?>
<resp err="no" command="createvouchercode">
</resp><voucher_num>14855</voucher_num><voucher>ZATKM-KR1ZZ-HRP9L-KBEUU-1WWTF-8CBZJ</voucher>API получения списка созданных предоплаченных кодов.
Система по данной команде вернет список ваучеров, созданных партнером за указанный период
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- command
- xml-код, закодированный в base64-кодировке, имеющий следующую структуру:
<data> <oper>getlistvouchercode</oper> <time1></time1> <!-- дата начала периода выборки документов, в виде 20170825162514 --> <time2></time2> <!-- дата окончания периода выборки документов, в виде 20170830235959 --> <time></time> <!-- время создания запроса в виде 20150130162514 --> </data>
В ответ система вернет результат отсутствия ошибки и список ранее созданных ваучеров.
<?xml version="1.0" encoding="UTF-8"?>
<resp err="no" command="getlistvouchercode">
</resp>
<vouchers>
<v><d>20191218161237</d><r>24</r><num>14855</num><pin>ZATKM-KR1ZZ-HRP9L-KBEUU-1WWTF-8CBZJ</pin><c>1000</c><s>99000</s><pd>30</pd><t>1</t><e>0</e></v>
<v><d>20191219090654</d><r>25</r><num>14896</num><pin>VVVKM-421YY-48MKL-HFUGG-FFF56-AAPB7</pin><c>1000</c><s>99000</s><pd>30</pd><t>1</t><e>0</e></v>
</vouchers>
API создания ссылки для подписания одного документа
Система по данной команде позволяет создать ссылку для подписания документа без входа в личный кабинет.
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- command
- xml-код, закодированный в base64-кодировке, имеющий следующую структуру:
<data> <oper>add4imerchantsign</oper> <docnum></docnum> <!-- уникальный номер документа в сервисе «Подпиши.Онлайн» --> <indexnum></indexnum> <!-- внутренний индекс документа --> <returnurl></returnurl> <!-- ссылка возврата пользователя после подписания --> <time></time> <!-- время создания запроса в виде 20150130162514 --> </data>
В ответ система вернет параметры сессии, которые надо будет указать при формировании ссылки на подписание документа:
<?xml version="1.0" encoding="UTF-8"?>
<resp err="no" command="add4imerchantsign">
<id1></id1> <!-- номер сессии -->
<id2></id2> <!-- пароль сессии -->
</resp>Полученные данные вы используете для переадрессации клиента на ссылку:
https://api.podpishi.kz/apisignmerchant.php?session_id=$id1&session=$id2&sign=$sign
где
- sign обязательное поле
- md5-хэш из трех параметров id1.id2.apikey (apikey - ваш ключ для API-операций).
API получения расширенных данных из подписанного документа
Система по данной команде позволяет получить в XML-формате все данные подписанта, которые он ввел во время заполнения шаблона документа.
Формат предоставялемых данных: xml-код, который запакован в base64-кодировку.
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- command
- xml-код, закодированный в base64-кодировке, имеющий следующую структуру:
<data> <oper>getextendedinfo</oper> <docnum></docnum> <!-- уникальный номер документа в сервисе «Подпиши.Онлайн» --> <time></time> <!-- время создания запроса в виде 20150130162514 --> </data>
В ответ система вернет параметры данных, введенных клиентом:
<?xml version="1.0" encoding="UTF-8"?>
<resp err="no" command="getextendedinfo">
<extdata></extdata> <!-- данные xml в base64 -->
</resp>API повторной отправки кода согласия на GSM-номер
Система по данной команде повторно отправляет код согласия на GSM-номер, указанный при делегировании документа.
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- command
- xml-код, закодированный в base64-кодировке, имеющий следующую структуру:
<data> <oper>resend_gsm_msg</oper> <docnum></docnum> <!-- уникальный номер документа в сервисе «Подпиши.Онлайн» --> <indexnum></indexnum> <!-- внутренний индекс документа --> <time></time> <!-- время создания запроса в виде 20150130162514 --> </data>
В ответ система вернет результат отсутствия ошибки при инициировании отправки:
<?xml version="1.0" encoding="UTF-8"?>
<resp err="no" command="resend_gsm_msg">
</resp>API создания ссылки на подписание нескольких документов через SMS
Система по данной команде создает ссылку на подписание нескольких документов через SMS и отправляет ссылку в SMS-сообщении на телефон с кодом согласия. Все документы ранее должны быть уже делегированы для согласия на введенный номер телефона при создании документа в системе.
Входные параметры
Входные параметры передаются только методом POST по адресу http://api.podpishi.kz/apistatus.php или https://api.podpishi.kz/apistatus.php в следующем составе:
- login обязательное поле
- ваш логин (email) в сервисе «Подпиши.Онлайн», пример
some@email.com(текстовое поле, не более 30 символов);
- apikey обязательное поле
- ключ для API-операций, который находится в личном кабинете в разделе «Управление», пример
7588ca38acc4ef76149caa0b0c115d94(текстовое поле, 32 символа);
- command
- xml-код, закодированный в base64-кодировке, имеющий следующую структуру:
<data> <oper>add4imerchantsigSMSnmulti</oper> <doc_for_sign></doc_for_sign> <!-- список номеров в документов в сервисе «Подпиши.Онлайн» --> <phone></phone> <!-- номер телефона для отправки кода согласия --> <time></time> <!-- время создания запроса в виде 20150130162514 --> </data>
Список номеров документов представляет собой секции, разделенные знаком ';', где секция состоит их двух частей, соединенных знаком подчеркивания. Первая часть - уникальный номер документа <docnum>, вторая часть - внутренний индекс документа <indexnum>, пример:
54_5481;58_5502В ответ система вернет результат отсутствия ошибки при инициировании отправки:
<?xml version="1.0" encoding="UTF-8"?>
<resp err="no" command="add4imerchantsigSMSnmulti">
</resp>