API документация

Общая информация

API - используется для внесения и получения данных в программу "Партнёр:Магазин" из внешних/сторонних сервисов, например, прием заказов в программу из сайта автоматически, и отображение на сайте статуса заказа.

Взаимодействие с API происходит с помощью отправки HTTP запроса POST (application/x-www-form-urlencoded) на адрес API

Авторизация

Авторизация на API происходит с помощью токена - ключа авторизации.

Токен можно получить/изменить в программе учета в разделе Настройки.

С помощью токена происходит определение пользователя программы Партнёр.

Токен API авторизации

В случае если токен задан не верно в ответ от сервера придет ошибка с указанием параметра error: token_invalid

Отправка запроса

Адрес для запроса: - https://shop.mypar.ru/api/?метод

Для каждого метода определены обязательные параметры.

Сервер отправит ответ в виде JSON массива.

Общие обязательные параметры для всех запросов:

В ответе обязательно содержится параметр result, в случае успешной обработки его значение: success

Ограничения

Количество отправки запросов ограничено -

не более 60 запросов в секунду с одного IP адреса

В случае превышения лимита - сервер ответит ошибкой - limit_requests.

Ошибки

Ошибки разделяются на критичные (ошибки, при возникновении которых действие не происходит) и уведомления.

Критичные ошибки

В случае возникновения критичной ошибки API отправляет в ответ JSON массив:

result: error;

error: ошибка;

Пример ответа от сервера API при неправильном указании токена:

Ответ API:

     {
         "result":"error",
         "error":"token_invalid"
     }

Уведомления

Уведомления указываются в ответе как параметр warnings.

warnings - массив уведомлений, в котором указываются причины уведомления,

Например, при отправке заказа для формирования с несуществующим статусом, заказ сохранится, но при этом в ответе будет содержаться уведомление.

Пример отправки заказа с кодом статуса "124" (не существующим)

Ответ API:

         {
             "result":"success",
             "order_id":"98",
             "order_number":53,
             "warnings":
                 {
                     "status_invalid":124
                 }
         }
     

Общие возможные ошибки для всех методов

Критичные:

Операции и информация

Сохранение заказа

В разделе Настройки, можно включить опцию - Принимать цену на позицию по API

Принимать цену на позицию по API

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

Адрес для запроса: - https://shop.mypar.ru/api/?order_add

Обязательные параметры для запроса:

Дополнительные параметры для запроса:

Привязка улицы к заказу

Если параметр street_id указан:

используется улица из справочника с соответствующим идентификационным кодом (См. в «Справочники» – «Улицы» - код API).

Если параметр street_id не указан или не найден в справочнике:

проверяются параметры city (город) и street (улица):

для привязки улицы к заказу параметр street – должен быть заполнен обязательно;

При включенной функции автоматического определения филиала по адресу обязательно должен быть указан город (параметр city), при этом город должен присутствовать в справочнике.

При выключенной функции автоматического определения филиала, в случае, если город (параметр city) не указан или отсутствует в справочнике – используется город филиала (см. в «Управление» - «Филиалы» - Город).

Если не указан параметр branch (филиал) – устанавливается филиал по умолчанию, код API – 1 (см. в «Управление» - «Филиалы» - код API).

Пример отправки запроса сохранения заказа на PHP используя Curl.

        /*    Подготовка данных на стороне интернет-магазина/приложения/сервиса    */

        $product[0] = "14"; //Позиция с артикулом 14 - Салат цезарь
        $product[1] = "10001"; //Позиция с артикулом 10001 - Пицца Гавайская
        $product[2] = "10003"; //Позиция с артикулом 10003 - Помидоры

        $product_amount[0] = "2";
        $product_amount[1] = "1";
        $product_amount[2] = "1";

        $table = 3;

        $name = "Антон";

        $token = "Значение_токена";

        $webhook_url = "https://myserver.com";

        $webhook_statuses = "4, 13, 10";

        /*    Подготовка данных для отправки запроса    */

        $data = "";
        $data .= "token=" . $token . "&";
        $data .= "name=" . $name . "&";
        $data .= "table=" . $table . "&";
        $data .= "webhook_url=" . $webhook_url . "&";
        $data .= "webhook_statuses=" . $webhook_statuses . "&";

        foreach ($product as $key => $value) {
            $data .= "product[" . $key . "]=" . $value . "&";
            $data .= "product_amount[" . $key . "]=" . product_amount[$key] . "&";
            if (isset($product_parent[$key])) {
                $data .= "product_parent[" . $key . "]=" . $product_parent[$key] . "&";
            }
        }

        /*    Отправка с помощью CURL    */

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://shop.mypar.ru/api/?order_add");
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
        curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER,true);
        curl_setopt($ch, CURLOPT_AUTOREFERER,true);
        curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
        curl_setopt($ch, CURLOPT_COOKIESESSION,true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 3);
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
        $result = curl_exec($ch);

        /*    Вывод на экран информации о результате    */

        if ($result == NULL) {
            echo "Error:\n";
            echo curl_errno($ch) . " - " . curl_error($ch) . "\n";
        }
        curl_close($ch);
        echo $result;

