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

Программа учета кафе, доставки, интернет-магазина

Телефон офиса:+7(495)369-50-11

API - инструкция

Главная>Помощь>API - инструкция

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

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

Взаимодействие с API происходит с помощью отправки HTTP запроса POST на адрес API

Авторизация

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

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

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

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

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

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

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

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

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

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

  • token - токен авторизации

В ответе обязательно содержится параметр 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
                                            }
                                    }
                                

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

Критичные:

  • token_invalid - Не соответствие токена
  • post_error - Пустой или некорректный запрос
  • plant_invalid - На тарифе "бесплатный" API не работает
  • api_off - API отключена, включить в настройках
  • limit_requests - Превышен лимит количества запросов в минуту

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

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

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

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

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

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

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

  • token - токен авторизации
  • product - массив с артикулами позициий из программы учета
  • product_amount - массив с указанием количества позиций в заказе

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

  • product_parent - массив модификаторов, в котором значение элемента массива равно ключу родителя в массиве product.

    Пример (PHP)

    $product[0]="10001"; //Добавили позицию с ключом 10001 - товар "Пицца Гавайская"

    $product[1]="10002"; //Добавили позицию с ключом 10002 - "Курица"

    $product[2]="10003"; //Добавили позицию с ключом 10003 - "Помидоры"

    $product_amount[0]="1";

    $product_amount[1]="1";

    $product_amount[2]="1";

    $product_parent[1]="0"; //"0" - ключ родителя позиции в массиве $product

    $product_parent[2]="0"; //"0" - ключ родителя позиции в массиве $product

    Таким образом добавили пиццу с дополнительными ингредиентами курицей и помидорами.

  • product_price - массив с указанием цены позиций

  • sale - скидка на чек в процентах (цифры)

  • sale_amount - скидка на чек суммой (число, разделяется ".")

  • margin - наценка на чек в процентах (цифры)

  • score - баллы со счета клиента для оплаты

    (коэффициент баллов к валюте оплаты - 1к1)

  • branch - филиал, код (указан в разделе Управление - Филиалы)

    (По умолчанию - 1)

  • point - точка продаж, код (указан в разделе Управление - Точки продаж)

    (По умолчанию - 1)

  • channel - канал продаж, код (указан в разделе Управление - Каналы продаж)

  • marks - отметки заказа (код API, через запятую)

  • note - примечание к заказу (не более 255 символов)

  • payment - способ оплаты (код API, указан в справочнике)

  • delivery - способ получения

    (код 1 - Зал, 2 - Доставка, 3 - Самовывоз)

  • status - статус заказа

    (код API указан в справочнике)

  • bond - купюра - сумма, с которой необходимо рассчитать сдачу

  • datetime - дата и время для предзаказа, только будущее время

    (Указывается в формате "ГГГГ-ММ-ДД ЧЧ:ММ:СС")

  • certificate - номер сертификата для использования в заказе

  • person_number - количество персон

  • table - номер стола

  • phone - номер телефона клиента

  • card - номер карты (дисконтной, клубной) клиента

  • mail - e-mail телефона клиента

  • name - имя клиента

    (Если не указано, но указан номер телефона, используется имя из справочника клиентов)

  • street_id - идентификатор улицы (код API, указан в справочнике улиц)

  • city - город

  • street - улица

  • house - номер дома

  • structure - строение

  • build - корпус

  • entrance - номер подъезда

  • floor - этаж

  • flat - квартира или офис

  • intercom - код домофона

  • new_address - указать 1, для сохранения адреса как дополнительного в карточку клиента

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

