 API

Используя API ГрамотаДел Express можно создавать файлы c персональными даннымы и при необходимости отдавать их получателям. Запросы к API могут происходить как с другого сервера, так и из браузера через CORS запрос.

С чего начать

В разделе «Интеграция» - «Токены API» нужно получить Secure токен для запросов и разрешить использовать этот токен. Кроме того, необходимо создать документ, содержащий переменные для персональных данных, а также шаблон письма для рассылок по электронной почте и папку в Диске для готовых файлов.

Создание файлов

Для создания файлов необходимо отправлять POST-DATA, POST-JSON или GET запросы на адрес
https://gramotadel.express/api/v1/create/
с указанными ниже данными.
Кодировка запроса - UTF-8. Обязательные поля отмечены звёздочкой.

secure*

Токен (строка, 36 символов)
doc_id*

ID документа (строка, 36 символов), который будет использоваться для создания файла. ID можно получить в адресной строке, когда документ открыт. Документ не должен быть в корзине, но может лежать в любой паке Документов.
mask*

JSON-строка, содержщая все переменные для замены в виде ключ (переменная) - значение (текст для замены). Может содержать данные для создания нескольких файлов (без ограничений на количество).
Пример для одного файла:
[{"%фио": "Иванов", "%баллы":"100"}]
Пример для нескольких файлов:
[{"%фио": "Иванов", "%баллы":"100"}, {"%фио": "Петров", "%баллы":"200"}, {"%фио": "Сидоров", "%баллы":"300"}]
Для указания адреса электронной почты нужно использовать %email, имени файла - %filename. Для отправки созданных файлов на несколько адресов электронной почты нужно укзазать из через запятую. При этом статус отправки в Диске будет отображаться по первому адресу.
Можно использовать только двойные кавычки в соответствии со стандартом. Если значение ключа содержит кавычки, то они должны быть экранированы.

