Работа с API

Работа с API доступна только на редакции Гипермаркет.

API Moguta.CMS позволяет взаимодействовать с магазином разработанном на движке Moguta.CMS из сторонних приложений. Это значит, что другие приложения, сайты, CRM, и тп. могут получить доступ к содержимому интернет-магазина и производить с ним различные операции. Таким образом сторонние приложения могут создавать и редактировать товары магазина, получать информацию о пользователях и производить другие дейтвия.

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

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

После того как вы добавили новое приложение в настройках, движок магазина готов к получению запросов из вне.
Мы подготовили php библиотеку для работы с API Moguta.CMS скачать ее можно тут. Пример использования находится в скачанном архиве в файле apiTest.php.

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

Как использовать класс mogutaApi (быстрый старт)

Создадим объект класса, передав в конструктор класса необходимые параметры 'адрес магазина', 'токен', 'секретный ключ':

$api = new mogutaApi('адрес магазина', 'токен', 'секретный ключ');

Отправим на сервер интернет-магазина команду test с произвольным массивом параметров $testParam. Команда test ничего не делает кроме того, что возвращает переданные ей данный назад.

$testParam = array('111', '222', '333');
$res = $api->run('test', $testParam, true);

Это тестовая функция, если все сделали правильно, то в ответ получим следующую информацию:

Array (
    [status] => OK
    [response] => Array(
            [0] => 111
            [1] => 222
            [2] => 333
        )

    [error] => 0
    [sign] => 0c71ad47ab03adef0970564abc71426d
    [workTime] => 0 ms
)

Главное поле для работы с API это responce, в нем сервер будет отдавать результат выполнения запрошенной команды.
В случае возникновения ошибки в поле error будет содержаться код ошибки, говорящий о том, что пошло не так. Коды ошибок:

1 - Неверный токен
2 - Ошибка вызова функции
3 - API не настроен

Как использовать API через GET запрос

Простой пример о том, как получить информацию о заказе.
Ссылка для получения заказ по его номеру.

http://site.ru/api?token=ключ-приложения&method=getOrder¶m={"number":["M-732468"]}

Из каких частей состоит ссылка

http://site.ru/api - ссылка к API в магазине
token=ключ-приложения - token это ключ приложения, который можно получить в панели управления сайта
method=getOrder - method это тот функционал, к которому хотим обратиться, в данном случае getOrder будет выдавать список заказов по различным параметрам
param={"number":["M-732468"]} - это параметры которые принимает метод. Имеет вид массива в формате JSON.

Возможные варианты параметров для метода getOrder

Поиск заказа по номеру заказа
Массив с номерами заказов, можно указать сразу несколько, в итоговом виде выглядит так

{"number":["M-123","M-223","M-323"]}

Поиск заказа по его id
Массив с id, можно указать сразу несколько, в итоговом виде выглядит так

{"id":[1,2,3,4,5]}

Поиск заказа по email покупателя
Массив с email, можно указать сразу несколько, в итоговом виде выглядит так

{"email":["user1@moguta.ru","user@moguta.ru"]}

Пакетная выгрузка всего списка заказов
Принимает в массиве 2 параметра:

page - номер пакета
count - размер пакета (количество заказов в одном пакете)

Итоговый вид

{"page":1,"count":15}

В ответ вы получите строку в формате JSON
Декодируйте ее и вы получите массив пригодный для обработки
Ниже приведен пример ответа после декодирования

