Работа с 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&param={"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: "$1$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&param={"orders":[{"id":3,"status_id":2}]}

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

В качестве параметров этот метод принимает массив заказов
Можно в одном запросе изменять сразу несколь заказов
{"orders":[{массив данных заказа 1},{массив данных заказа 2}]}

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

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

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

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

Тут мы поменяли метод на deleteOrder, он отвечает за удаление заказов
Он принимает массив "orders", в котором перечислены id заказов, которые нужно  удалить
Примеры итоговой записи параметров
Удаление 1 заказа
{"orders":[4]}
Для удаления большего количества заказов в 1 запросе, просто перечислим их
{"orders":[4,5,6,7,8,9,10]}

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

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

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

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