Возможные критические ошибки:

Возможные уведомления:

Ответ API (успешный):

Изменение заказа

С помощью API можно внести изменения в заказ.

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

Адрес для запроса: - https://shop.mypar.ru/api/?order_edit

Обязательные параметры для запроса:

Дополнительные параметры для запроса:

Привязка улицы к заказу

Если параметр street_id указан:

используется улица из справочника с соответствующим идентификационным кодом (См. в «Справочники» – «Улицы» - код API).

Если параметр street_id не указан или не найден в справочнике:

проверяются параметры city (город) и street (улица):

для привязки улицы к заказу параметр street – должен быть заполнен обязательно;

При включенной функции автоматического определения филиала по адресу обязательно должен быть указан город (параметр city), при этом город должен присутствовать в справочнике.

При выключенной функции автоматического определения филиала, в случае, если город (параметр city) не указан или отсутствует в справочнике – используется город филиала (см. в «Управление» - «Филиалы» - Город).

Если не указан параметр branch (филиал) – устанавливается филиал по умолчанию, код API – 1 (см. в «Управление» - «Филиалы» - код API).

Пример отправки запроса изменения заказа на PHP используя Curl.

        /*    Подготовка данных на стороне интернет-магазина/приложения/сервиса    */

        $product[0] = "14"; //Позиция с артикулом 14 - Салат цезарь
        $product[1] = "10001"; //Позиция с артикулом 10001 - Пицца Гавайская
        $product[2] = "10003"; //Позиция с артикулом 10003 - Помидоры

        $product_amount[0] = "2";
        $product_amount[1] = "1";
        $product_amount[2] = "1";

        $order_id = 11221;

        /*    Подготовка данных для отправки запроса    */

        $data = "";
        $data .= "order_id=" . $order_id . "&";
        $data .= "token=" . $token . "&";

        foreach ($product as $key => $value) {
            $data .= "product[" . $key . "]=" . $value . "&";
            $data .= "product_amount[" . $key . "]=" . product_amount[$key] . "&";
            if (isset($product_parent[$key])) {
                $data .= "product_parent[" . $key . "]=" . $product_parent[$key] . "&";
            }
        }

        /*    Отправка с помощью CURL    */

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://shop.mypar.ru/api/?order_edit");
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
        curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER,true);
        curl_setopt($ch, CURLOPT_AUTOREFERER,true);
        curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
        curl_setopt($ch, CURLOPT_COOKIESESSION,true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 3);
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
        $result = curl_exec($ch);

        /*    Вывод на экран информации о результате    */

        if ($result == NULL) {
            echo "Error:\n";
            echo curl_errno($ch) . " - " . curl_error($ch) . "\n";
        }
        curl_close($ch);
        echo $result;

Возможные критические ошибки:

Возможные уведомления:

Ответ API (успешный):

Информация о заказе

Информацию о заказе можно получить с помощью:

Адрес для запроса: - https://shop.mypar.ru/api/?order_info

Обязательные параметры для запроса:

Возможные критические ошибки:

Ответ API (успешный):

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

Ответ API:

         {
             "result":"success",
             "order_id":"102",
             "phone":"84951111111",
             "client_name":"Иван Иванович",
             "total_price":"1010",
             "status":"10",
             "status_text":"Выполнен",
             "statuses_time":
                 {
                     "1":"2017-07-14 20:03:44",
                     "10":"2017-07-14 21:30:08"
                 },
             "waiters":["Алексей"]
         }
     

Справочники

Список позиций с ценами (прайс-лист)

Позволяет выгрузить список позиций, у которых установлен параметр артикул.

Адрес для запроса: - https://shop.mypar.ru/api/?info_products

