Отправка файлов на подпись с Adobe Sign API

В документации Adobe сочетается большой объем информации и плохая организация этой информации. Поэтому когда перед мной стала задача отправлять документы через Adobe Sign Api, я потратил несколько дней чтобы понять как всё это работает. 

И вот моё решение перед вами. Надеюсь, оно сэкономит время и нервы тех кому только предстоит разобраться в этом. 

Порядок действий:

1. Создаем статичный ключ для работы с API - Access token

2. Получаем домены для работы с API - Base uris

3. Загружаем документ

4. Отправляем документ на подпись

5. Проверяем статус подписи

6. Сохраняем подписанный файл

Создаем статичный ключ для работы с API - Access token

Заходим в свой аккаунт на сайте Adobe Sign API: https://secure.echosign.com/public/login. Переходим на страницу Account. Выбираем Personal Preferences и Access Tokens.

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

После сохранения, кликаем на наш токен и нажимаем сверху “Integration Key”, чтобы получить наш токен.

Далее в перменной $accessToken будет именно этот токен.

Получаем домены для работы с API - Base uris

<?php
// Access token, полученный выше
$accessToken = '';

// Laravel фасад:
// GET запрос
// Доп. заголовок: Bearer $accessToken
// URL: https://api.adobesign.com/api/rest/v6/baseUris
$response = Http::withToken($accessToken)
  ->get('https://api.adobesign.com/api/rest/v6/baseUris');

// В ответе JSON с полем apiAccessPoint 
$apiAccessPoint = $response->json('apiAccessPoint');

В $apiAccessPoint домен для API запросов.

Загружаем документ

<?php
// Access token, полученный выше
$accessToken = '';

// Домен для API запросов, полученный выше
$apiAccessPoint = '';

// Путь к pdf шаблону
$template = file_get_contents($pathToTemplate);

// Laravel фасад:
// POST multipart/form-data запрос
// Доп. заголовок: Bearer $accessToken
// URL: $apiAccessPoint.'/api/rest/v6/transientDocuments'
// В теле указываем название файла, mime тип и содержимое файла
$response = Http
   ::withToken($accessToken)
   ->baseUrl($apiAccessPoint)
   ->asMultipart()
   ->post('/api/rest/v6/transientDocuments', [
       'File-Name' => 'document.pdf',
       'Mime-Type' => 'application/pdf',
       'File'      => $template
   ]);

// В ответе JSON с полем transientDocumentId, что является ID загруженного дока
$transientDocumentID = $response->json('transientDocumentId');
if ( ! $transientDocumentID) {
   // Если не пришел ID документа, то обрабатываем ошибку
}

В переменной $transientDocumentID будет ID загруженного документа.

Отправляем документ на подпись

Далее мне надо было понять как отправить документ на подпись.

Сначала я пытался добавить в документ виджеты. Виджет - это поле ввода в которое пользователь может внести свои данные, включая подпись. Но виджетам необходимо указывать координаты, которые непонятно как связаны с реальным документом. 

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

Например, чтобы появилось поле подписи, нужно ввести тег {{ es:signer:signature }}

В документе это может выглядеть так:

Документ #1234

Исполнитель: Дмитрий Дмитриевич {{es:signer:signature }}

Далее необходимо сформировать тело запроса. Оно содержит некоторое количество полей:

<?php
// Функция для формирования тела запроса. Используется ниже
function getBodyForSignDocument($documentID, $email): array
{
   return [
       // ID документа, полученный выше
       "fileInfos"           => [
           [
               "transientDocumentId" => $documentID
           ]
       ],
       // Название документа, которое увидит клиент
       "name"                => "Series Document",
       "participantSetsInfo" => [
           [
               "order"       => 1,
               "role"        => "SIGNER",
               "memberInfos" => [
                   [
                       // Почта клиента
                       "email" => $email,
                       "id"    => 1
                   ]
               ]
           ]
       ],
       "signatureType"       => "ESIGN",
       "state"               => "IN_PROCESS"
   ];
}

