ГрамотаДел ГрамотаДел Express В чём разница?

Публичное API

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

С чего начать

В разделе "API" получите Secure токен для запров к API и разрешите обрабатывать запросы через API.
Кроме того, необходимо создать документ, содержащий строки с переменными, а так же письмо и папку в Диске для готовых файлов. Если вы хотите отправлять готовые файлы в Яндекс.Диск, то нужно получить разрешение на доступ к записи в Диск.

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

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

Переменная Обязательный Описание Комментарии
secure да Secure токен Нужно получить в основных настройках. Не следует передавать в открытом виде. Только для запросов сервер-сервер.
doc_id да ID документа ID документа можно получить в адресной строке при его открытии. Документ не должен быть в корзине, но может лежать в любой паке в Документах.
mask да Маска для замены JSON-строка, содержщая все переменные для замены в виде ключ (переменная) - значение (текст для замены). Может содержать данные для создания нескольких файлов (без ограничений на количество).
Пример для одного файла:
[{"%фио": "Иванов", "%баллы":"100"}]
Пример для нескольких файлов:
[{"%фио": "Иванов", "%баллы":"100"}, {"%фио": "Петров", "%баллы":"200"}, {"%фио": "Сидоров", "%баллы":"300"}]
Для указания адреса электронной почты и отправки письма используйте переменную %адрес_почты, темы письма - %заголовок_письма, имени файла - %имя_файла. Для отправки писем на несколько адресов укажите их через запятую или пробел. При этом статус отправки в Диске будет отображаться по первому адресу.
Можно использовать только двойные кавычки в соответствии со стандартом. Если значение ключа содержит кавычки, то они должны быть экранированы.
Альтернативный метод
Если отправить JSON-строку нет возможности, то строки для замены можно отправить как поля формы. Каждая переменная для замены должна начинаться с mask_, например mask_name и содержать значение для замены. При этом в документе будет осуществлён поиск перерменной с части после нижего подчёркивания и с знаком %, наример %name. Для указания адреса электронной почты в этом случае используйте mask_email, а имя файла - mask_filename. Для отправки писем на несколько адресов укажите их через запятую или пробел. При этом статус отправки в Диске будет отображаться по первому адресу.
mail_id нет ID письма ID письма можно получить в адресной строке при его открытии. Если переменная не передана, то письмо отправлено не будет.
email_send нет Время отправки Время, когда отправлять письмо с файлом. Может принимать следующие значения:
onfinish - Разослать все письма после создания всех файлов в группе (по-умолчанию)
oncreate - Отправлять письма сразу же после создания файла. При создании одного файла onfinish и oncreate идентичны.
timeout - Разослать письма через промежуток времени. В этом случае необходимо передать ещё два параметра:
email_timeout_value - цифровое значение промежутка, через который отправлять письма, целое значение
email_timeout_value - единица измерения промежутка. Может принимать значение "m" (минуты), "h" (часы), "d" (дни).
Либо, для указания точного времени отправки, передайте время в формате unix time в email_timeout_timestamp. Если переданы обе переменные, то приориет у последней.
genuine нет Лейбл проверки подлинности С версии 1.1: лейбл для проверки подлинности готового файла. Может принимать следующие значения:
ID лейбла Указанный лейбл будет нанесён на файл. ID плейбла можно посмотреть в заголовке окна, открыв его.
none - не добавлять лейбл проверки подлинности. Эквивалентно отсутствию переменной в запросе.
folder_id нет Папка в Диске Папка для добавления файлов в Диске. Если папки нет, то она будет создана автоматически при создании первого файла.
yadisk нет Яндекс.Диск Добавлять ли готовые файлы на Яндекс.Диск. Может принимать следующие значения:
all - добавлять создаваемые файлы в отдельную папку.
all-f - добавлять создаваемые файлы в папку "Готовые файлы".
none - не добавлять файлы на Яндекс.Диск. Эквивалентно отсутствию переменной в запросе.

Результат

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

Ключ Значение Описание
result error Ошибка запроса. Файлы не созданы.
success Успешный запрос на создание файлов. В зависимости от сценария использования API можно сообщить об успешном создании файлов или вывести форму получения файлов.
create_id ID генерации Только при успешном выполнении запроса. Может пригодится для других запросов к API. Если это возможно, сохраните ID генерации.
files ID файлов Только при успешном выполнении запроса. Массив, содержайщий ID создаваемых файлов. Для получения самого файла необходимо сделать запрос к https://gramotadel.express/getfile/{ID}/. В ответ вы получите файл в формате JPG. Для загрузки PDF версии добавьте к адресу pdf/. Обратите внимание, что API возвращает ID файла сразу же, однако на подготовку самих файлов требуется время - от 1 до 5 секунд на каждый файл. До того, как файл будет создан, запрос к https://gramotadel.express/getfile/{ID}/ будет возврашать ошибку 404.
url URL для получения файлов Только при успешном выполнении запроса. URL строка для вывода формы скачивания файлов. Необходимо открыть Iframe c указанным URL. Просто переход по URL работать не будет. Код формы можно взять в настройках, заменив URL на полученный в этом ключе. Чтобы получение файлов работало, необходимо, чтобы в настройках было включено получение файлов через форму. Адрес сайта, на котором происходит получение файла должно быть корректно указанно в настройках формы.
Создание каждого файла занимает 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/getform/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"]}


Автоматические отчёты в Google Таблице

Вы настроить отправку отчётов о созданных файлах в Google Таблицу. Информация о файлах, в том числе статус отправки, будет сохраняться в вашей таблице.
Посмотрите раздел документации Отправка автоматических отчётов в Google Таблицы.


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

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

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

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

Данные для замены могут быть одинаковые (для этого просто используйте одинаковые переменные в документе), либо отличаться. Например, в одном документе вы используете %name_ru, а в другом - %name_en. В этом случае в запросе должны быть два поля - mask_name_ru и mask_name_en. Одно подставится в один документ, а другое - в другой.


Нужна помощь?

Напишите нам в техническую поддержку или через чат. Мы с радостью поможем вам!

Открыть