Обязательные параметры для запроса:

Возможные критические ошибки:

Ответ API (успешный):

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

Ответ API:

         {
             "result":"success",
             "product_id": {
                 "0":"15",
                 "1":"No article"
             },
             "product_category": {
                 "0":"Салаты",
                 "1":"Салаты"
             },
             "product_category_id": {
                 "0":"1",
                 "1":"2"
             },
             "product_description": {
                 "0":"Салат айсберг, креветки, соус цезарь",
                 "1":"Салат айсберг, курица, соус цезарь"
             },
             "product_filial": {
                 "0":"0",
                 "1":"1,2"
             },
             "product_text": {
                 "0":"Цезарь с креветками",
                 "1":"Цезарь с курицей"
             },
             "product_price": {
                 "0":"360",
                 "1":"290"
             },
             "product_image": {
                 "0":"https://stockimages.com/...",
                 "1":""
             },
             "product_stock": {
                 "0": {},
                 "1": {
                    "1":"0",
                    "2":"3"
                 }
             },
             "product_modificator": {
                 "0":"0",
                 "1":"0"
             }
         }
     

Список категорий

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

Адрес для запроса: - https://shop.mypar.ru/api/?info_category

Обязательные параметры для запроса:

Возможные ошибки:

Ответ API (успешный):

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

Ответ API:

         {
             "result":"success",
             "id": {
                 "0":"1",
                 "1":"2",
                 "2":"3"
             },
             "name": {
                 "0":"Салаты",
                 "1":"Супы",
                 "2":"Роллы"
             },
             "filial": {
                 "0":"1",
                 "1":"0",
                 "1":"1,2"
             },
             "parent": {
                 "0":"0",
                 "1":"0",
                 "2":"0"
             },
             "hidden": {
                 "0":"0",
                 "1":"0",
                 "2":"0"
             },
             "modificators": {
                 "0":"0",
                 "1":"0",
                 "2":"0"
             },
             "sort": {
                 "0":"2",
                 "1":"1",
                 "2":"3"
             }
         }
     

Список филиалов

Позволяет выгрузить список с информацией о филиалах

Адрес для запроса: - https://shop.mypar.ru/api/?info_filials

Обязательные параметры для запроса:

Возможные ошибки:

Ответ API (успешный):

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

Ответ API:

         {
             "result":"success",
             "id": {
                 "0":"1",
                 "1":"2"
             },
             "name": {
                 "0":"Москва",
                 "1":"Питер"
             },
             "city": {
                 "0":"Москва",
                 "1":"Санкт-Петербург"
             },
             "address": {
                 "0":"ул. ....., дом. ...",
                 "1":"ул. ....., дом. ..."
             },
             "coordinates": {
                 "0":"55.755814,37.617635",
                 "1":"59.9386, 30.3141"
             },
             "utc": {
                 "0":"3",
                 "1":"3"
             }
         }
     

Информация о клиенте

Позволяет выгрузить информацию о клиенте по его номеру телефона

Адрес для запроса: - https://shop.mypar.ru/api/?info_client

Обязательные параметры для запроса:

Возможные критические ошибки:

Ответ API (успешный):

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

Ответ API:

         {
             "result":"success",
             "name":"Иван Иванович",
             "register_date":"01.01.2017",
             "card":"0",
             "phone":"84951111111",
             "mail":"",
             "sale":"0",
             "birthday":"01.01.1970",
             "street":"Знаменские садки",
             "house":"7",
             "structure":"",
             "build":"",
             "entrance":"",
             "floor":"",
             "flat":"",
             "intercom":"",
             "note":"",
             "channel":"0",
             "channel_text":"Не указан",
             "black_list":"0",
             "score":"176",
             "bill_cnt":"5",
             "bill_total":"3587"
         }
     

Информация о сертификате

Позволяет выгрузить информацию о сертификате по его номеру

Адрес для запроса: - https://shop.mypar.ru/api/?info_certificate

Обязательные параметры для запроса:

Возможные критические ошибки:

Ответ API (успешный):

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

Ответ API:

         {
             "result":"success",
             "type":"1",
             "type_text":"Позиция",
             "create_date":"30.06.2017",
             "finish_date":0,
             "reusable":"1",
             "product_id":0,
             "product_text":"Sprite 0,5л",
             "note":"",
             "status":1
         }
     

Поделиться ссылкой на эту страницу: