1. Описание

1.1. Базовый URL

В базовый URL для выполнения запросов https://my.modulkassa.ru/api

1.2. Аутентификация API

Для аутентификации API клиента используется Basic-аутентификация.

Для получения логина и пароля для доступа к API нужно зайти в меню Настройки → Сервисы и включить элемент Заказы (выдача/доставка)

Настройки сервисов

В открывшемся окне подключения сервиса будут указаны логин и пароль для работы через API. Скопируйте и сохраните их.

Подключение заказов

2. Описание методов

2.1. Создание нового заказа

POST /v2/retail-point/{retailPointId}/order

2.1.1. Параметры

Тип Имя Описание Схема

Body

Тело запроса
обязательно

Данные заказа

Order

Path

retailPointId
обязательно

ID точки продаж

string

2.1.2. Ответы

HTTP код Описание Схема

200

Заказ успешно создан

Order

400

Некорректный запрос

Без содержимого

401

Запрос не авторизован

Без содержимого

403

У пользователя недостаточно прав для работы с заказами

Без содержимого

404

Точка продаж не найдена

Без содержимого

409

Заказ с таким же номером уже существует

Без содержимого

2.1.3. Пример запроса

POST https://my.modulkassa.ru/api/v2/retail-point/12345678-90ab-cdef-1234-000000000000/order
Тело запроса 
{
  "remoteId" : "4f4c789c-3863-41d3-aea9-c35b5a9e7f18",
  "documentNumber" : "ORDER-12345",
  "documentType" : "SALE",
  "documentDateTime" : "2019-09-18T14:41:04+07:00",
  "inventPositions" : [ {
    "inventCode" : "GOOD-123",
    "barcode" : "123456789",
    "name" : "Товар 1",
    "description" : "Описание товара",
    "inventoryType" : "INVENTORY",
    "measure" : "pcs",
    "price" : 100.00,
    "quantity" : 1.0,
    "taxMode" : "COMMON",
    "vatTag" : 1102,
    "customsDeclarationNumber" : "123456",
    "originCountryCode" : "643"
  }, {
    "inventCode" : "GOOD-124",
    "barcode" : "987654321",
    "name" : "Товар 2",
    "description" : "Товар 2",
    "inventoryType" : "SERVICE",
    "measure" : "pcs",
    "price" : 100.00,
    "quantity" : 1.0,
    "agentInformation" : {
      "contractorInn" : "2204000595",
      "contractorName" : "Модульбанк",
      "contractorPhone" : "+7123456789",
      "tags" : [ "AGENT" ]
    }
  } ],
  "customerContact" : "+71234567890",
  "responseURL" : "https://your-callback-service.com/complete-order?id=1",
  "clientInformation" : {
    "name" : "Иванов Иван Иванович",
    "documentNumber" : "1234567"
  }
}

2.2. Изменение существующего заказа

PUT /v2/retail-point/{retailPointId}/order

2.2.1. Параметры

Тип Имя Описание Схема

Body

Тело запроса
обязательно

Данные заказа

Order

Path

retailPointId
обязательно

ID точки продаж

string

2.2.2. Ответы

HTTP код Описание Схема

200

Заказ успешно изменён

Order

400

Некорректный запрос

Без содержимого

401

Запрос не авторизован

Без содержимого

403

У пользователя недостаточно прав для работы с заказами

Без содержимого

404

Точка продаж или заказ не найдены

Без содержимого

2.2.3. Пример запроса

PUT https://my.modulkassa.ru/api/v2/retail-point/12345678-90ab-cdef-1234-000000000000/order
Тело запроса 
{
  "id" : "4f4c789c-3863-41d3-aea9-c35b5a9e7f18",
  "remoteId" : "4f4c789c-3863-41d3-aea9-c35b5a9e7f18",
  "documentNumber" : "ORDER-12345",
  "documentType" : "SALE",
  "documentDateTime" : "2019-09-18T14:41:04+07:00",
  "inventPositions" : [ {
    "inventCode" : "GOOD-123",
    "barcode" : "123456789",
    "name" : "Товар 1",
    "description" : "Описание товара",
    "inventoryType" : "INVENTORY",
    "measure" : "pcs",
    "price" : 100.00,
    "quantity" : 1.0,
    "taxMode" : "COMMON",
    "vatTag" : 1102,
    "customsDeclarationNumber" : "123456",
    "originCountryCode" : "643"
  }, {
    "inventCode" : "GOOD-124",
    "barcode" : "987654321",
    "name" : "Товар 2",
    "description" : "Товар 2",
    "inventoryType" : "SERVICE",
    "measure" : "pcs",
    "price" : 100.00,
    "quantity" : 1.0,
    "agentInformation" : {
      "contractorInn" : "2204000595",
      "contractorName" : "Модульбанк",
      "contractorPhone" : "+7123456789",
      "tags" : [ "AGENT" ]
    }
  } ],
  "customerContact" : "+71234567890",
  "responseURL" : "https://your-callback-service.com/complete-order?id=1",
  "clientInformation" : {
    "name" : "Иванов Иван Иванович",
    "documentNumber" : "1234567"
  }
}

2.3. Получение заказа

GET /v2/retail-point/{retailPointId}/order/{orderId}

2.3.1. Параметры

Тип Имя Описание Схема

Path

orderId
обязательно

ID заказа

string

Path

retailPointId
обязательно

ID точки продаж

string

2.3.2. Ответы

HTTP код Описание Схема

200

Заказ найден

Order

401

Запрос не авторизован

Без содержимого

403

У пользователя недостаточно прав для работы с заказами

Без содержимого

404

Точка продаж или заказ не найдены

Без содержимого

2.4. Получение списка заказов

GET /v2/retail-point/{retailPointId}/order

2.4.1. Параметры

Тип Имя Описание Схема

Path

retailPointId
обязательно

ID точки продаж

string

2.4.2. Ответы

HTTP код Описание Схема

200

OK

Order

401

Запрос не авторизован

Без содержимого

403

У пользователя недостаточно прав для работы с заказами

Без содержимого

404

Точка продаж не найдена

Без содержимого

2.5. Удаление заказа

DELETE /v2/retail-point/{retailPointId}/order/{orderId}

2.5.1. Параметры

Тип Имя Описание Схема

Path

orderId
обязательно

ID заказа

string

Path

retailPointId
обязательно

ID точки продаж

string

2.5.2. Ответы

HTTP код Описание Схема

200

Заказ успешно удалён

Без содержимого

401

Запрос не авторизован

Без содержимого

403

У пользователя недостаточно прав для работы с заказами

Без содержимого

404

Точка продаж или заказ не найдены

Без содержимого

3. Модель данных

3.1. Order

Имя Описание Схема

id
необязательно

ID заказа
Устанавливается автоматически при создании заказа
Пример : "4f4c789c-3863-41d3-aea9-c35b5a9e7f18"

string

remoteId
необязательно

ID заказа во внешней системе
Пример : "12345"

string

documentNumber
обязательно

Номер заказа
должен быть уникальным в рамках точки продаж
Пример : "ORDER-12345"

string

documentType
обязательно

Тип документа:

  • SALE - Заказ продажи
  • RETURN - Заказ возврата

enum (SALE, RETURN)

documentDateTime
обязательно

Пример : "2019-09-18T14:41:04+07:00"

string (date-time)

inventPositions
обязательно

Позиции заказа

< InventPosition > array

customerContact
необязательно

Адрес электронной почты или телефон покупателя
Допустимы символы для адреса электронной почты.
Номер телефона в формате +7<10 цифр>
При проведении заказа на кассе, ОФД отправляет чек клиенту.
Пример : "+71234567890"

string

responseURL
необязательно

URL для подтверждения успешной фискализации на кассе
Пример : "https://your-callback-service.com/complete-order?id=1"

string

description
необязательно

Примечание к заказу
Пример : "Примечание к заказу"

string

checkComment
необязательно

Комментарий для печати на чеке
Пример : "Пример"

string

checkCommentChanged
необязательно

Комментарий для печати на чеке был изменён
Пример : false

boolean

agentInformation
необязательно

Агентские данные

AgentInformation

clientInformation
необязательно

Клиентские данные

ClientInformation

totalSum
необязательно

Общая сумма заказа
Вычисляется автоматически из переданных позиций заказа

number

3.2. AgentInformation

Имя Описание Схема

tags
необязательно

Признак агента:

  • BANK_PAY_AGENT - банковский платежный агент. Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платежным агентом.
  • BANK_PAY_SUBAGENT - банковский платежный субагент. Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платежным субагентом.
  • PAY_AGENT - платежный агент. Оказание услуг покупателю (клиенту) пользователем, являющимся платежным агентом.
  • PAY_SUBAGENT - платежный субагент. Оказание услуг покупателю (клиенту) пользователем, являющимся платежным субагентом.
  • ATTORNEY - поверенный. Осуществление расчета с покупателем (клиентом) пользователем, являющимся поверенным.
  • COMMISSION_AGENT - комиссионер. Осуществление расчета с покупателем (клиентом) пользователем, являющимся комиссионером.
  • AGENT - другой тип агента

< enum (BANK_PAY_AGENT, BANK_PAY_SUBAGENT, PAY_AGENT, PAY_SUBAGENT, ATTORNEY, COMMISSION_AGENT, AGENT) > array

commissionAgentPhone
необязательно

Телефон оператора по приему платежей
Шаблон : "^((\\+7|7|8)+([0-9]){10})$"
Пример : "+71234567890"

string

contractorPhone
необязательно

Телефон поставщика
Шаблон : "^((\\+7|7|8)+([0-9]){10})$"
Пример : "+71234567890"

string

operation
необязательно

Наименование операции платежного агента

string

paymentAgentPhone
необязательно

Телефон платежного агента
Шаблон : "^((\\+7|7|8)+([0-9]){10})$"
Пример : "+71234567890"

string

transferOperatorName
необязательно

Наименование оператора перевода

string

transferOperatorInn
необязательно

ИНН оператора перевода

string

transferOperatorAddress
необязательно

Адрес оператора перевода

string

transferOperatorPhone
необязательно

Телефон оператора перевода
Шаблон : "^((\\+7|7|8)+([0-9]){10})$"
Пример : "+71234567890"

string

3.3. ClientInformation

Имя Описание Схема

name
необязательно

Наименование клиента
Пример : "ООО Ромашка"

string

inn
необязательно

ИНН
Пример : "500100732259"

string

documentNumber
необязательно

Номер документа

string

3.4. InventPosition

Имя Описание Схема

inventCode
необязательно

Код товара

string

barcode
необязательно

Штрихкод товара

string

name
необязательно

Наименование товара

string

inventoryType
необязательно

Тип товара

enum (INVENTORY, TOBACCO, OPERATION, SERVICE, PREPAID, OTHER_EXCISABLE, ALCOHOL, LIGHT_ALCOHOL, FREE_SALE, PREPAID_CORRECTION)

measure
обязательно

Единица измерения

enum (pcs, ltr, kg, m, m2, m3, h, other)

description
необязательно

Описание товара

string

price
обязательно

Цена за единицу товара
Минимальное значение : 0

number

quantity
обязательно

Количество единиц товара
Минимальное значение (исключение) : 0

number

minPrice
необязательно

Минимальная цена
Минимальное значение : 0

number

originCountryCode
необязательно

Код страны происхождения товара (из ОКСМ)
Шаблон : "^\\d{1,3}$"
Пример : "112"

string

customsDeclarationNumber
необязательно

Номер таможенной декларации

string

taxMode
необязательно

Режим налогообложения:

  • COMMON - ОСН
  • SIMPLIFIED - УСН-Д
  • SIMPLIFIED_WITH_EXPENSE - УСН-ДР
  • ENVD - ЕНВД
  • COMMON_AGRICULTURAL - ЕСХН
  • PATENT - ПСН

enum (COMMON, SIMPLIFIED, SIMPLIFIED_WITH_EXPENSE, ENVD, COMMON_AGRICULTURAL, PATENT)

vatTag
необязательно

Признак налогообложения:

  • 1102 - 20%
  • 1103 - 10%
  • 1104 - 0%
  • 1105 - Без НДС
  • 1106 - 20/120
  • 1107 - 10/110

integer (int32)

agentInformation
необязательно

Данные агента

PositionAgentInformation

posSum
необязательно

Стоимость позиции заказа Вычисляется автоматически при создании заказа

number

3.5. PositionAgentInformation

Имя Описание Схема

tags
необязательно

Признак агента:

  • BANK_PAY_AGENT - банковский платежный агент. Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платежным агентом.
  • BANK_PAY_SUBAGENT - банковский платежный субагент. Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платежным субагентом.
  • PAY_AGENT - платежный агент. Оказание услуг покупателю (клиенту) пользователем, являющимся платежным агентом.
  • PAY_SUBAGENT - платежный субагент. Оказание услуг покупателю (клиенту) пользователем, являющимся платежным субагентом.
  • ATTORNEY - поверенный. Осуществление расчета с покупателем (клиентом) пользователем, являющимся поверенным.
  • COMMISSION_AGENT - комиссионер. Осуществление расчета с покупателем (клиентом) пользователем, являющимся комиссионером.
  • AGENT - другой тип агента

< enum (BANK_PAY_AGENT, BANK_PAY_SUBAGENT, PAY_AGENT, PAY_SUBAGENT, ATTORNEY, COMMISSION_AGENT, AGENT) > array

commissionAgentPhone
необязательно

Телефон оператора по приему платежей
Шаблон : "^((\\+7|7|8)+([0-9]){10})$"
Пример : "+71234567890"

string

contractorName
необязательно

Наименование поставщика

string

contractorInn
необязательно

ИНН поставщика

string

contractorPhone
необязательно

Телефон поставщика
Шаблон : "^((\\+7|7|8)+([0-9]){10})$"
Пример : "+71234567890"

string

operation
необязательно

Операция платежного агента

string

phone
необязательно

Телефон платежного агента
Шаблон : "^((\\+7|7|8)+([0-9]){10})$"
Пример : "+71234567890"

string

transferOperatorName
необязательно

Наименование оператора перевода

string

transferOperatorInn
необязательно

ИНН оператора перевода

string

transferOperatorAddress
необязательно

Адрес оператора перевода

string

transferOperatorPhone
необязательно

Телефон оператора перевода
Шаблон : "^((\\+7|7|8)+([0-9]){10})$"
Пример : "+71234567890"

string

3.6. PageResponse_Order

Имя Описание Схема

data
необязательно

Список заказов на странице

< Order > array

pos
обязательно

Стартовая позиция для списка заказов
Пример : 2

integer (int32)

total_count
обязательно

Общее количество заказов
Пример : 3

integer (int64)