Как использовать everSign eSignature SAAS Document Management PHP API - ведение документации по подписке на PHP онлайн урок.


Введение

Пример создания и базового использования

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

Получение списка ваших документов и шаблонов

Работа с одним документом или шаблоном

Создание нового документа

Загрузка файла

Отображение документов

Заключение

Введение

В предыдущей статье

Управление цифровыми документами с помощью Eversign SAAS

вы, где введенный в службу everSign. В этой статье мы рассмотрим API, который они предоставляют, и как использовать с ним пакет подписи документов TrueSign PHP. Если вы хотите следовать и попробовать некоторые из функций самостоятельно, вам сначала нужно будет загрузить пакет, а затем зарегистрируйтесь в учетной записи на

https: eversign.com signup
. Бесплатный план позволит вам тестировать службу API с ограниченным количеством запросов API в месяц.

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

eversign.class.php
. Вы можете найти свои учетные данные, выбрав разработчика в раскрывающемся меню слева от панели управления.

protected $ apiKey = 'ВАША КЛЮЧА ЗДЕСЬ';
protected $ busID = 'БИЗНЕС ИД ЗДЕСЬ';

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

Пример создания и базового использования

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

include ('eversign.class.php');
$ eSign = new everSign (true);

Параметр, установленный в true, заключается в том, будем ли мы использовать API через SSL (безопасный) или просто стандартный HTTP (небезопасный). В этом случае мы используем безопасный режим, однако вы можете изменить это значение на false, чтобы использовать небезопасный режим.

API имеет несколько конечных точек, которые выполняют разные действия, и мы будем рассматривать их все по мере продвижения по этой статье. Это:



бизнес или b в виде сокращенного
документа или d
send_reminder или s
download_raw_document или rd

download_final_document или fd
file или f

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

Мы используем setEndPoint, чтобы сообщить классу, какую конечную точку мы будем использовать. В первом примере мы будем использовать конечную точку бизнеса, которая возвращает ответ, содержащий все предприятия, связанные с нашей учетной записью.


& lt;? php
include ('eversign.class.php');
$ eSign = new everSign (true);
$ eSign- & gt; setEndPoint ('b');
$ eSign- & gt; getResponseCurl (false);
if (! empty ($ eSign- & gt; errorCode)) {
& nbsp; & NBSP; echo 'error'. $ eSign- & gt; errorCode. ':'. $ ESign- & GT; ErrorText;
& nbsp; & NBSP; умереть;
}
echo '& lt; pre & gt;';
var_dump ($ eSign- & gt; ответ);
echo '& lt; предварительно & GT; ';
? & gt;

Обратите внимание, что мы используем сокращенную «b» для конечной точки, мы могли бы также использовать полное имя конечной точки «business», если бы захотели.

В следующей строке мы используем метод getResponseCurl для хранения ответа от API. Существует аналогичный метод с именем getResponse, разница между двумя заключается в том, что он будет использовать CURL, а другой будет использовать обработчик файла для получения ответа.

Я использую метод CURL, потому что он работает лучше по безопасному соединению. Если вы используете стандартный метод и получаете уведомления и ошибки безопасности, используйте CURL.

Параметр в методах getResponseCurl и getResponse должен включать идентификатор бизнеса или нет. В этом случае оно установлено в false, так как эта конечная точка не требует идентификатора бизнеса, она возвращает все предприятия.

Если бы ошибка, она будет отображаться, иначе вы должны увидеть объект, содержащий информацию обо всех ваших предприятиях.

Получение списка ваших документов и шаблонов

Мы используем конечную точку документа, чтобы получить подробную информацию о наших документах, которая будет включать все настройки для каждого извлеченного документа. Обратите внимание, что вам нужно будет иметь уже сохраненные документы для получения информации о них.


& lt;? php
include ('eversign.class.php');
$ eSign = new everSign (true);
$ eSign- & gt; setEndPoint ('d');
$ eSign- & gt; setParam ('type', 'all');
$ eSign- & gt; getResponseCurl (false);
if (! empty ($ eSign- & gt; errorCode)) {
& nbsp; & NBSP; echo 'error'. $ eSign- & gt; errorCode. ':'. $ ESign- & GT; ErrorText;
& nbsp; & NBSP; умереть;
}
echo '& lt; pre & gt;';
var_dump ($ eSign- & gt; ответ);
echo '& lt; предварительно & GT; ';
? & gt;

