NAV Navbar
cURL

МойСклад LoyaltyAPI

API для интеграции МоегоСклада с системами лояльности.

Сценарий работы

Предваритаельные условия: - Пользователь на стороне МоегоСклада указывает базовый адрес системы лояльности (в приведенных примерах обозначен как example.com/baseurl) и ключ доступа . - Пользователь на стороне системы лояльности указывает логин и пароль для доступа к МоемуСкладу. - Система лояльности через JSON API запрашивают всю необходимую информацию для настройки скидок (информация о покупателях, товарах, магазинах и т.д.). - В настройках приложения лояльности на стороне МоегоСклада может быть выбран способ поиска покупателей: внутренний (в МоемСкладе) или внешний (в системе лояльности)

После всех настроек МойСклад может производить к системе лояльности следующие запросы: - Создание покупателя - Поиск покупателя - Запрос баланса баллов покупателя - Расчет скидок для продажи - Создание продажи - Создание возврата

Запросы осуществляются на определенный эндпоинт относительно базового адреса. Каждый из запросов содержит в своем составе ключ доступа.

Обработка ошибок

Если вознникла ошибка при обработке запроса, то она должна приходить с HTTP кодом, отличным от 200 и 201

Структура ошибок

Ошибки представляют собой массив errors, содержащий объекты error, каждый из которых описывает отдельную ошибку.

Структура объекта error

Сущности

Покупатель

Создание покупателя

Запрос на создание нового покупателя.

Атрибуты сущности

POST http://example.com/baseurl/api/moysklad/loyalty/1.0/counterparty

Request

Headers

Content-Type:application/json
Lognex-Discount-API-Auth-Token:Токен авторизации

Body

{
  "retailStore": {
    "meta": {
      "href": "https://online.moysklad.ru/api/remap/1.1/entity/retailstore/2b5eb22f-139e-11e6-9464-e4de00000073",
      "id": "2b5eb22f-139e-11e6-9464-e4de00000073"
    },
    "name": "Магазин №1"
  },
  "meta": {
    "href": "https://online.moysklad.ru/api/remap/1.1/entity/counterparty/276a6f50-7ffd-11e6-8a84-bae50000005",
    "id": "276a6f50-7ffd-11e6-8a84-bae50000005"
  },
  "name": "Иванов Иван Иванович",
  "discountCardNumber": "MTIzNDU2Nzg5MA",
  "phone": "+7 555 123 4567",
  "email": "email@example.com"
}

Response
201

Поиск покупателя

Запрос на поиск существующего покупателя.

Параметры

Параметр Описание
search string Example: 9039993344 Строка с поисковым запросом

Атрибуты сущности

GET http://example.com/baseurl/api/moysklad/loyalty/1.0/counterparty?search=9039993344

Request

Headers

Content-Type:application/json
Lognex-Discount-API-Auth-Token:Токен авторизации

Response
200 (application/json)

{
  "rows": [
    {
      "id": "2b5eb22f-139e-11e6-9464-e4de00000073",
      "name": "Иванов Иван Иванович",
      "discountCardNumber": "MTIzNDU2Nzg5MA",
      "phone": "+7 555 123 4567",
      "email": "email@example.com"
    }
  ]
}

Получение баланса баллов покупателя

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

Атрибуты сущности

Атрибуты ответа

GET http://example.com/baseurl/api/moysklad/loyalty/1.0/counterparty/detail

Request

Headers

Content-Type:application/json
Lognex-Discount-API-Auth-Token:Токен авторизации

Body

{
  "retailStore": {
    "meta": {
      "href": "https://online.moysklad.ru/api/remap/1.1/entity/retailstore/2b5eb22f-139e-11e6-9464-e4de00000073",
      "id": "2b5eb22f-139e-11e6-9464-e4de00000073"
    },
    "name": "Магазин №1"
  },
  "meta": {
    "href": "https://online.moysklad.ru/api/remap/1.1/entity/counterparty/276a6f50-7ffd-11e6-8a84-bae50000005",
    "id": "276a6f50-7ffd-11e6-8a84-bae50000005"
  },
  "name": "Иванов Иван Иванович",
  "discountCardNumber": "MTIzNDU2Nzg5MA",
  "phone": "+7 555 123 4567",
  "email": "email@example.com"
}

Response
200 (application/json)

Body

{
  "bonusProgram": {
    "agentBonusBalance": 500
  }
}

Продажа

Расчет скидок для продажи

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

Если проишло разбиение позиции, то необходимо учитывать значение в поле sn (серийные номера). Правило следующее - количество серийных номеров изначальной позиции совпадает с количеством серийных номеров в позициях, получившихся в результате разбиения. Так же, количество серийных номеров должно быть равно количеству товара (поле quantity).

После расчета скидок, приложение уже никак не меняет состав чека и не применяет другие скидки.

Атрибуты сущности

POST http://example.com/baseurl/api/moysklad/loyalty/1.0/retaildemand/recalc

Request

Headers

Content-Type:application/json
Lognex-Discount-API-Auth-Token:Токен авторизации

Body

