NAV Navbar
cURL

МойСклад LoyaltyAPI

LoyaltyAPI МоегоСклада дает возможность разработчикам обмениваться с внешними программами лояльности следующей информацией:

Подключение внешней программы лояльности в сервисе МойСклад происходит через решение, которое необходимо разработать и опубликовать в нашем каталоге решений. Для этого вам нужно:

  1. Получить доступ к Личному кабинету разработчика.
  2. Создать черновик серверного решения с указанием блока <loyaltyApi/> в дескрипторе.
  3. Используя эту документацию создать бизнес-логику работы с системой лояльности на сервере.
  4. Протестировать и отправить решение на публикацию.

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

Предварительные условия:

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

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

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

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

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

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

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

Response
412 (application/json)

{
  "errors": [
    {
      "error": "Не указан обязательный параметр",
      "parameter": "phone",
      "code": 999,
      "error_message": "Требуется указать номер телефона"
    }
  ]
}

Сущности

Покупатель

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

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

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

POST /counterparty

Request

Headers

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

Body

{
  "retailStore": {
    "meta": {
      "href": "https://api.moysklad.ru/api/remap/1.2/entity/retailstore/2b5eb22f-139e-11e6-9464-e4de00000073",
      "id": "2b5eb22f-139e-11e6-9464-e4de00000073"
    },
    "name": "Магазин №1"
  },
  "meta": {
    "href": "https://api.moysklad.ru/api/remap/1.2/entity/counterparty/276a6f50-7ffd-11e6-8a84-bae50000005",
    "id": "276a6f50-7ffd-11e6-8a84-bae50000005"
  },
  "name": "Иванов Иван Иванович",
  "discountCardNumber": "MTIzNDU2Nzg5MA",
  "phone": "+7 555 123 4568",
  "email": "email@example.com",
  "syncId": "6ebefb74-f6e3-4ef1-b155-5232a2ae396a",
  "legalFirstName": "Иванов",
  "legalMiddleName": "Иван",
  "legalLastName": "Иванович",
  "birthDate": "2023-07-14 00:00:00",
  "sex": "MALE",
  "statusCheck": "CHECKED"
}

Response
201

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

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

Параметры

Параметр Описание
search string Example: 9039993344 Строка с поисковым запросом
retailStoreId string Example: 2b5eb22f-139e-11e6-9464-e4de00000073 Идентификатор точки продаж Необходимое

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

GET /counterparty?search=9039993344&retailStoreId=2b5eb22f-139e-11e6-9464-e4de00000073

Request

Headers

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

Response
200 (application/json)

{
  "rows": [
    {
      "id": "2b5eb22f-139e-11e6-9464-e4de00000073",
      "msId": "276a6f50-7ffd-11e6-8a84-bae50000005",
      "name": "Иванов Иван Иванович",
      "discountCardNumber": "MTIzNDU2Nzg5MA",
      "phone": "+7 555 123 4567",
      "email": "email@example.com",
      "legalFirstName":"Иванов",
      "legalMiddleName":"Иванович",
      "legalLastName":"Иванов",
      "birthDate": "2023-07-14 00:00:00",
      "sex": "MALE"
    }
  ]
}

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

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

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

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

POST /counterparty/detail

Request

Headers

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

Body

{
  "retailStore": {
    "meta": {
      "href": "https://api.moysklad.ru/api/remap/1.2/entity/retailstore/2b5eb22f-139e-11e6-9464-e4de00000073",
      "id": "2b5eb22f-139e-11e6-9464-e4de00000073"
    },
    "name": "Магазин №1"
  },
  "meta": {
    "href": "https://api.moysklad.ru/api/remap/1.2/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",
  "legalFirstName":"Иванов",
  "legalMiddleName":"Иванович",
  "legalLastName":"Иванов",
  "birthDate": "2023-07-14 00:00:00",
  "sex": "MALE"
}

Response
200 (application/json)

Body

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

Подготовка к запросу кода подтверждения регистрации покупателя

Если для регистрации покупателя с атрибутом "statusCheck": "UNCHECKED" требуется провести подтверждение через код, то необходимо в ответе на запрос вернуть ошибку:

Response
412 (application/json)

{
  "errors": [
    {
      "error": "Необходимо подтверждение создания покупателя.",
      "code": 28001,
      "error_message": "Покупатель должен подтвердить свои данные через код."
    }
  ]
}

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

Метод предназначен для запроса кода у внешней бонусной программы с целью подтверждения регистрации покупателя.

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

POST /counterparty/verify

Request

Headers

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

Body

{
  "retailStore": {
    "meta": {
      "href": "https://api.moysklad.ru/api/remap/1.2/entity/retailstore/2b5eb22f-139e-11e6-9464-e4de00000073",
      "id": "2b5eb22f-139e-11e6-9464-e4de00000073"
    },
    "name": "Магазин №1"
  },
  "meta": {
    "href": "https://api.moysklad.ru/api/posap/1.0/entity/counterparty/syncid/276a6f50-7ffd-11e6-8a84-bae50000005"
  },
  "name":"Ромашкова Варвара Никитична",
  "discountCardNumber":"09716398",
  "phone":"+79011231122",
  "email":"romashkova@fmail.com",
  "legalFirstName":"Варвара",
  "legalMiddleName":"Никитична",
  "legalLastName":"Ромашкова",
  "birthDate":"1992-08-01 00:00:00",
  "sex":"FEMALE"
}

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

Response
200 (application/json)

Headers

Content-Type:application/json

Body

{
  "verificationCode":"123456",
  "timeForRepeat": 60,
  "messageForCashier": "Код был отправлен на номер покупателя: +79011231122"
}

Продажа

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

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

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

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

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

POST /retaildemand/recalc

Request

Headers

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

Body

{
  "retailStore": {
    "meta": {
      "href": "https://api.moysklad.ru/api/remap/1.2/entity/retailstore/2b5eb22f-139e-11e6-9464-e4de00000073",
      "id": "2b5eb22f-139e-11e6-9464-e4de00000073"
    },
    "name": "Магазин №1"
  },
  "agent": {
    "meta": {
      "href": "https://api.moysklad.ru/api/remap/1.2/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",
    "legalFirstName": "Иванов",
    "legalMiddleName": "Иван",
    "legalLastName": "Иванович",
    "sex": "MALE",
    "birthDate": "2023-07-14 00:00:00"
  },
  "positions": [
    {
      "assortment": {
        "meta": {
          "href": "https://api.moysklad.ru/api/remap/1.2/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/posap/1.0/entity/sn/2b5eb22f-139e-11e6-9464-e4de00000073",
            "id": "2b5eb22f-139e-11e6-9464-e4de00000073"
          },
          "name": "7895545"
        }
      ],
      "pack": {
        "id": "98f87a95-c0b6-11ee-0a80-06e1000360e2",
        "name": "Бутылка 1,5 л",
        "quantity": 1.5,
        "barcode": "2000000051420"
      }
    }
  ],
  "bonusProgram": {
    "transactionType": "EARNING"
  }
}

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

Response
200 (application/json)

Headers

Content-Type:application/json

Body

{
  "agent": {
    "meta": {
      "href": "https://api.moysklad.ru/api/remap/1.2/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",
    "legalFirstName": "Иванов",
    "legalMiddleName": "Иван",
    "legalLastName": "Иванович",
    "sex": "MALE",
    "birthDate": "2023-07-14 00:00:00"
  },
  "positions": [
    {
      "assortment": {
        "meta": {
          "href": "https://api.moysklad.ru/api/remap/1.2/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/posap/1.0/entity/sn/2b5eb22f-139e-11e6-9464-e4de00000073",
            "id": "2b5eb22f-139e-11e6-9464-e4de00000073"
          },
          "name": "7895545"
        }
      ],
      "pack": {
        "id": "98f87a95-c0b6-11ee-0a80-06e1000360e2",
        "name": "Бутылка 1,5 л",
        "quantity": 1.5,
        "barcode": "2000000051420"
      }
    }
  ],
  "bonusProgram": {
    "transactionType": "EARNING",
    "agentBonusBalance": 500,
    "bonusValueToSpend": 0,
    "bonusValueToEarn": 150,
    "agentBonusBalanceAfter": 650,
    "paidByBonusPoints": 0,
    "receiptExtraInfo": "Спасибо за участие в нашей программе!"
  },
  "needVerification": false
}

Запрос кода подтверждения списания баллов

Метод предназначен для запроса кода у внешней бонусной программы с целью подтверждения списания бонусов.

Атрибуты запроса

POST /retaildemand/verify

Request

Headers

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

Body

{
  "retailStore": {
    "meta": {
      "href": "https://api.moysklad.ru/api/remap/1.2/entity/retailstore/2b5eb22f-139e-11e6-9464-e4de00000073",
      "id": "2b5eb22f-139e-11e6-9464-e4de00000073"
    },
    "name": "Магазин №1"
  },
  "counterpartyId": "75d9ba29-2c4a-4c1c-a3a8-8db00366ac04",
  "phone": "+79011231122"
}

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

Response
200 (application/json)

Headers

Content-Type:application/json

Body

{
  "verificationCode":"123456",
  "timeForRepeat": 60,
  "messageForCashier": "Код был отправлен на номер покупателя: +79011231122"
}

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

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

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

POST /retaildemand

Request

Headers

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

Body

{
  "retailStore": {
    "meta": {
      "href": "https://api.moysklad.ru/api/remap/1.2/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://api.moysklad.ru/api/remap/1.2/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",
    "legalFirstName": "Иванов",
    "legalMiddleName": "Иван",
    "legalLastName": "Иванович",
    "sex": "MALE",
    "birthDate": "2023-07-14 00:00:00"
  },
  "positions": [
    {
      "assortment": {
        "syncId": "f085d67e-6eae-11e6-8a84-bc520403352a",
        "meta": {
          "href": "https://api.moysklad.ru/api/remap/1.2/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 /retailsalesreturn

Request

Headers

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

Body

{
  "retailStore": {
    "meta": {
      "href": "https://api.moysklad.ru/api/remap/1.2/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": {
        "syncId": "f085d67e-6eae-11e6-8a84-bc520403352a",
        "meta": {
          "href": "https://api.moysklad.ru/api/remap/1.2/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": 283100.0
}

Response
201

cURL