После настройки нашей конечной точки мы ввели новый метод setParam. Это используется для установки параметров, которые будут отправляться с нашим запросом API. Мы устанавливаем параметр «type» в значение «all». Есть несколько значений, которые могут быть отправлены:



all = все документы
my_action_required = документы, требующие вашего действия
waiting_for_others = документы, ожидающие действия другого подписчика
завершены = завершенные документы

черновики = документы все еще на стадии проекта
аннулировано = отмененные документы

Если у вас есть премиум-аккаунт, который поддерживает шаблоны, вы также можете использовать параметр «type» для извлечения тех, которые используют следующие значения:



templates = все активные шаблоны

templates_archived = заархивированные шаблоны
template_drafts = шаблоны все еще находятся на стадии проекта

Работа с одним документом или шаблоном

Если вы запустили запрос на получение ваших документов, вы увидите хеш-документ, который является в основном идентификатором для этого документа.

Если вы просматриваете документ на панели инструментов everSign, хэш может быть найден как последняя часть URL-адреса. Чтобы получить детали для одного документа, мы будем использовать конечную точку «document» и установить параметр document_hash вместо параметра «type», который мы использовали ранее.
$ eSign- & gt; setParam ('document_hash', 'your-document-hash-here');

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

Если вы хотите отменить документ, вы должны включить параметр document_hash, а параметр «cancel» установлен в значение «1» в том же запросе.
$ eSign- & gt; setParam ('cancel', '1');

Создание нового документа

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

https: eversign.com api documentation methods # create-document
. К счастью, пакет подписи для документов TrueSign PHP позаботится о тяжелом подъеме для вас, поэтому я коснусь доступных методов.
setDocParams ($ params)

Этот метод передает массив базовых параметров документа и используется следующим образом:


$ doc = array (
& nbsp; & nbsp; 'is_draft' = & gt; 1;,
& nbsp; & nbsp; 'title' = & gt; 'My Document Title'
);
$ eSign- & gt; setDocParams ($ doc);
addFile ($ name, $ file)

Этот метод добавляет локальный файл и правильно кодирует его. Вы должны указать имя, которое вы хотите сохранить в файле everSign, и полный путь к файлу в качестве параметров. Он вернет локальный идентификатор файла, который будет использоваться для присвоения полей этому файлу, и об этом на мгновение.
addFilebyID ($ name, $ id)

Этот метод добавляет файл, который вы ранее загружали в everSign. Вы бы указали название вы хотите, чтобы он хранился в everSign как и идентификатор файла, который everSign присвоил загруженному файлу. Мы рассмотрим загрузку файлов в другом разделе. Он вернет идентификатор локального файла, который будет использоваться для назначения полей этому файлу.
addFilebyURL ($ name, $ url)

Этот метод добавляет файл, доступный в Интернете. Вы должны указать имя, которое вы хотите сохранить на everSign, и полный URL-адрес, где everSign может его получить. Он вернет идентификатор локального файла, который будет использоваться для назначения полей этому файлу.
addField ($ fileID, $ params)

Каждый файл имеет возможность добавлять к нему разные поля. Они могут включать любой поддерживаемый тип поля с соответствующими настройками. Вы предоставили бы локальный идентификатор файла, возвращенный указанными выше методами файлов, и параметры будут массивом полей и их параметров. Обратите внимание: если документ не содержит полей подписи, в конце документа будет создана страница подписи.
addSigner ($ name, $ email, $ pin = '', $ message = '', $ order = 0, $ id = 0, $ role = '')

Этот метод добавит подписывающего лица к документу. Вы должны указать свое имя и адрес электронной почты и, возможно, указать контакт безопасности, сообщение, заказ для страницы подписи, а для шаблонов - идентификатор пользователя и роль.
addCC ($ name, $ email, $ role = '')

Этот метод добавит получателя электронной почты в документ. Вы должны указать их имя и адрес электронной почты и необязательно указать их роль для шаблонов.
addMeta ($ key, $ value)

