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_unit - единица измерения промежутка. Может принимать значение "m" (минуты), "h" (часы), "d" (дни).
Либо, для указания точного времени отправки, нужно передать время в формате unix time в email_timeout_timestamp. Если переданы email_timeout_value и email_timeout_timestamp, то приориет будет у последней. -
folder_id
ID папки в Диске (строка, 36 символов) сохранения файлов. Если папки нет, то она будет создана автоматически при создании первого файла.
-
storage_period
Время хранения файлов на Диске. Если параметр не указан, то файлы хранятся бессрочно, до удаления вручную. Для удаления через промежуток времени должен принять значение:
timeout. В этом случае необходимо передать ещё два параметра:
storage_period_timeout_value - цифровое значение промежутка, через который удалить файлы, целое значение
storage_period_timeout_unit - единица измерения промежутка. Может принимать значение "m" (минуты), "h" (часы), "d" (дни).
Либо, для указания точного времени удаления, нужно передать время в формате unix time в storage_period_timeout_timestamp. Если переданы storage_period_timeout_value и email_timeout_timestamp, то приориет будет у последней. -
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"]
}