{
  "retailStore": {
    "meta": {
      "href": "https://online.moysklad.ru/api/remap/1.1/entity/retailstore/2b5eb22f-139e-11e6-9464-e4de00000073",
      "id": "2b5eb22f-139e-11e6-9464-e4de00000073"
    },
    "name": "Магазин №1"
  },
  "agent": {
    "meta": {
      "href": "https://online.moysklad.ru/api/remap/1.1/entity/counterparty/276a6f50-7ffd-11e6-8a84-bae50000005",
      "id": "276a6f50-7ffd-11e6-8a84-bae50000005"
    },
    "name": "Иванов Иван Иванович",
    "discountCardNumber": "MTIzNDU2Nzg5MA",
    "phone": "+7 555 123 4567",
    "email": "email@example.com"
  },
  "positions": [
    {
      "assortment": {
        "meta": {
          "href": "https://online.moysklad.ru/api/remap/1.1/entity/product/9c56720c-e8a7-4fdc-aea4-7104f28207be",
          "id": "9c56720c-e8a7-4fdc-aea4-7104f28207be"
        }
      },
      "quantity": 123.456,
      "price": 123.45,
      "sn": [
        {
          "meta": {
            "href": "https://online.moysklad.ru/api/remap/1.1/entity/thing/2b5eb22f-139e-11e6-9464-e4de00000073",
            "id": "2b5eb22f-139e-11e6-9464-e4de00000073"
          },
          "name": "7895545"
        }
      ]
    }
  ],
  "bonusProgram": {
    "transactionType": "EARNING"
  }
}

Атрибуты ответа

Response
200 (application/json)

Headers

Content-Type:application/json

Body

{
  "agent": {
    "meta": {
      "href": "https://online.moysklad.ru/api/remap/1.1/entity/counterparty/276a6f50-7ffd-11e6-8a84-bae50000005",
      "id": "276a6f50-7ffd-11e6-8a84-bae50000005"
    },
    "name": "Иванов Иван Иванович",
    "discountCardNumber": "MTIzNDU2Nzg5MA",
    "phone": "+7 555 123 4567",
    "email": "email@example.com"
  },
  "positions": [
    {
      "assortment": {
        "meta": {
          "href": "https://online.moysklad.ru/api/remap/1.1/entity/product/9c56720c-e8a7-4fdc-aea4-7104f28207be",
          "id": "9c56720c-e8a7-4fdc-aea4-7104f28207be"
        }
      },
      "quantity": 123.456,
      "price": 123.45,
      "discountPercent": 49.99,
      "discountedPrice": 62.95,
      "sn": [
        {
          "meta": {
            "href": "https://online.moysklad.ru/api/remap/1.1/entity/thing/2b5eb22f-139e-11e6-9464-e4de00000073",
            "id": "2b5eb22f-139e-11e6-9464-e4de00000073"
          },
          "name": "7895545"
        }
      ]
    }
  ],
  "bonusProgram": {
    "transactionType": "EARNING",
    "agentBonusBalance": 500,
    "bonusValueToSpend": 0,
    "bonusValueToEarn": 150,
    "agentBonusBalanceAfter": 650,
    "paidByBonusPoints": 0,
    "receiptExtraInfo": "Спасибо за участие в нашей программе!"
  }
}

Создание продажи

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

Атрибуты сущности

POST http://example.com/baseurl/api/moysklad/loyalty/1.0/retaildemand

Request

Headers

Content-Type:application/json
Lognex-Discount-API-Auth-Token:Токен авторизации

Body

{
  "retailStore": {
    "meta": {
      "href": "https://online.moysklad.ru/api/remap/1.1/entity/retailstore/2b5eb22f-139e-11e6-9464-e4de00000073",
      "id": "2b5eb22f-139e-11e6-9464-e4de00000073"
    },
    "name": "Магазин №1"
  },
  "name": "00001",
  "moment": "2016-04-18 15:06:00",
  "meta": {
    "href": "",
    "id": ""
  },
  "agent": {
    "meta": {
      "href": "https://online.moysklad.ru/api/remap/1.1/entity/counterparty/276a6f50-7ffd-11e6-8a84-bae50000005",
      "id": "276a6f50-7ffd-11e6-8a84-bae50000005"
    },
    "name": "Иванов Иван Иванович",
    "discountCardNumber": "MTIzNDU2Nzg5MA",
    "phone": "+7 555 123 4567",
    "email": "email@example.com"
  },
  "positions": [
    {
      "assortment": {
        "meta": {
          "href": "https://online.moysklad.ru/api/remap/1.1/entity/product/9c56720c-e8a7-4fdc-aea4-7104f28207be",
          "id": "9c56720c-e8a7-4fdc-aea4-7104f28207be"
        }
      },
      "quantity": 123.456,
      "price": 123.45,
      "discountPercent": 49.99,
      "discountedPrice": 62.95
    }
  ],
  "bonusProgram": {
    "bonusValueToSpend": 0,
    "bonusValueToEarn": 150
  },
  "cashSum": 62.95,
  "noCashSum": 283.1
} 

Response
201

Возврат

Создание возврата

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

Атрибуты сущности

POST http://example.com/baseurl/api/moysklad/loyalty/1.0/retailsalesreturn

Request

Headers

Content-Type:application/json
Lognex-Discount-API-Auth-Token:Токен авторизации

Body

{
  "retailStore": {
    "meta": {
      "href": "https://online.moysklad.ru/api/remap/1.1/entity/retailstore/2b5eb22f-139e-11e6-9464-e4de00000073",
      "id": "2b5eb22f-139e-11e6-9464-e4de00000073"
    },
    "name": "Магазин №1"
  },
  "name": "00001",
  "moment": "2016-04-27 15:43:00",
  "meta": {
    "href": "",
    "id": ""
  },
  "demand": {
    "meta": {
      "href": "",
      "id": ""
    }
  },
  "agent": {},
  "positions": [
    {
      "assortment": {
        "meta": {
          "href": "https://online.moysklad.ru/api/remap/1.1/entity/product/9c56720c-e8a7-4fdc-aea4-7104f28207be",
          "id": "9c56720c-e8a7-4fdc-aea4-7104f28207be"
        }
      },
      "quantity": 123.456,
      "price": 123.45,
      "discountPercent": 49.99,
      "discountedPrice": 62.95
    }
  ],
  "cashSum": 62.95,
  "noCashSum": 283.1
}

Response
201