{
   status: "OK",
   response: {
       orders: [
       {
           id: "3",
           updata_date: "2018-10-19 11:38:01",
           add_date: "2018-10-19 11:34:59",
           close_date: "2018-10-19 11:34:59",
           pay_date: "2018-10-19 11:34:59",
           user_email: "user@moguta.ru",
           phone: "+7 (654) 654 65-46",
           address: "",
           address_parts: {
               index: "123456",
               country: "Россия",
               region: "Санкт-Петербург",
               city: "Санкт-Петербург",
               street: "Выдумка",
               house: "15",
               flat: "99"
           },
           summ: "210201.60",
           order_content: [
               {
                   id: "98",
                   variant: "1153",
                   title: "Apple iPhone 6s 32 Чёрный",
                   name: "Apple iPhone 6s 32 Чёрный",
                   property: "",
                   price: "29834.15",
                   fulPrice: "35099",
                   code: "SKU207",
                   weight: "0",
                   currency_iso: "RUR",
                   count: "3",
                   coupon: "DC-U8NIZ-DLQJ4FN",
                   info: "хочу завтра товар",
                   url: "smartfony/apple-iphone-6s",
                   discount: "15",
                   discSyst: "false/false"
               },
               {
                   id: "62",
                   variant: "1194",
                   title: "Apple iPhone X 64 Оникс",
                   name: "Apple iPhone X 64 Оникс",
                   property: "",
                   price: "120699.15",
                   fulPrice: "141999",
                   code: "SKU222",
                   weight: "0",
                   currency_iso: "RUR",
                   count: "1",
                   coupon: "DC-U8NIZ-DLQJ4FN",
                   info: "хочу завтра товар",
                   url: "smartfony/apple-iphone-x",
                   discount: "15",
                   discSyst: "false/false"
               }
           ],
           delivery_id: "1",
           delivery_cost: "7000",
           delivery_interval: "",
           delivery_options: null,
           payment_id: "7",
           paided: "0",
           status_id: "0",
           user_comment: "хочу завтра товар",
           comment: "",
           confirmation: " ###IE[mg_page,html_content,299]### $PAVInqz9$Tule8VfkNDHWds7ePlz6e0",
           yur_info: {
               email: "",
               name: "",
               address: "",
               phone: "",
               inn: "4535569842153",
               kpp: "",
               nameyur: "ИП Василий",
               adress: "Россия, нижняя канава 39",
               bank: "Московский",
               bik: "025468546",
               ks: "654321894984654654641",
               rs: "54654968498746422656"
           },
           name_buyer: "Администратор",
           date_delivery: "19.10.2018",
           ip: "::1",
           number: "M-0106655179300",
           hash: "",
           1c_last_export: "2018-10-19 11:34:59",
           storage: "default",
           summ_shop_curr: "210201.6",
           delivery_shop_curr: "7000",
           currency_iso: "RUR"
           }
       ]
   },
   error: "0",
   sign: "9983652204815bf1a97dcea80533aeab",
   workTime: "0 ms"
}

Важные поля

id - идентификатор заказа в базе данных
user_email - email покупателя
phone - телефон покупателя
name_buyer - имя покупателя
addres - адресс доставки
address_parts - массив с подробным адрессом разбитым на блоки
summ - стоимость заказа без доставки в валюте заказа
delivery_cost - стоимость доставки в валюте заказа
currency_iso - валюта заказа
summ_shop_curr - сумма заказа без доставки в валюте магазина
delivery_shop_curr - сумма доставки в валюте магазина
delivery_id - id способа доставки
date_delivery - дата доставки
order_content - состав заказа (товары)
payment_id - id способа оплаты
status_id - id статуса заказа
yur_info - информация о юридическом лице

Стандартные статусы заказов

0 - не подтвержден
1 - ожидает оплаты
2 - оплачен
3 - в доставке
4 - отменен
5 - выполнен
6 - в обработке

Теперь попробуем изменить статус полученого заказа на "оплачен"

Для этого нам потребуеться ссылка такого вида

http://site.ru/api?token=ключ-приложения&method=importOrder¶m={"orders":[{"id":3,"status_id":2}]}

Основные части ссылки остались те же. Изменился method, для обновления и внесения новых заказов в магазин используется метод importOrder

В качестве параметров этот метод принимает массив заказов
Можно в одном запросе изменять сразу несколь заказов

{"orders":[{массив данных заказа 1},{массив данных заказа 2}]}

Массивы нужно формировать аналогично тому, что вы получаете при выгрузке заказов.
Если вы хотите обновить определенные параметры, весь этот список перечислять не нужно, укажите только то, что вам нужно поменять и обязательно укажите id.
Если вы хотите загрузить новый заказ, то тут уже придется формировать полный массив.

Теперь попробуем удалить заказ

Для этого нам потребуется ссылка вида

http://site.ru/api?token=ключ-приложения&method=deleteOrder¶m={"orders":[4]}

Тут мы поменяли метод на deleteOrder, он отвечает за удаление заказов.
Он принимает массив "orders", в котором перечислены id заказов, которые нужно удалить.
Примеры итоговой записи параметров.

Удаление 1 заказа

{"orders":[4]}

Для удаления большего количества заказов в 1 запросе, просто перечислим их

{"orders":[4,5,6,7,8,9,10]}

Были рассмотрены основные принципы для работы с API

Чтобы узнать о большем количестве методов и их параметрам перейдите по ссылке ниже

Подробное описание каждого метода для работы с API

Примеры работы с методами API