Метод makeOrder
Описание
Формирует заявку на выпуск электронного подарочного сертификата (ЭПС) и его отправку конечному получателю. Выпуск сертификата происходит асинхронно. Как правило, выпуск ЭПС происходит за время не превышающее 5 секунд, однако в некоторых случаях возможны задержки.
Для отслеживания статуса возможна настройка callback_url (для настройки обратитесь к техническому специалисту). После обработки заявок на выпуск ЭПС на указанный callback_url будет отправляться POST запрос. В случае успешного выпуска ЭПС (status = ok) будут переданы поля из заявки, а так же поле order_id — уникальный идентификатор заказанного сертификата в системе Giftery. В случае ошибки (status = error) будет передано описание ошибки.
Параметры запроса (data)
| Параметр | Описание |
|---|---|
| product_id | Обязательное. ID продукта (см. метод getProducts, поле id) |
| face | Обязательное. Номинал сертификата (см. метод getProducts, поле faces) |
| uuid | Уникальный идентификатор заявки, передаваемый от клиента к API. Используется для предотвращения дублирования заказов при сетевых сбоях. Если передать два запроса с одинаковым uuid, в первом случае будет добавлена новая заявка в очередь, то во втором вернётся идентификатор первой заявки и дублирования не произойдёт. Несмотря на название значение может быть валидной UUID строкой или строкой из случайного набора символов (до 36 включительно). В случае обнаружения uuid в истории, мы попробуем сравнить связанные с ним параметры с параметрами текущего запроса. При совпадении значений вернётся идентификатор ранее созданной заявки, при наличии расхождений - ошибка с кодом 1207 |
| email_from | Email отправителя сертификата. Строка, не более 255 символов. |
| email_to | Email получателя сертификата. Если не указан, то доставка сертификата через платформу Giftery не производится. Строка, не более 255 символов. |
| from | Имя отправителя (используется в шаблонах почтовых нотификаций). Строка, не более 255 символов. |
| to | Имя получателя (используется в шаблонах почтовых нотификаций). Не более 255 символов. |
| to_phone | Номер телефона получателя. При указанании email_to и to_phone сертификат будет отправлен на почтовый адрес, дополнительно будет отправлено уведомление на телефонный номер. При указании только to_phone на телефонный номер будет доставлен код для последующего получения сертификата самим получателем. Формат номера телефона 79001234567. |
| date_send | Отложенная даты отправки сертификата в формате ISO8601 YYYY-MM-DDThh:mm:ss±hh:mm. Клиенты зарегистрированные до 1 февраля 2023 года могут дополнительно использовать формат YYYY-MM-DD hh:mm:ss для обратной совместимости (в таком случае дата должна быть в часовом поясе UTC+3 (MSK)). Дата отправка должна быть в будущем относительно момента выполнения запроса. Устаревший формат со временем будет удалён. |
| text | Текст поздравления (используется в шаблонах нотификаций). Строка, не более 512 символов. |
| code | Служебный код заказа. По умолчанию все заказы имеют код API. Код может содержать только большие английские буквы, цифры и знак подчёркивания. Должен соответствовать регулярному выражению ^[_A-Z0-9]+$. Строка, не более 100 символов. |
| comment | Служебный комментарий к заказу. Может быть использован партнёром в личных целях. Отображается в личном кабинете. Строка, не более 512 символов. |
| external_id | Идентификатор во внешней системе. Например, это может быть внутренний номер заказа системы, которая выполняет запрос на создание сертификата. Строка, не более 255 символов. |
| delivery_type | Возможные варианты получения сертификатов: email (по умолчанию; конечный клиент получает сертификат письмом на свою электронную почту), sms (на указанный в to_phone номер телефона будет отправлено СМС с информацией о получении сертификата), link (ссылка для получения сертификата доступна через метод getLinks). |
| ttl | Количество секунд, в течение которого мы будем пробовать обработать заказ. Большинство заказов обрабатывается в течение считанных секунд, однако в редких случаях (как правило связанных с техническими проблемами на стороне поставшиков) это время может доходить до нескольких часов. Данный параметр позволяет ограничить время обработки заказа по истечении которого заказ будет автоматически отменён. По умолчанию время обработки заказа не оганичено. В качестве значения можно передать число от 60 (одна минута) до 86400 один день. Отсчёт идёт с момента получения заявки. |
Параметры ответа (data)
| Параметр | Описание |
|---|---|
| id | ID заявки в очереди заказов. Обратите внимание, что данный ID не является идентификатором заказа. Для получения номера заказа необходимо вызвать метод getStatus с параметром id = ID. |
Пример
# Получаем значение для подстановки SIG
# Вместо SECRET необходимо подставить хранящийся у клиента секретный ключ для подписи запросов к API
$ echo -n 'makeOrder{"product_id":2111,"face":500,"email_to":"ivan@giftery.ru","from":"Giftery"}SECRET' | sha256sum - | awk '{print $1}'
# Используем известный клиенту ID и сгенерированный SIG для выполнения запроса
$ curl 'https://ssl-api.giftery.ru/?cmd=makeOrder&id=ID&in=json&out=json&data=%7B%22product_id%22%3A2111%2C%22face%22%3A500%2C%22email_to%22%3A%22ivan%40giftery.ru%22%2C%22from%22%3A%22Giftery%22%7D&sig=SIG'
# Можно использовать при передачи данных метод POST
$ curl -X POST \
-d 'data=%7B%22product_id%22%3A2111%2C%22face%22%3A500%2C%22email_to%22%3A%22ivan%40giftery.ru%22%2C%22from%22%3A%22Giftery%22%7D' \
'https://ssl-api.giftery.ru/?cmd=makeOrder&id=ID&in=json&out=json&sig=SIG'Результат запроса
{
"status": "ok",
"data": {
"id": 12345
}
}Тестовый режим
Обратите внимание, что в тестовом режиме вы можете отправить не более 15 писем в календарный день (по времени Мск), чтобы избежать возможного спама. При достижении лимита вы сможете вызывать makeOrder, но без отправки писем.
Отложенные заказы (delayed)
По запросу может быть включён особый режим, когда вместо генерирования ошибки 3601 (Некорректно заполнены поля: face) из-за нехватки кодов заказ будет создан в специальном статусе - delayed. Заказы в таком статусе не обрабатываются сразу. Заказ будет обработан, как только появятся необходимые для него коды. Возможна задержка в несколько часов, в отдельных случаях до нескольких дней. Данный режим не работает при недостаточном балансе, вместо этого будет возвращаться ошибка 5000 (Недостаточно средств).
Отличить такой заказ можно по параметру status при вызове getStatus, он будет содержать значение delayed. Или по ошибке 1208 (Заказ обрабатывается, ожидается поступление кодов) при запросе getLinks.
Данный режим подходит, если доставка сертификата пользователю в течение нескольких минут не является обязательным условием.
Callback
Если для Вас был настроен адрес для уведомления о созданных заказах, на него будут приходить данные методом POST. В ответ мы ожидаем HTTP код 200 и тело сообщения OK (латиницей, заглавными буквами, без дополнительных символов). При соблюдении двух этих условий мы считаем, что callback вызов был успешно принят удалённой системой. Если эти два условия не соблюдены то callback будет повторяться через 1, 2, 5, 15, 30, 60, 120 минут, если условия не соблюдены к последней отправки callback перестает отправляться и считается не принятым удалённой системой.
Формат callback
По желанию мы можем отправлять данные в виде JSON (Content-Type: application/json) или в виде urlencoded (Content-Type: application/x-www-form-urlencoded). Для отправки в формате JSON нужно явно указать это в запросе на подключение callback_url. По умолчанию запрос отправляется в виде urlencoded.
{
"status": "ok",
"data": {
"id": 34516345,
"uuid": "uuid при вызове makeOrder",
"order_id": 156765,
"product_id": 2111,
"face": 2000,
"sum": 2000,
"code": "KONKURS",
"comment": "победитель №345",
"external_id": "123456-1",
"gift_page_url": "https://my.giftery.app/gift/new/1156765qA1iO9vV2n"
}
}Параметр gift_page_url передаётся при успешной обработке заказа (status = ok) и содержит ссылку на страницу получения сертификата.
{
"status": "error",
"data": {
"id": 34516345,
"uuid": "uuid при вызове makeOrder",
"order_id": null,
"product_id": 2111,
"face": 2000,
"sum": 2000,
"code": "KONKURS",
"comment": "победитель №345",
"external_id": "123456-1"
},
"error": {
"code": 5000,
"text": "Недостаточно средств."
}
}Распространённые ошибки
| Код ошибки | Описание |
|---|---|
| 1102 | Отдельные бренды в нашем каталоге имеют дополнительные ограничения, вызванные лимитами поставщиков кодов. Данные лимиты поставщика могут быть наложены на количество заказов в месяц или на общую сумму заказов (баланс у поставщика). В случае, если наш баланс в удалённой системе поставщика 100 тысяч, то мы не имеем возможности выйти за него и выпустить сертификатов более этой суммы. Вопрос контроля и пополнения баланса у поставщиков обычно решается в течение одного-двух рабочих дней. |
| 3601 | Общий код ошибки при валидации входящих данных. Наиболее часто встречающиеся ошибки при передаче product_id и face параметров. Данные ошибки возникают в случае если передать в запрос параметры, которых нет в ответе getProducts. Продукты могут выключаться на нашей стороне, поэтому они будут отсутствовать в ответе getProducts и оформить сертификат по ним невозможно. Доступность отдельных номиналов может меняться в течение дня, получение ошибки с указанием на face говорит о том, что номинал временно закончился. Мы рекомендуем обновлять список продуктов раз в час в том случае, если вы не будете выполнять проверку доступности номиналов перед каждым выполнением makeOrder. |
| 5000 | Недостаточно средств. Необходимо пополнить баланс и повторить запрос. |