Для передачи изображения в блок с изображением можно использовать либо прямую ссылку (http:// или https://), либо закодированное в Base64 изображение. Во втором случае строка должна начинаться с "data:image/".

Альтернативный метод
Если отправить JSON-строку нет возможности, то строки для замены можно отправить как поля запроса. Каждая переменная для замены должна начинаться префикса с mask_, например mask_name и содержать значение для замены. При этом в документе будет осуществлён поиск переменной после префикса. Например, полю mask_name соответствует переменная %name. Для указания адреса электронной почты в этом случае нужно использовать mask_email, а имя файла - mask_filename.
mail_id

ID шаблона письма (строка, 36 символов) для отправки по электронной почте. ID можно получить в адресной строке, когда шаблон открыт. Если переменная не передана, то письмо отправлено не будет.
email_send

Время, когда отправлять письмо с файлом. Может принимать следующие значения:
onfinish - Разослать все письма после создания всех файлов (по-умолчанию)
oncreate - Отправлять письма сразу же после создания файла. При создании одного файла onfinish и oncreate идентичны.
timeout - Разослать письма через промежуток времени. В этом случае необходимо передать ещё два параметра:
email_timeout_value - цифровое значение промежутка, через который отправлять письма, целое значение
email_timeout_value - единица измерения промежутка. Может принимать значение "m" (минуты), "h" (часы), "d" (дни).
Либо, для указания точного времени отправки, нужно передать время в формате unix time в email_timeout_timestamp. Если переданы timeout и email_timeout_timestamp, то приориет будет у последней.
folder_id

ID папки в Диске (строка, 36 символов) сохранения файлов. Если папки нет, то она будет создана автоматически при создании первого файла.
page_id

Порядковый номер листа (число или строка), если в документе есть несколько листов. Можно передать один номер ( первый лист - 0), или номера (через запятую) листов, которые нужно использовать для создания файла.
result

Определяет в каком виде возвращать результат. Может принимать значения:
- Значение отсутствует. Будет возвращена JSON-строка с результатом запроса (см. ниже)
- link. При успешном запросе будет возвращена строка, содержащая ссылку на созданный файл (если в запросе было создание нескольких файлов, то ссылку на первый). Для получения самого файла нужно обратиться по указанной ссылке. На подготовку самих файлов требуется время - от 1 до 5 секунд на каждый файл. До того, как файл будет создан, запрос по этому адресу будет возврашать ошибку 404. Если запрос не привёл к созданию файла, то будет возвращена JSON строка с ошибкой (см. ниже).
- file. При успешном запросе будет возвращён сам готовый файл (если в запросе было создание нескольких файлов, то только первый). Так как создание файла занимает 1-5 секунд, то возврат произойдёт только после того, как файл будет создан. При большом количестве запросов к API время создание файла будет увеличено. Если файл не будет подготовлен за 30 секунд, то API вернёт ошибку 404 (хотя сам запрос на создание файла в конечном итоге будет исполнен). Если запрос не привёл к созданию файла, то будет возвращена JSON строка с ошибкой (см. ниже). Если ожидается, что запросов к API будет больше, чем 1 запрос в 5 секунд, то не стоит использовать этот параметр.

Результат

В результате сервер вернёт JSON-строку, принимающую следующие возможные значения:

result

Результат запроса. Может принимать следующие значения:
error - ошибка запроса. Файлы не созданы.
success -успешный запрос на создание файлов. В зависимости от сценария использования API можно сообщить об успешном создании файлов или вывести форму получения файлов.
create_id

ID генерации. Только при успешном выполнении запроса. Может пригодится для других запросов к API.
files

Массив, содержайщий ID создаваемых файлов. Только при успешном выполнении запроса. Для получения самого файла формате JPG необходимо обратиться к https://gramotadel.express/getfile/{ID}/. Для загрузки PDF файла нужно добавить к адресу pdf/. API возвращает ID файла сразу же, однако на подготовку самих файлов требуется время - от 1 до 5 секунд на каждый файл. До того, как файл будет создан, запрос к https://gramotadel.express/getfile/{ID}/ будет возврашать ошибку 404.
url

URL строка для вывода виджета скачивания файлов. Только при успешном выполнении запроса. Необходимо создать Iframe c указанным URL. Просто переход по URL не даст результата. Домен сайта, на котором происходит получение файла, должен быть корректно указан в настройках API.
Создание каждого файла занимает 1 секунду + несколько секунд на обработку всей группы. Сразу же после отправки запроса можно открывать Iframe с указанными URL. Если создание файлов ещё не завершено, то будет выведено соответствующее сообщение. Как только файлы будут готовы, их будет предложено скачать.
Можно вывести виджет получения в диалоговом окне поверх страницы. Для этого нужно создать Iframe со следующими дополнительными стилями: position:fixed; width:100%; height:100%; top:0; bottom:0; right:0; left:0; z-index:10000; background: rgb(0 0 0 / 72%); К адресной строке нужно добавить ?view=modal. И разместить этот iframe в body.
error_text

Только при ошибке. Текстовое описание ошибки. Возможнные ошибки: неверный Secure токен, маска для замены, ID документа, ID шаблона письма, ID папки в Диске, либо внутренняя ошибка сервера.

Пример возвращаемых данных при успешном запросе:
{
"result":"success",
"create_id":"b4caf05b-6757-4d9c-b4bc-1924a9b31796",
"url":"https://embed.gramotadel.express/widgets/get/927ebf68-2f55-4b20-a18c-c1171ee113db/b4caf05b-6757-4d9c-b4bc-1924a9b31796/",
"files":[
"369dc61e-40c2-46c0-81f4-e31ca8c33cc2",
"d94c6efb-0076-438b-bb84-fead9c1ae556",
"716e1081-c8ee-442b-b0b0-0681b2ed5d90"
]
}

Создание нескольких файлов в одном запросе

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

Чтобы отправить такой запрос, переменная doc_id должна быть массивом (имя переменной - doc_id[]). В таком случае в одном запросе может быть несколько переменных doc_id[] - для создания нескольких файлов. Другие переменные, такие как mail_id, email_send, folder_id тоже могут быть отправлены в виде массивов, чтобы каждый из файлов был отправлен в определённым шаблоном, в определённое время или сохранён в определённую папку. Если в этом нет необходимости, то массивом должно быть только поле doc_id.

Например, необходимо создать два файла из разных документов и положить их в разные папки на Диске. Для этого необходимо отправить две переменные doc_id[] и две переменные folder_id[] (в том же порядке). Кроме того, если стоит задача отправить их одним письмом, то нужно указать один mail_id, а в email_send[] вначале указать "manual", а затем "oncreate". В этом случае вначале будет создан один файл, затем - второй. И только после создания второго произойдёт отправка с указанным в mail_id письмом.

Отправлять себе файл после создания

Файл будет отправлен на электронную почту аккаунта сразу же после того, как будет создан. В поле «Шаблон письма» можно выбрать, какой шаблон использовать для отправки. Предварительно в Шаблонах писем можно создать отдельный шаблон для отправки писем на электронную почту аккаунта. Если в тексте письма написать переменную %data, то в это место будут добавлены все данные файла в виде таблицы.

Удаление файлов

Для удаления файлов необходимо отправить POST-DATA, POST-JSON или GET запросы на адрес
https://gramotadel.express/api/v1/drive/files/delete/
с указанными ниже данными.
Кодировка запроса - UTF-8. Обязательные поля отмечены звёздочкой.

secure*

Токен (строка, 36 символов)
file_id

ID файла (строка, 36 символов), который будет удалён. ID файла возвращается в массиве files при создании через API. Файл не должен быть в корзине.

ИЛИ
file_ids

Массив ID файлов (строка, 36 символов), которые будут удалены, если требуется удалить несколько файлов в одном запросе.

ИЛИ
creater_id

ID генерации (строка, 36 символов), если файл был создан через API. ID генерации можно передать вместо file_id или file_ids. В этом случае будут удалены все файлы с этим ID генерации. ID генерации возвращается в поле create_id при создании файлов через API.

delete_forever

Удалять ли файл окончательно, без перемещения в корзину. По-умолчанию файл перемещается в корзину. Может принимать значения:
- 0 - переместить в корзину (по-умолчанию)
- 1 - удалить окончательно
Файлы из корзины удаляются автоматически через 60 дней после перемещения в козину.

Пример

Пример корректного запроса на удаление файлов:
{
"secure":"b4caf05b-6757-4d9c-b4bc-1924a9b31796",
"file_id":"369dc61e-40c2-46c0-81f4-e31ca8c33cc2"
}

Результат

В результате сервер вернёт JSON-строку, принимающую следующие возможные значения:

result

Результат запроса. Может принимать следующие значения:
error - ошибка запроса. Файлы не удалены.
success -успешный запрос на удаление файлов.
files

Массив, содержайщий ID удалённых файлов. Только при успешном выполнении запроса.
error_text

Только при ошибке. Текстовое описание ошибки. Возможнные ошибки: неверный Secure токен, ID файла, ID генерации, либо внутренняя ошибка сервера.

Пример возвращаемых данных при успешном запросе:
{
"result":"success",
"files":["369dc61e-40c2-46c0-81f4-e31ca8c33cc2"]
}

Другие интеграции

Готовы начать?

Открыть Открыть веб-приложение