Метод служит для передачи информации о покупках в систему SailPlay.
В отличие от метода /api/v1/purchases/new/ в версии 2 производится рассчет акций, для чего состав корзины становится обязательным параметром. Также были убраны параметры модицифирующие количество начисляемых баллов (этот функциона перенесен в раздел акции) и немного поменялся формат корзины.
Параметр обязательный? | Имя параметра | Описание параметра |
нет | user_phone или email или origin_user_id | Идентификатор клиента. Более подробно см. здесь . Если не передать параметр – покупка будет записана как анонимная, без ссылки на клиента. |
да | token | См. здесь |
да | store_department_id | см. здесь |
да | pin_code | см. здесь |
да | order_num | Номер заказа в вашей системе. |
да | cart | Json объект, содержащий в себе информацию о составе корзины. Для объекта каждоый позиции передаются параметры sku - идентификатор товара, price - суммарная стоимость товаров в позиции, количество товаров в позиции. |
нет | cart_id | Идентификатор корзины, полученный на этапе предварительного рассчета (метод /api/v2/marketing-actions/calc/). Если передается cart_id состав корзины cart можно не передавать. |
нет | purchase_dep_id | Идентификатор целевого подразделения, в котором необходимо создать покупку. При отсутствии покупка будет создана в том подразделении, store_department_id которого передается. |
нет | purchase_dep_origin_id | Идентификатор подразделения, использующий origin_id каждого подразделения. При отсутствии покупка будет создана в том подразделении, origin_id которого передается. |
нет | promocodes | Массив со списком промокодов, которые нужно применить к покупке. Например,promocodes=["summer2017"]. |
нет | force_complete | Флаг. Если данный флаг установлен (force_complete=1), транзакция считается подтвержденной несмотря на флаг в настройках. Данный атрибут может быть использован, например, в случае когда часть оплат необходимо подтверждать, а про остальные известно что они уже подтверждены. Более подробно см. здесь . |
http://sailplay.ru/api/v2/purchases/new/?store_department_id=219&token=024e3bfbe50c8ef3d413caf1erwf5380bbdd79df3&order_num=171&cart={"1":{"sku":"1","price":1000, "quantity":1},"2":{"sku":"2","price":300, "quantity":3}}&origin_user_id=cart1&pin_code=104443
{ "status": "ok", "purchase": { "is_completed": false, "store_department_id": 219, "completed_date": null, "order_num": "171", "id": 23141, "points_delta": 410, "public_key": "a45939f44e6c6783ad8d38562e083a6fda233e29", "user_id": 340774, "purchase_date": "2015-06-02T15:00:16.129", "clerk_pin": "104443", "price": "1200.00" }, "cart": { "marketing_actions_applied": [ { "client_msg": "2", "service_msg": "1", "alias": "3" } ], "possible_marketing_actions": [], "cart": { "positions_count": 1, "extra_points": {}, "total_points": 0, "upsaled": [], "id": 615355613, "text_blocks": [ {"marketing_action": { "count": null, "total_quantity_applied": null, "service_msg": null, "name": "Печать на чек", "alias": "Печать на чек", "client_msg": null, "till_date": null, "total_discount": null }, "value": "Текстовое поле для печати на чек \n Новая строка"} ], "total_price": "0.00", "positions": [ { "category": { "sku": "elphnt", "id": 271 }, "product": { "sku": "1", "id": 203 }, "num": 1, "marketing_actions": [], "price": "1000.00", "new_price": "1000.00", "points": 400, "points_rate": "0.4000", "quantity": "1" }, { "category": { "sku": "default", "id": 196 }, "product": { "sku": "2", "id": 205 }, "num": 2, "marketing_actions": [ "3" ], "price": "300.00", "new_price": "200.00", "points": 10, "points_rate": "0.0500", "quantity": "3" } ], "positions_count": 2, "total_price": "1200.00", "id": 1097 } } }
Служит для получения информации о составе, стоимости и начисленных бонусных баллах покупки а также клиенте.
Параметр обязательный | Название параметра | Описание параметра |
да | order_num | Номер заказа |
да | token | См. здесь |
да | store_department_id | См. здесь |
Название параметра | Описание параметра |
status | |
purchase | объект с инфомрацией о покупке |
is_completed | подтверждена ли покупка |
store_department_id | идентификатор департамента покупки |
completed_date | дата подтверждения |
order_num | идентификатор заказа |
points_delta | количество начисленных баллов |
public_key | ключ подтверждения покупки |
user_id | внутренний идентификатор клиента в системе SailPlay |
purchase_date | дата совершения покупки |
clerk_pin | пинкод клиента |
price | сумма покупки |
cart | объект описания корзины |
http://sailplay.ru/api/v2/purchases/get/?store_department_id=435&token=b3c7ac443b9843bf4daa20f54292655b5f77bb4b&order_num=136
{ "status": "ok", "purchase": { "is_completed": false, "store_department_id": 435, "completed_date": null, "order_num": "42260", "id": 11916548, "points_delta": 25, "public_key": "7d46d2b7c74c418c9559621e85f97afcc1eddbe2", "user_id": 6556846, "purchase_date": "2015-05-12T17:49:01", "clerk_pin": "1231", "price": 500 }, "cart": { "marketing_actions_applied": [ { "client_msg": "Уведомление об успехе!", "service_msg": "Уведомление о возмоности!", "alias": "all" } ], "possible_marketing_actions: []," "cart": { "total_points": 25, "positions": [ { "category": { "sku": "default", "id": 707 }, "product": { "sku": "ugly", "id": 485226 }, "num": "1", "points_rate": "0.05000", "price": "600.00", "quantity": "1.0000", "new_price": "300.00", "points": 15 }, { "category": { "sku": "default", "id": 707 }, "product": { "sku": "2", "id": 485224 }, "num": "2", "points_rate": "0.05000", "price": "400.00", "quantity": "1.0000", "new_price": "200.00", "points": 10 } ], "positions_count": 2, "total_price": "500.00", "id": 1547 } } }
Служит для изменения пользователя, к которому привязана покупка.
Параметр обязательный | Название параметра | Описание параметра |
да | order_num или purchase_id | Номер заказа, либо ID транзакции в системе SailPlay (более подробно см. п. 2.1) |
да | token | См. здесь |
да | store_department_id | См. здесь |
да | user_phone или email или origin_user_id | Идентификатор клиента. Более подробно см. здесь . |
Название параметра | Описание параметра |
status | |
id | Уникальный ID измененной транзакции |
order_num | Номер измененного заказа |
user | Данные о пользователе, к которому теперь привязана покупка |
http://sailplay.ru/api/v1/purchases/edit/?token=206f37f4fbf70db81b330d8187beed7a3b507a0f&store_department_id=*&order_num=9988&origin_user_id=12200247
В случае успеха:
{
"order_num": "9988",
"status": "ok",
"id": 68283629,
"user": {
"full_phone": "",
"phone": "+7 (916) 1***-05",
"origin_user_id": "12200244",
"last_name": "Тепцова",
"first_name": "Татьяна",
"points": 0,
"id": 36151702,
"email": "tteptsova@yandex.ru"
}
}
В случае неуспеха:
{
"status": "error",
"status_code": -3003,
"message": "Impossible to change purchase user"
}
Метод служит для подтверждения покупок в систему SailPlay.
Отличие от метода /api/v1/purchases/confirm/ в формате передачи состава корзины - в версии 2 это json объект, аналогично /api/v2/purchases/new/.
Служит для удаления покупки и отмены начисления бонусных баллов за совершенную покупку.
Допустим пользователь совершил покупку и получил 1000 бонусных баллов, а затем получил подарок на 100 бонусных баллов. В этом случае запрос на удаление покупки вернет ошибку, потому что после его удаления у пользователя останется отрицательное количество бонусных баллов. Чтобы решить эту проблему, предварительно необходимо удалить транзакцию о выдаче подарка.
При удалении покупки у клиента уменьшается счетчик тега Покупка на 1. Если покупка была подтверждена, то уменьшается и тег Подтверждение покупки. Если счетчик тегов после уменьшения равен 0, то теги удаляются.
Параметр обязательный | Название параметра | Описание параметра |
да | order_num или purchase_id | Номер заказа, либо ID транзакции в системе SailPlay (более подробно см. п. 2.1) |
да | token | См. здесь |
да | store_department_id | См. здесь |
Название параметра | Описание параметра |
status | |
id | Уникальный ID удаленной транзакции |
order_num | Номер удаленного заказа |
http://sailplay.ru/api/v1/purchases/delete/?store_department_id=32&token=0e96be0867401601df4c6e8691476bfaaa73f3&order_num=12345
В случае успеха:
{
"order_num": "12345",
"status": "ok",
"id": 9676
}
В случае неуспеха (если у пользователя не хватает бонусных баллов, т.е. если перед этим предварительно не был удален подарок):
{
"status":"error",
"status_code": -3001,
"message":"Impossible to delete purchase"
}
Для создания покупки в системе SailPlay используйте данный метод. Вся логика, связанная с начислением бонусных баллов, бейджиков и статусов, автоматически запускается после обращения к данному методу.
Процесс выглядит следующим образом:
Для случаев, когда
предлагаем воспользоваться механизмом работы с корзиной.
Работает это следующим образом: в запросе на начисление / подтверждение бонусных баллов дополнительно передается параметр positions, имеющий следующий формат:
postion_id_1,[category_id_1,]sum_1[:...:postion_id_N,[category_id_N,]sum_N]
где
Параметр обязательный | Название параметра | Описание параметра |
да | position_id | SKU товара в вашем каталоге (может содержать латинские символы и цифры) |
да | category_id | ID категории для данного товара в вашем каталоге |
да | sum | Сумма (стоимость для данного товара) |
Как видно из формата, параметр категории является необязательным.
При разборе состава корзины, применяются следующие правила5
Если товара с данным SKU или группы с данным ID нет в базе данных SailPlay - они создаются автоматически
Если для данного товара нет специального коэффициента конвертации, проверяется есть ли коэффициент конвертации для данной категории, если и его нет - используется стандартный
Если в массиве передан один и тот же товар несколько раз - их суммы предварительно складываются.
Параметр обязательный? | Имя параметра | Описание параметра |
да | user_phone или email или origin_user_id | Идентификатор клиента. Более подробно см. здесь . |
да | token | С м. здесь |
да | store_department_id | см. здесь |
да | pin_code | см. здесь |
да | price | Полная сумма покупки в местной валюте |
нет | fields | Дополнительные поля, которые будут в JSON ответе. Дополнительные поля перечисляются через запятую и могут принимать следующие значения: public_key, order_num. Пример: &fields=public_key,order_num |
нет | points_rate | Коэффициент конвертации рублей в баллы. Может принимать значение из полуинтервала (0,1]. При отсутствии данного параметра, используется значение, указанное в настройках. Формат points_rate=0.45 |
нет | order_num | Номер заказа в вашей системе (используется в случае, если выбран механизм с подтверждением факта оплаты. Подробнее см. здесь ) |
нет | force_complete | Флаг. Если данный флаг установлен (force_complete=1), транзакция считается подтвержденной несмотря на флаг в настройках. Данный атрибут может быть использован, например, в случае когда часть оплат необходимо подтверждать, а про остальные известно что они уже подтверждены. Более подробно см. здесь . |
нет | positions | Массив товаров внутри данной покупки (состав корзины). Имеет формат “positions=1899,13,200:101,10,379” - в группах, разделенных двоеточиями, передается ID-товаров в вашей системе, ID группы товара (опционально) и его стоимость Если покупок с данным ID товара несколько - передавать этот ID нужно несколько раз. Служит для возможности начисления бонусных баллов с разными коэффициентами (например, если есть необходимость за товары определенной категории начислять в 2 раза больше бонусных баллов). Более подробно см. здесь . Важно: суммы должны иметь тип int. |
нет | user_category_name | категория пользователя ( см. здесь ) |
Название параметра | Описание параметра |
status | |
purchase | Данные о транзакции |
complete_date | Дата и время окончания транзакции |
price | Переданная в запросе сумма |
id | Уникальный ID транзакции |
points_delta | Начисленные пользователю баллы за эту покупку |
user | Данные о пользователе, его баллах |
phone | Номер телефона пользователя в форматированном виде (если информация есть в системе SailPlay) |
full_name | Полное имя пользователя (если информация есть в системе SailPlay) |
Электронный адрес (если информация есть в системе SailPlay) | |
public_key | Возвращается только, если был указан в запросе в параметре fields. Hash транзакции покупки. Используется для подставноки в JS-код popup'а для автоматического открытия попапа после покупки. |
order_num | Возвращается только, если был указан в запросе в параметре fields.Номер заказа в вашей системе. |
attrs | Атрибут покупки. Возможно указать любую информацию о покупке, которая понадобится в дальнейшем, например, тип платежа или время, которое заняла покупка. |
http://sailplay.ru/api/v1/purchases/new/?store_department_id=219&cart={"1": {"sku": "1","price": "100","quantity": 3,"discount_points": 40},"2": {"sku": "2","price": "100", "quantity": 3,"discount_points": 30} }&order_num=327924&pin_code=1111&origin_user_id=25547&token=024e3bfbe50c8ef3d413caf19bf5380bbdd79df3&attrs={"processing_time":"249","payment_type":"card"}
{ "status": "ok", "purchase": { "complete_date": "2013-01-25T00:31:42.642", "price": "10", "id": 8, "points_delta": 4, "public_key": ";ao08rj3tj09fu9jkwer20393urjflshg54h", "order_num": 132123 }, "user": { "phone": "700000000", "points": 28, "full_name": "Кирилл Иванович Лавров" }, "email": "sales@sailplay.ru" }
В SailPlay реализован механизм для подтверждения бонусных баллов, полученных за покупки. Использовать его можно, например в случае, когда пользователю за покупку начисляются бонусные баллы сразу после формирования заказа, но пользователь в последствии может отказаться от заказа.
Реализовано это следующим образом: устанавливается время жизни “неподтвержденных” бонусных баллов. По прошествии этого срока, если оплата не была подтверждена, бонусные баллы будут списаны автоматически. В период, пока покупка не подтверждена и срок не истек, пользователь не сможет получить подарок.
Кроме этого, в методе purchases/new реализован механизм подтверждения платежей (см. здесь )
В запросе используется параметр order_num - номер заказа/платежа (это номер заказа в вашей системе, который был передан в запросе на начисление бонусных баллов). Вместо него может быть использован purchase_id - ID транзакции в системе SailPlay, который возвращается в ответе на запрос о начислении бонусных баллов. При этом, если переданы оба параметра, то приоритет отдается purchase_id.
Параметр обязательный | Название параметра | Описание параметра |
да | token | См. здесь |
да | store_department_id | См. здесь |
да | order_num (либо purchase_id) | Номер заказа в вашей системе (либо ID транзакции, который возвращается в ответ на запрос начисления бонусных баллов) |
нет | new_price | Актуальная цена (цена после подтверждения, если изменилась) |
нет | positions | Массив товаров внутри данной покупки (состав корзины). Имеет формат “positions=1899,200:101,379” - в группах, разделенных двоеточиями, парами идут ID-товаров в вашей системе и стоимость. Если покупок с данным ID товара несколько - передавать этот ID нужно несколько раз. Важно: суммы должны иметь тип int. |
http://sailplay.ru/api/v1/purchases/confirm/?store_department_id=1&token=b301f9928dda6499a74755491767208f3b156867&order_num=12344&new_price=12344&positions=1899,200:101,379
Полностью идентичен ответу сервера при начислении бонусных баллов ( см. здесь )
Служит для изменения данных покупки путём её пересоздания.Перепривязка покупки к другому пользователю возможна при передаче идентификатора пользователя без параметра cart/cart_id.
Параметр обязательный | Название параметра | Описание параметра |
да | order_num или purchase_id | Номер заказа, либо ID транзакции в системе SailPlay |
да | token | См. здесь |
да | store_department_id | См. здесь |
да | user_phone или email или origin_user_id | Идентификатор клиента, которому надо перепривязать покупку. Более подробно см. здесь . |
да | cart | Json объект, содержащий в себе информацию о составе корзины. Для объекта каждоый позиции передаются параметры sku - идентификатор товара, price - суммарная стоимость товаров в позиции, количество товаров в позиции. |
нет | cart_id | Идентификатор корзины, полученный на этапе предварительного рассчета (метод /api/v2/marketing-actions/calc/). Если передается cart_id состав корзины cart можно не передавать. |
нет | purchase_dep_id | Идентификатор целевого подразделения, в котором необходимо создать покупку. При отсутствии покупка будет создана в том подразделении, store_department_id которого передается. |
нет | purchase_dep_origin_id | Идентификатор подразделения, использующий origin_id каждого подразделения. При отсутствии покупка будет создана в том подразделении, origin_id которого передается. |
нет | promocodes | Массив со списком промокодов, которые нужно применить к покупке. Например,promocodes=["summer2017"]. |
https://sailplay.ru//api/v2/purchases/edit/?token=s1232dsf1313e13r&store_department_id=435&order_num=нгшщз&cart={"0":{"sku":"3","price":299,"quantity":1,"discount_points":0,"min_price":0},"1":{"sku":"2","price":76,"quantity":1,"discount_points":0,"min_price":0},"2":{"sku":"1","price":160,"quantity":10,"discount_points":0,"min_price":0}}&verbose=1&attrs={"delivery_type":"courier","source_order":"site"}
В случае успеха:
{ "status": "ok", "purchase": { "is_completed": false, "store_department_id": 435, "completed_date": null, "attrs": { }, "order_num": "нгшщз", "id": 560213002, "points_delta": 299, "public_key": "cd3551f7d1b05282173a8c6fd25875fd15431c6d", "user_id": 149373710, "purchase_date": "2021-06-30T08:45:14.790", "clerk_pin": "1096", "price": 299 }, "cart": { "cart": { "positions_count": 1, "extra_points": { "actions_applied": [ ], "points_delta": 0 }, "total_points": 299, "upsaled": [ ], "id": 1413792514, "text_blocks": [ ], "total_price": "299.00", "total_discount_points_max_for_user": 0, "positions": [ { "custom_attrs": [ ], "category": { "sku": "default", "id": 707, "name": "Стандартная" }, "product": { "sku": "3", "id": 494331, "name": null }, "employee_id": 1293, "discount_points_max": 0, "reverse_points_rate": [ ], "price": "299.00", "expiry_info": [ ], "new_price": "299.00", "min_price": "0.00", "num": 0, "marketing_actions": [ ], "quantity": "1.0000", "points_rate": "1.00000", "discount_points": 0, "points": 299 } ], "parent_id": null, "params": { }, "total_discount_points_max": 0 }, "marketing_actions_applied": [ ], "possible_marketing_actions": [ { "client_msg": null, "service_msg": null, "name": "тестАРТ", "alias": "тестАРТ" }, { "client_msg": "", "service_msg": "", "name": "нгшщз", "alias": "нгшщз" } ], "recommendations": [ ], "cart_returns": [ ] } }
Служит для изменения данных покупки путём её пересоздания.Перепривязка покупки к другому пользователю возможна при передаче идентификатора пользователя без параметра cart/cart_id.
Параметр обязательный | Название параметра | Описание параметра |
да | order_num или purchase_id | Номер заказа, либо ID транзакции в системе SailPlay |
да | token | см. здесь |
да | store_department_id | см. здесь |
https://sailplay.ru/api/v2/purchases/restore?store_department_id=435&token=s1232dsf1313e13r&order_num=20800842
В случае успеха:
{ "status":"ok", "purchase":{ "is_completed":false, "store_department_id":5253, "completed_date":null, "order_num":"20800842", "id":213268561, "points_delta":4, "public_key":"bb1d855f2accfb8af891ec7fee8208f0bf5778d4", "user_id":44978246, "purchase_date":"2018-07-04T07:46:36.963", "clerk_pin":"1647", "price":492 } }