Теперь необходимо выполнить запрос на отправку файла на подпись:

<?php
// Access token, полученный выше
$accessToken = '';

// Домен для API запросов, полученный выше
$apiAccessPoint = '';

// Тело запроса, функция которого писана выше
$bodyForSignDocument = getBodyForSignDocument($transientDocumentID, $email);


// Laravel фасад:
// POST application/json запрос
// Доп. заголовок: Bearer $accessToken
// URL: $apiAccessPoint.'/api/rest/v6/agreements'
// Тело запроса описано выше
$response = Http::withToken(self::API_TOKEN)
                ->baseUrl($apiAccessPoint)
                ->asJson()
                ->post(
                    '/api/rest/v6/agreements',
                    $bodyForSignDocument
                );

// В ответе JSON с ID загруженного документа. Он понадобится ниже
$documentID = $response->json('id');
if ($response->status() != '201' || ! $documentID) {
   // Если ID не пришел или документ не был первично обработан Adobe, обрабатываем ошибку
}

В переменной $documentID содержится ID документа, который был отправлен на подпись.

Проверяем статус подписи

<?php
// Access token, полученный выше
$accessToken = '';

// Домен для API запросов, полученный выше
$apiAccessPoint = '';

// ID документа, полученный выше
$documentID

// Laravel фасад:
// GET запрос
// Доп. заголовок: Bearer $accessToken
// URL: $apiAccessPoint.'/api/rest/v6/agreements/'.$documentID
$response = Http::withToken(self::API_TOKEN)
               ->baseUrl($apiAccessPoint)
               ->get('/api/rest/v6/agreements/' . $documentID);

// В ответе JSON с полем status
$status = $response->json('status');
if ($status !== 'SIGNED') {
   // Если статус не SIGNED, то ждем пока подпишут
}

Сохраняем подписанный файл

<?php
// Access token, полученный выше
$accessToken = '';

// Домен для API запросов, полученный выше
$apiAccessPoint = '';

// ID документа, полученный выше
$documentID

// Полный путь до файла  
$fileURLPath = $apiAccessPoint . 'api/rest/v6/agreements/' . $documentID . '/combinedDocument';

// Laravel фасад:
// GET запрос
// Доп. заголовок: Bearer $accessToken
// URL: $apiAccessPoint.$fileURLPath
$fileContent = Http::withToken(self::API_TOKEN)
                  ->baseUrl($apiAccessPoint)
                  ->get($fileURLPath);

// В теле ответа будет подписанный PDF файл, если раннее в статусе было SIGNED 
$fileContent = $fileContent->body();

Источники. Примечания

Источники

• Общий гайд по Adobe Sign API - можно ознакомиться для общего понимания API

• Описание запросов к API 6й версии - тут подробно описаны методы для отправки документа на подпись

• Гайд от Adobe по Access Token - не уверен что читал именно этот гайд, поэтому могу лишь посоветовать бегло посмотреть что к чему тут

• Руководство по тегам в Adobe Sign API - советую внимательно прочитать

• Личный кабинет в Adobe Sign - на всякий случай

Касательно авторизации

Изначально Adobe просит использовать авторизацию через кнопку "Войти через Adobe". Но такой способ мне не подходил, ибо система должна функционировать автономно без вмешательства пользователей. Авторизация - тоже вмешательство.

Именно поэтому была найдена альтернатива в виде статичного токена - access token.

Касательно параметров в POST методе /api/rest/v6/agreements

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

Например, можно не отправлять сразу документ, а подготовить его, добавив те виджеты. И только потом отправлять. Либо же, можно добавить какие-то данные в документ через автозамену тегов в формат {{var.name}}

Прошлая статья на тему Adobe

"Генерация файлов с Adobe" - в статье описаны методы формирования файлов из doсx шаблонов.