Если параметр 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 = "Значение_токена";


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

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

        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/?new_order");
        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;

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

  • cash_close - смена филиала закрыта

  • product_article_invalid - не найдены позиции с отправленными артикулами

  • product_list_empty - не верно заполнены артикулы или количество позиций

  • orders_limit - достигнут предел количества заказов по тарифу

  • orders_limit - достигнут предел количества заказов по тарифу

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

  • product_invalid - неверный артикул (массив - [отправленный ключ массива] = артикул)

  • product_amount_invalid - количество позиции = 0 (массив - [отправленный ключ массива] = артикул)

  • certificate_number_invalid - номер сертификата неверный (значение отправленного номера)

  • certificate_used - сертификат использован

  • certificate_overdue - сертификат просрочен (дата, до которой действовал)

  • clients_score_surplus - баллов указано больше чем сумма заказа (установлено на значение суммы заказа)

  • clients_score_deficit - нехватает баллов для списания, указывает сколько было на счете (установлен остаток со счета)

  • bond_invalid - купюра меньше чем счет и не равна 500, 1000, 5000 (рассчет сдачи не выполняется)

  • datetime_invalid - ошибка предзаказа (возможные значения: period_invalid - неверный период, format_invalid - неверный формат

  • payment_invalid - Не существующий способ оплаты (указан отправленный способ, отметка об оплате не устанавливается)

  • channel_invalid - Не существующий канал продаж (указан отправленный)

  • tag_invalid - Не существующая отметка (указаны неверные значения через запятую)

  • status_invalid - Не существующий статус (установлен статус "Новый")

  • city_invalid - Неверно указан город при включенной функции автоматического определения филиала по адресу

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

  • result - success

  • order_id - Системный номер заказа

  • order_number - Номер чека

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

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

  • системного номера заказа, полученного в ответе при сохранении заказа (order_id)
  • номера телефона клиента (используется последний добавленный заказ, поиск выполняется строгий)

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

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

  • token - токен авторизации
  • order_id - системный номер заказа
    или phone - номер телефона клиента

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

  • not_found - заказ не найден

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

  • result - success

  • order_id - системный номер заказа

  • order_number - номер чека

  • phone - номер телефона клиента

  • client_name - имя клиента

  • total_price - сумма заказа итого

  • status - код API статуса заказа

  • status_text - название статуса

  • statuses_time - массив, где ключ: API код статуса, значение: время установки статуса

  • waiters - массив, с именами сотрудников, "привязанных" к заказу

Пример ответа 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

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

  • token - токен авторизации

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

  • branch_id - Api код для филиала

    Если не указан - остатки суммируются по всем филиалам

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

  • result - success

  • product_id - массив с артикулами позиций

  • product_text - массив с наименованиями позиций

  • product_price - массив с ценами позиций

  • product_stock - массив с остатками позиций

  • product_category - массив с названиями категорий

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

Ответ API:

                                    {
                                        "result":"success",
                                        "product_id": {
                                            "0":"15",
                                            "1":"14"
                                        },
                                        "product_text": {
                                            "0":"Цезарь с креветками",
                                            "1":"Цезарь с курицей"
                                        },
                                        "product_price": {
                                            "0":"360",
                                            "1":"290"
                                        }
                                        "product_stock": {
                                            "0":"5",
                                            "1":"2"
                                        }
                                        "product_category": {
                                            "0":"Салаты",
                                            "1":"Салаты"
                                        }
                                    }
                                

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

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

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

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

  • token - токен авторизации
  • phone - номер телефона искомого клиента
    или card - номер дисконтной карты

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

  • not_found - не верный номер телефона или дисконтной карты

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

  • result - success

  • register_date - имя клиента

  • card - номер дисконтной карты

  • phone - номер телефона

  • mail - электронная почта (E-mail)

  • sale - личная скидка клиента (%)

  • birthday - дата рождения

  • street - улица (город, улица)

  • house - номер дома

  • structure - строение

  • build - корпус

  • entrance - подъезд

  • floor - этаж

  • flat - квартира

  • intercom - домофон

  • note - комментарий клиента

  • channel - канал продаж - код API

  • channel_text - канал продаж - текст

  • black_list - черный список (если присутствует 1, иначе 0)

  • score - баланс лицевого счета (бонусные баллы)

  • bill_cnt - количество заказов клиента

  • bill_total - общая сумма заказов клиента

Пример ответа 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

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

  • token - токен авторизации
  • number - номер искомого сертификата

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

  • not_found - не верный номер сертификата

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

  • result - success

  • type - тип сертификата цифрой

  • type_text - тип сертификата в текстовом виде

  • create_date - дата создания (дд.мм.гггг)

  • finish_date - дата окончания действия (0 - бессрочный)

  • reusable - можно ли использовать повторно (1 - да, 0 - нет)

  • product_id - артикул позиции (если не указан - 0)

  • product_text - наименование позиции

  • sale_percent - скидка в процентах (значение)

  • sale_amount - скидка суммой на заказ (значение)

  • note - комментарий

  • status - действительный или нет (1 или 0)

Пример ответа 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
                                    }
                                

Другие инструкции