API Orders

Обзор

Данный документ описывает методы для работы поставщика/дистрибьютора по получению полного или отсортированного по статусу списка заказов, а также изменению и корректировке заказа поставщиком в системе Smart Satu.

Версия

Version: 1.0.0

Контактная информация

Contact: info@smartsatu.com

URI схема

Host : //food.smartsatu.com/api/ Schemes : HTTPS

Методы

Получение списка заказов

GET /v1/orders

Получение списка заказов в зависимости от статуса заказа

GET /v1/orders?status=

Изменение и корректировка заказа поставщиком

PUT /orders/{id}

Описание

Получение списка заказов

Для того чтобы получить список всех заказов необходимо отправить GET-запрос c пустым телом по URL: https://food.smartsatu.com/api/orders. В headers запроса обязательно должна передаваться страна пользователя, а также уникальный токен авторизации, который был получен при входе в систему. Ответом от сервера будет являться массив данных со списком всех ваших заказов в системе Smart Satu с их данными. Во всех заказах передается тип оплаты "payment_type", где:

• 0 = оплата заказа наличными;
• 1 = оплата заказа оборотными средствами;
• 2 = оплата заказа по Visa QR;
• 3 = оплата заказа по безналичному расчету;
• 4 = оплата заказа по Raiffeisen QR;
• 5 = оплата заказа корпоративной картой.

Получение списка заказов в зависимости от статуса заказа

Для того чтобы получить список заказов имеющих определенный статус необходимо отправить GET-запрос c пустым телом по URL: https://food.smartsatu.com/api/v1/orders. В строке запроса необходимо добавить параметр статуса и его значение (?status=1). В итоге получаем запрос вида: https://food.smartsatu.com/api/v1/orders?status=1. В headers запроса обязательно должна передаваться страна пользователя и уникальный токен авторизации, который был получен при входе в систему. Ответом от сервера будет являться массив данных со списком всех заказов поставщика в указанном статусе.

Также возможно получение списка заказов за период от времени, указанного в GET-параметре "updated_from", до времени выполнения запроса: "updated_from=2019-11-27T07:03:01".

Пример: https://food.smartsatu.com/api/v1/orders?status=7&updated_from=2019-11-27T07:03:01

Перечень статусов заказа:

Status	Description
status=1	Новый - заказ создан Торговой точкой
status=2	Принят - заказ в статусе "Новый" принят Поставщиком
status=3	Отклонен поставщиком - заказ в статусе "Новый" отклонен Поставщиком
status=4	Принят с корректировкой - заказ в статусе "Новый" принят Поставщиком с изменениями: откорректировано количество товара, изменена дата доставки
status=5	Подтвержден - заказ в статусе "Принят с корректировкой" принят Торговой точкой: ТТ согласна с внесенными в заказ изменениями
status=6	Отменен магазином - заказ в статусе "Принят с корректировкой" отклонен Торговой точкой: ТТ не принимает внесенные в заказ изменениями
status=7	Выполнен - заказ в статусе "Подтвержден"/"Принят" доставлен в Торговую точку: ТТ приняла все товары без изменений и подтвердила доставку
status=8	Не доставлен - заказ в статусе "Подтвержден"/"Принят" не доставлен в Торговую точку: ТТ меняет статус не доставленного заказа по прошествии 24 часов с установленной даты доставки
status=9	Не выполнен - заказ, изначально принятый Поставщиком, который не будет доставлен ТТ
status=10	Выполнен с корректировкой - заказ в статусах "Подтвержден"/"Принят" доставлен в Торговую точку, которая приняла не все товары (изменила количество) и подтвердила доставку

Изменение и корректировка заказа поставщиком

Для того чтобы изменить статус заказа, количество товаров или набор продуктов в заказе необходимо отправить PUT-запрос c JSON-телом по URL: https://food.smartsatu.com/api/orders/{id}, где id - это уникальный идентификатор заказа, который необходимо изменить.

При отправке данного PUT-запроса с id заказа {} не использовать. 

Поставщик может изменять новые заказы (status=1) на статусы, которые представлены в таблице ниже:

Status	Description
status=2	Принят: заказы, принятые поставщиком.
status=3	Отказ: заказы, отмененные поставщиком.
status=4	Принят с корректировкой: заказы, измененные поставщиком (наличие, количество, дата доставки).
status=9	Не выполнен - заказ, который был принят поставщиком, но не будет доставлен в торговую точку

Если заказ принят или отклонен, то запрос должен содержать обязательный параметр status и значение 2 (принят) или 3 (отклонен).

Если у заказа меняется status на 3 (отклонен), то, помимо обязательного параметра status, запрос должен содержать параметр comment.

Order_items в случае отклонения заказа передавать в запросе не нужно.

Если заказ должен быть изменен, то запрос должен содержать параметры offer_id и quantity.

Внимание: offer_id является параметром id в order_items:

Если были переданы не все товарные позиции из order_items, то отсутствующие позиции будут удалены системой из заказа.

Дополнительно со статусом заказа пользователю может отображаться статус поставщика. Для этого в теле PUT-запроса на изменение статуса (2, 3, 4 и 9) поставщик добавляет параметр "supplierStatus" с необходимым текстом статуса, например:

{
   "status": 2,
   "supplierStatus": "Заказ принят без изменений",
}

Безопасность

В headers запроса обязательно должна передаваться страна пользователя, а также уникальный токен авторизации, который был получен при входе в систему. Ответом от сервера будет являться массив данных с измененными данными заказа.

Type	In	Name	Description
Authorization	header	required	Для создания HTTP Basic Auth заголовка нужно преобразовать access_token следующим образом: $auth= "Basic " . base64encode(access_token . ":"); Данный токен должен использоваться в каждом запросе в системе.
country	header	required	Параметр страны должен использоваться в каждом запросе в системе.

Параметры

Type	Name	Description	Schema
Body	body required	Запрос на изменение заказа

Ответы

Response Orders Items:

HTTP Code	Description	Schema
200	Ok	Response Order Items
401	Unauthorized	401
403	Forbidden	403

Orders Status Change Response:

HTTP Code	Description	Schema
200	Ok	Order Status Change Response
401	Unauthorized	401
403	Forbidden	403

Принимаемые ресурсом типы MIME

• application/json

Возвращаемые ресурсом типы MIME

• application/json

Определения

Request Order Items

Name	Description	Schema	Example
offer_id	Идентификатор предложения	integer($int64)	3463374
quantity	Количество	integer($int64)	4

Пример запроса:

{
   "offer_id": 3463374,
   "quantity": 4
 }

Request Order Status Change

Name	Description	Schema	Example
comment	Комментарий	string	В наличии есть только 4 бутылки
items	Массив	< items> array	4
delivery_date	Дата доставки (строкой DD.MM.YYYY)	string	09.10.2019
status	Статус заказа	string	Принят с корректировкой: заказы измененные поставщиком (наличие, количество)

Items

Name	Description	Schema	Example
quantity	Количество	integer($int64)	4
offer_id	Уникальный номер предложения	integer($int64)	3463374

Пример запроса:

{
 "comment": "Изменена дата доставки и количество товара",
 "delivery_date": "09.10.2019",
 "items":
   [
       {
        "quantity": 50,
        "offer_id": 4166524
       }
   ],
 "status": 4
}

Response Orders

Items

Name	Description	Schema	Example
id	Уникальный идентификатор заказа	integer	258941
store_user_id	Идентификатор пользователя торговой точки	integer	656
store_company_id	Идентификатор торговой точки	integer	80
delivery_date	Дата доставки (time stamp с учетом time zone)	integer	1581292800
initial_delivery_date	Первоначальная дата доставки (time stamp с учетом time zone)	integer	1581292800
supplier_company_id	Идентификатор поставщика	string	84
supplierCompanyName	Идентификатор названия поставщика	string	ТОО "Поставщиk-"
status	Статус заказа	integer	1
created_at	Дата создания заказа	integer	1532517982
updated_at	Дата обновления заказа	integer	1532517982
with_documents	Наличие документов	integer	0
sum	Общая сумма заказа	decimal	11340.00
comments	Комментарий к заказу	array	Ок
replacement_id	Идентификатор заказа на обмен	string	null
replacement_status	Статус заказа на обмен	string	null
role	Роль пользователя, который оформил заказ	string	Торговый представитель
full_name	ФИО пользователя, который оформил заказ	string	Иван Иванов
alcohol_license	Алкогольная лицензия	object
number	Номер алкогольной лицензии	string	213
expire_at	Начало действия алкогольной лицензии	string	1522022400
expire_at_date	Конец действия алкогольной лицензии	string	26.03.2018
payment_type	Тип оплаты заказа	integer	0
payment_status	Статус оплаты заказа	integer	0
order_items	array	< order_items > array
supplier_company_name	Название поставщика	string	ТОО "Поставщиk-"
store_company	array	< store_company > array
service_fee_amount	Сумма сервисного сбора	decimal	300.00

Order Items

Name	Description	Schema	Example
id	Идентификатор наименования товара	integer($int32)	1631118
order_id	Идентификатор заказа	integer($int32)	204533
offer_id	Идентификатор предложения	integer($int32)	4134408
product_id	Идентификатор товара	integer($int32)	85067
quantity	Количество продукта	integer	1
initial_quantity	Начальное количество продукта	integer	1
quantity_decimal	Дробное значение продукта	string	1
initial_quantity_decimal	Начальное дробное значение продукта	string	1
amount	Общая сумма	string	2000
deleted	Удален	boolean	0
offer	Предложение	object
id	Идентификатор предложения	string	4345054
name	Название предложения	string	Воздух чистый, Алматинский ПЭТ 5л
sku	Штрих-код предложения	string	cash12039823407121
unit	Единица измерения предложения	string	шт
manufacturer	Производитель	string	null
quantity	Количество	string	1
expires_at	Годен до	string	null
price_1	Цена 1 (для магазинов)	string	1260
price_2	Цена 2 (для HoReCa)	string	1386
price_3	Цена 3 (для рынков)	string	1134
price_4	Цена 4	string	null
price_5	Цена 5	string	null
unique_code	Уникальный код	string	null
product_id	Идентификатор продукта	string	28952
step	Шаг	string	null
minQuantity	Минимальное количество товара для заказа	string	1.000
price	Цена для текущей ТТ	string	1260
product	Товар	object
id	Идентификатор товара	string	28952
name	Название продукта	string	Воздух чистый, Алматинский ПЭТ 5л
sku	Штрих-код предложения	string	cash12039823407121
unit	Единица измерения предложения	string	шт
manufacturer	Производитель	string	null
category_id	Идентификатор категории товара	string	360
images	array	< images > array
status	Статус товара	string	1
user_id	Идентификатор пользователя	string	132
is_weighted	Весовой товар	boolean	0
promotion_type	Признак бонусного товара	string	0

Images

Name	Description	Schema	Example
id	Идентификатор изображения	integer($int32)	1631118
product_id	Идентификатор продукта	string	28952
scr	Ссылка на изображение	string	https://cdn.smartsatu.com/food/images/products/7238_14752205982FZWw.jpg
thumb	Ссылка на изображение	string	https://cdn.smartsatu.com/food/images/products/7238_14752205982FZWw.jpg

Store company

Name	Description	Schema	Example
route_list	Идентификатор наименования товара	string	null
name	Идентификатор заказа	string	маг. "Рокфор"
min_order_price	Минимальная сумма заказа	integer	0
email	Адрес электронной почты	string	shop@me.kz
description	Описание	string	Магазин для тестирования\r\n
address	Адрес торговой точки	string	Алматы, Байзакова, 125/185
conact	Контактные данные	string	Телефон: +78000000001, Вн.: 123, Контактное лицо: Гайка
type	Тип торговой точки	string	store
tin	ИНН торговой точки	string	0123456789
phone	Номер телефона	string	+78000000001
supplier_rule	Правила поставщика	string	null
logo	Логотип	string	https://food.smartsatu.com/images/no_image_130x130.png
has_replacement_products	Обмен товаров	string	1
cashback_percent	Кэшбэк включен	string	true
has_cashback	Кэшбэк включен и активен	string	false
position	Позиция для сортировки	integer	999
supplier_store_id	UCS-код торговой точки	string	3214567

Пример ответа:

{
 "items": [
   {
     "id": "258941",
     "store_user_id": 656,
     "store_company_id": 656,
     "delivery_date": "1581292800",
     "initial_delivery_date": "1581292800",
     "supplier_company_id": "84",
     "supplierCompanyName": "ТОО \"Поставщиk-",
     "status": "1",
     "created_at": 1532517982,
     "updated_at": 1532517982,
     "with_documents": 0,
     "sum": 11340,
     "comments": "Ок",
     "replacement_id": " ",
     "replacement_status": " ",
     "role": "Торговый представитель"
     "full_name": "Иван Иванов"
     "alcohol_license": {
       "number": "213",
       "expire_at": "1522022400",
       "expire_at_date": "26.03.2018"
     },
     "payment_type": 0,
     "payment_status": 0
     "order_items": [
       {
         "id": 1631118,
         "order_id": 204533,
         "offer_id": 4134408,
         "product_id": 85067,
         "quantity": 1,
         "initial_quantity": 1,
         "quantity_decimal": 1,
         "initial_quantity_decimal": 1,
         "amount": 2000,
         "deleted": 0,
         "offer": {
           "id": "4345054",
           "name": "Воздух чистый, Алматинский ПЭТ 5л",
           "sku": "cash12039823407121",
           "unit": "шт",
           "manufacturer": " ",
           "quantity": "1",
           "expires_at": " ",
           "price_1": "1260",
           "price_2": "1386",
           "price_3": "1134",
           "price_4": " ",
           "price_5": " ",
           "unique_code": "",
           "product_id": "28952",
           "step": "",
           "minQuantity": "1.000",
           "price": "1260"
         },
         "product": {
           "id": "28952",
           "name": "Воздух чистый, Алматинский ПЭТ 5л",
           "sku": "9890000033839",
           "unit": "шт.",
           "quantity": "1",
           "manufacturer": " ",
           "category_id": "360",
           "images": [
             {
               "id": "39236",
               "product_id": "28952",
               "scr": "https://cdn.smartsatu.com/food/images/products/7238_14752205982FZWw.jpg",
               "thumb": "https://cdn.smartsatu.com/food/images/products/7238_14752205982FZWw.jpg"
             }
           ],
           "status": "1",
           "user_id": "132",
           "is_weighted": 0
         },
         "promotion_type": "0"
       }
     ],
     "Supplier_company_name": "ТОО \"Поставщиk-",
     "store_company": {
       "address": "Алматы, Байзакова, 125/185",
       "min_order_price": 0,
       "description": "Магазин для тестирования\\r\\n",
       "cashback_percent": "true",
       "supplier_rule": "NULL",
       "type": 1,
       "has_replacement_products": "1",
       "has_cashback": "false",
       "phone": "+78000000001",
       "route_list": "",
       "contact": "Телефон: +78000000001, Вн.: 123, Контактное лицо: Гайка",
       "name": "маг. \"Рокфор",
       "tin": "0123456789",
       "logo": "https://food.smartsatu.com/images/no_image_130x130.png",
       "id": "80",
       "position": 999,
       "email": "shop@me.kz"
       "supplier_store_id": "3214567"
     }
   }
 ]
}

Orders Status Change Response

Name	Description	Schema	Example
id	Уникальный идентификатор заказа	integer($int32)	null
store_user_id	Идентификатор пользователя торговой точки	integer($int32)	маг. "Рокфор"
store_company_id	Идентификатор торговой точки	integer($int32)	0
supplier_company_id	Идентификатор поставщика	integer($int32)	shop@me.kz
supplierCompanyName	Идентификатор названия поставщика	string	Магазин для тестирования\r\n
status	Статус заказа	integer($int32)	Алматы, Байзакова, 125/185
created_at	Время создания заказа	integer($int32)	Телефон: +78000000001, Вн.: 123, Контактное лицо: Гайка
updated_at	Время обновления заказа	integer($int32)	store
with_documents	Доставка заказа с документами	integer($int32)	0123456789
sum	Сумма заказа	integer($int32)	+78000000001
comments	Массив	< comments > array
replacement_id		integer	null
replacement_status		integer	null

Comments

Name	Description	Schema	Example
id	Идентификатор комментария	integer	75875
company_id	Идентификатор поставщика	integer	84
message	Текст комментария	string	Вот такой комментарий
type	Статус заказа	string	4
order_id	Уникальный идентификатор заказа	integer	153390
created_at	Время создания	string	1540376988
companyName	Идентификатор названия поставщика	string	ТОО "Поставщиk-"
is_system	Системное сообщение	string	null

Пример ответа:

{
 "id": 153390,
 "store_user_id": 656,
 "store_company_id": 80,
 "supplier_company_id": 84,
 "supplierCompanyName": "ТОО \"Поставщиk-\"",
 "status": 2,
 "created_at": 1497429666,
 "updated_at": 1497431046,
 "with_documents": 1,
 "sum": 8663,
 "comments": [
   {
     "id": 75875,
     "company_id": 84,
     "message": "Вот такой комментарий",
     "type": 4,
     "order_id": 153390,
     "created_at": 1540376988,
     "companyName": "ТОО \"Поставщиk-\"",
     "is_system": "Null"
   }
 ],
 "replacement_id": null,
 "replacement_status": null
}

401

Name	Description	Schema	Example
name	Название поставщика	string	Unauthorized
message	Сообщение	string	Your request was made with invalid credentials
code	Код	integer($int32)	0
status	Статус	integer($int32)	401
type	Тип	string	"yii\\web\\UnauthorizedHttpException"

Пример ответа:

{
 "name": "Unauthorized",
 "message": "Your request was made with invalid credentials.",
 "code": 0,
 "status": 401,
 "type": "yii\\web\\UnauthorizedHttpException"
}

403

Name	Description	Schema	Example
name	Название поставщика	string	Forbidden
message	Сообщение	string	You're not allowed to delete this item
code	Код	integer($int32)	0
status	Статус	integer($int32)	403
type	Тип	string	"yii\\web\\HttpException"

Пример ответа:

{
 "name": "Forbidden",
 "message": "You're not allowed to delete this item.",
 "code": 0,
 "status": 403,
 "type": "yii\\\\web\\\\HttpException"
}