Этот метод добавит пары мета-значения в документ. Вы указываете ключ и значение.
addTemplateField ($ id, $ value)

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

После того, как все свойства документа были установлены, вы отправляете созданный документ с помощью метода sendDocument (). Пакет будет отправлять обязательные поля в конечную точку документа, используя CURL.

Загрузка файла

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

Чтобы выполнить это, вы должны использовать стандартную форму html с атрибутом multipart form-data enctype и полем файла.

Отправьте файл на свой скрипт и используйте метод uploadCurl ($ field), чтобы отправить его в API. Параметр поля - это имя, которое вы использовали для своего поля. API вернет идентификатор файла, который затем можно использовать в методе addFilebyID.


& lt;? php
include ('eversign.class.php');
$ eSign = new everSign (true);
if (isset ($ _ FILES ['myfile'] ['tmp_name'])) {
$ eSign- & gt; setEndPoint ('f');
$ eSign- & gt; uploadCurl ('myfile');
if (! empty ($ eSign- & gt; errorCode)) {
& nbsp; & NBSP; echo 'error'. $ eSign- & gt; errorCode. ':'. $ ESign- & GT; ErrorText;
& nbsp; & NBSP; умереть;
}
$ file_id = $ eSign- & gt; response- & gt; file_id;
$ doc = массив (
& nbsp; & nbsp; 'is_draft' = & gt; 1,
& nbsp; & nbsp; 'title' = & gt; 'Myfile Upload'
);
$ eSign- & gt; setDocParams ($ doc);
$ eSign- & gt; addFilebyID ('Upload Test', $ file_id);
$ eSign- & gt; addSigner ('Joe Test', 'joe_test@yourdomain.com');
}
$ eSign- & gt; sendDocument ();
echo '& lt; pre & gt;';
var_dump ($ eSign- & gt; ответ);
echo '& lt; предварительно & GT; ';
умереть;
? & gt;
& lt;! DOCTYPE html & gt;
& lt; html & gt;
& lt; head & gt;
& lt; title & gt; Загрузка файла & lt; Название & GT;
& lt; головка & GT;
& lt; body & gt;
& lt; form method = "post" enctype = "multipart form-data" & gt;
& lt; input type = "file" name = "myfile" & gt; & lt; br & gt;
& lt; input type = "submit" value = "Send File" & gt;
& lt; Форма & GT;
& lt; Тело & GT;
& lt; HTML & GT;

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

Отображение документов

Для использования двух конечных точек извлечение документов в формате Adobe Acrobat (PDF).

Чтобы получить и просмотреть окончательный документ в своем браузере, вы должны установить конечную точку для загрузки_файла_документа и установить параметр document_hash. Затем вы вызываете метод displayPDF ($ name = ''), именовав файл, если хотите.


& lt;? php
include ('eversign.class.php');
$ eSign = new everSign (true);
$ eSign- & gt; setEndPoint ('fd');
$ eSign- & gt; setParam ('document_hash', 'your-document-hash-here');
$ eSign- & gt; setParam ('audit_trail', '1');
$ eSign- & gt; displayPDF ('myfile');
? & gt;

Обратите внимание, что мы также установили параметр audit_trail равным 1, который добавит контрольный журнал в наш окончательный документ. Этот параметр доступен только при отображении окончательного документа.

Мы также можем отобразить необработанный документ, изменив нашу конечную точку на download_raw_document.
$ eSign- & gt; setEndPoint ('rd');

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

Заключение

Это охватывает основы взаимодействия с API-интерфейсом everSign eSignature. Есть некоторые другие особенности и методы, которые стоит упомянуть.
sendReminder ($ hash, $ id)

Этот метод отправит напоминание подписчику. Вы указываете хэш документа и идентификатор подписчиков. Вы также должны установить конечную точку на send_reminder.
setBusID ($ id)

Этот метод позволит вам изменить бизнес-идентификатор по умолчанию, если вам нужно это сделать.
resetParams ()

Этот метод сбрасывает все параметры, ранее заданные с помощью метода setParam.

Я понимаю, что это совсем немного, чтобы усвоить в одном чтении. Ознакомьтесь с тем, как все документы Sign управляются с панели управления, читайте документацию по API и затем проверяете API, и все это начнет иметь смысл в кратчайшие сроки.