Данная документация содержит описание методов API Кабинета Дримкас.

Аттрибут Значение
Базовый адрес https://kabinet.dreamkas.by/api
Формат JSON
Кодировка UTF-8

Все запросы к API, содержащие тело (POST, PUT, PATCH) должны выполняться с заголовком Content-Type: application/json. В противном случае, вы будете получать 400 ошибку, так как тело запроса не будет корректно обработано.


Авторизация

Для вызова большинства методов требуется авторизация.

По Cookies

Этот режим используется по умолчанию. Когда пользователь вводит логин/пароль в форме авторизации, в браузере выставляется Cookie, которая в дальнейшем используется для идентификации пользователя в API.

Все публичное API описанное в данной документации так или иначе используется самим Кабинетом Дримкас.

Поэтому если у Вас возникают вопросы по работе того или иного метода, то вы всегда можете подсмотреть реализацию через инструменты отладки браузера в соответствующем разделе Кабинета.

По токену

Это наиболее предпочтительный способ авторизации. Для запросов к API вам понадобится (внимание!) токен.

Получить его можно двумя способами: 1. Сгенерировать лично в настройках аккаунта. 2. Пройти OAuth авторизацию в одном из интеграционных решений. В этом случае созданный токен будет автоматически передан приложению, и оно сможет управлять вашим аккаунтом в ограниченном режиме. Например, приложение не сможет создавать/удалять устройства (кассы) в вашем аккаунте, изменять пароль, и т.д.

Для авторизации требуется передавать заголовок Authorization: Bearer {TOKEN} при каждом вызове API.

Пример: Authorization: Bearer f7bf8f74-c225-46be-9d92-a4e6380d25b4.

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

Фрагмент кода на PHP

$token = 'f7bf8f74-c225-46be-9d92-a4e6380d25b4';
$headers = array(
  'Authorization: Bearer '.$token,
);

curl_setopt($curlHandle, CURLOPT_HTTPHEADER, $headers);

Базовая HTTP авторизация

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

Для авторизации при каждом вызове API требуется передавать заголовок: Authorization: Basic {base64(логин:пароль)}

Пример: Для пары логин:пароль test@example.com:123456 заголовок будет выглядеть так Authorization: Basic dGVzdEBleGFtcGxlLmNvbToxMjM0NTY=

Фрагмент кода на PHP

$login = 'test@example.com';
$password = '123456';
$headers = array(
  'Authorization: Basic '.base64_encode($login.':'.$password),
);

curl_setopt($curlHandle, CURLOPT_HTTPHEADER, $headers);

Авторизация приложений

Этот тип авторизации может быть использован интеграционными решениями для вызова сервисных методов, например, для создания пользователей.

Авторизация аналогична базовой. Для авторизации при каждом вызове API требуется передавать заголовок: Authorization: Basic {base64(client_id:client_secret)}


Подписка на обновления

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

Например, давайте рассмотрим фискализацияю чека по API. Когда вы отправляете чек, мы ставим его в очередь. Касса с определенной периодичностью стучится в наш шлюз и забирает на выполнение адресованные ей задачи. Иногда интернет-соединение на кассе теряется, она может перезагружаться или на ней в данный момент работает кассир. Как бы там ни было, моментально выполнить запрос нельзя. Для этого, при запросе

В Кабинете Дримкас реализованы два принципиально отличающихся способа получения информации об изменениях в аккаунте.

Поллинг

Наиболее подходит для решений, которые не имеют статичного IP-адреса в сети Интернет. Для реализации этого способа вам необходимо реализовать планировщик (cron), который будет с некоторой периодичностью опрашивать API на предмет изменений.

Такое решение наиболее востребовано при фискализации чеков по API. При отправке запроса, вы получаете ответ со статусом 202 Accepted и идентификатором операции. На этом этапе ваш запрос еще не выполнен, он только добавлен в очередь. Фактически, запрос будет считаться выполненым, только когда касса сама сообщит об этом. Таким образом, в ответе вы получаете своеобразный трек-номер, к которому мы все привыкли на почте.

Используя данный идентификатор, с определенной периодичностью (10-20-30 сек.) вам следует проверять (поллить) результат операции (см. API Операции).

Вебхуки

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

Для работы вам необходимо на вашей стороне реализовать метод (endpoint url), в который Кабинет будет присылать уведомления посредством HTTP-запросов. После чего в настройках Кабинета вы указываете этот URL, так же события, по которым Кабинет будет отправлять уведомления.


Описание ошибок

Первое правило бойцовского клуба: если вы не получили в ответе статус 2ХХ, то что-то пошло не так.

Клиентские ошибки (4XX)

Возникают в случае обнаружения ошибок в запросе клиента. Типичные ситуации: - неверный запрос;

  • ошибки валидации;

  • доступ запрещен;

  • требуется авторизация;

Наиболее частые ошибки

Статус Описание Способы устранения
400 Ошибка валидации Проверьте правильность введенных данных.
401 Требуется авторизация Проверьте, правильно ли реализован блок авторизации.
403 Доступ запрещен Авторизованному объекту запрещен доступ к ресурсу. Например, пытаетесь отредактировать чужую кассу.
404 Ресурс не найден Проверить правильность написания ресурса, к которому обращаетесь.
410 Ресурс удален Попытка получить доступ к удаленным данным, например, операциям, которые были заверешены более месяца назад.
429 Достигнут лимит запросов Слишком много однотипных запросов, подождите немного и повторите попытку.

Клиентские ошибки, как правило, выдаются с пояснениями.

Пример ответа с ошибкой

{
  "status": 400,
  "code": "E_VALIDATION_FAILED",
  "message": "Ошибка валидации",
  "data": {
    "errors": [
      {
        "code": "E_PRODUCT_NAME_EMPTY",
        "message": "Наименование товара не должно быть пустым"
      }
    ]
  }
}

Серверные ошибки (5ХХ)

Серверная ошибка. Типичные ситуации: - ведутся технические работы;

  • произошел сбой на сервере;

В этом случае, как правило, просто следует повторить запрос немного позднее.

Если ошибка повторяется на проятяжении длительного времени, обратитесь в поддержку.


OAuth2

Для интеграции со сторонними сервисами Кабинет Дримкас поддерживает OAuth2 авторизацию. Простейший пример реализации на Node.js можно найти здесь.

Для начала работы вам потребуется client_id и client_secret. Их можно запросить через техподдержку Дримкас, отправив запрос с контактными данными на help@dreamkas.by.

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

Запрос на авторизацию

GEThttps://kabinet.dreamkas.by/api/oauth2/authorize{?client_id,redirect_uri}

После перехода по этой ссылке, пользователю будет предложено подтвердить авторизацию. При согласии, он будет переадресован по адресу, указанному в redirect_uri.

В обработчике следует проверить наличие параметров code и error.

Если code пришел, а error пустой, то пользователь подтвердил авторизацию и нужно получить для него access_token с использованием которого ваше приложение сможет осуществлять действия в аккаунте пользователя Кабинета.

Параметры строки запроса
Параметр Тип Обяз. Описание
client_id number Да Идентификатор приложения.
redirect_uri string Да Обработчик результата авторизации
Пример ответа 302 Found
Location: http://localhost/?uid=123&code=1234567890

Получение токена

POSThttps://kabinet.dreamkas.by/api/oauth2/access_token

При выполнении данного запроса, вы получите access_token для работы с аккаунтом авторизовавшегося пользователя. Этот токен следует сохранить в вашей системе и в дальнейшем использовать его для запросов, когда нужно произвести какие либо действия в аккаунте пользователя Кабинета Дримкас.

Токен не имеет ограничения по времени действия. Однако, пользователь в любой момент может отменить интеграцию, удалив выданный токен в настройках. В этом случае ваше приложение утратит возможность работать с аккаунтом данного пользователя. Обязательно учитывайте это, чтобы не спамить API бесполезными запросами, т.к. на них всегда будет отдаваться ошибка авторизации. Как только Вы получили статус 401 Unauthorized - можете считать, что пользователь отменил интеграцию. Удалите токен в своей системе и попросите его авторизоваться заново.

Пример запроса
Content-Type: application/json
{
    "code": "1234567890",
    "client_id": 1,
    "client_secret": "0aa9e134-b2ed-451e-bb98-c7d91ee843f2"
}
Пример запроса
Content-Type: application/json
{
    "code": "1234567890",
    "client_id": 1,
    "client_secret": "0aa9e134-b2ed-451e-bb98-c7d91ee843f2"
}
Пример ответа 200 OK
Content-Type: application/json
{
    "access_token": "a047fb5a-9464-4267-ac47-8c47ad100e27"
}
Пример ответа 403 Forbidden
Content-Type: application/json
{
    "statusCode": 403,
    "error": "Forbidden",
    "message": "Bad Code"
}

Товары

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

НДС

Для кодирования значения НДС используется следующий формат: NDS_XX_YY, где XX - целая часть значения (до точки), YY - дробная часть (после точки).

Минимальный НДС - 0%, максимальный - 100%

Примеры
Код Значение
NDS_0 0%
NDS_0_03 0.03%
NDS_2_93 2.93%
NDS_35_01 35.01%
NDS_100 100%

Штрихкоды

Используемый формат - GTIN (14 символов).

Единица товара

Единица товара quantity измеряется в тысячных и значение этого поля следует воспринимать по-разному, в завимисости от типа товара type

Примеры
type quantity значение
SCALABLE 1 1 грамм
SCALABLE 200 200 грамм
SCALABLE 1000 1 кг
COUNTABLE 1000 1 шт
ALCOHOL 1000 1 бутылка/банка

Если алкоголь продается в розлив, то нужно установить параметр volume = 0, тогда значение quantity = 200, будет означать, что продукт продается в розлив по 200 мл

Работа с коллекцией

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

GEThttps://kabinet.dreamkas.by/api/products{?limit,offset}
Параметры строки запроса
Параметр Тип Обяз. Описание
limit number Нет Количество записей в ответе (если не указан, то вернутся все товары)
offset number Нет Смещение
Пример ответа 200 OK
Content-Type: application/json
[
  {
    "id": "b0381fe4-4428-4dcb-8169-c8bbcab59626",
    "name": "Новый товар",
    "type": "COUNTABLE",
    "departmentId": 0,
    "quantity": 1000,
    "prices": [
      {
        "deviceId": 1,
        "value": 1200
      }
    ],
    "meta": {},
    "barcodes": [
      "AB_1234",
      "00000001"
    ],
    "tax": "NDS_0 .. NDS_100",
    "createdAt": "2017-05-05T14:15:01.239Z",
    "updatedAt": "2017-05-05T14:15:01.239Z"
  }
]

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

POSThttps://kabinet.dreamkas.by/api/products

Данный метод поддерживает создание одного или нескольких товаров. Для создания одного товара тело запроса должно содержать объект с данными товара. Для создания нескольких товаров нужно передать массив вида [{ Товар 1 }, { Товар 2 }, { Товар3 }].

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

Параметры тела запроса
Параметр Тип Описание
id string

UUID товара (если не передан, UUID будет сгенерирован автоматически).

Указывать UUID можно только при создании товара. Изменить идентификатор товара после создания нельзя.

Пример: b0381fe4-4428-4dcb-8169-c8bbcab59626
name string

Название

По умолчанию: Новый товар
type enum

Тип продукта

Принимает одно из значений
Значение Описание
COUNTABLE

Штучный

SCALABLE

Весовой

ALCOHOL

Алкогольный

CLOTHES

Одежда

SHOES

Обувь

SERVICES

Услуги

departmentId number

ID отдела магазина

quantity number

Единица товара

Пример: 1000
prices array

Цена для каждого устройства

Параметр Тип Описание
deviceId number

ID устройства

Пример: 1
value number

Цена в копейках

Пример: 1200
price number

Цена товара для новых устройств (если не указать, будет взято максимальное значение из prices)

meta object

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

Параметр Тип Описание
barcodes array

Штрихкоды. Если длина 8, 12 или 13, то проверяется на контрольную сумму

Пример: ["AB_1234", "00000001"]
tax enum

Налог

Принимает одно из значений
Значение Описание
NDS_0 .. NDS_100

НДС 0% - 100% (подробнее в разделе “Товары”)

Создание одного товара
Content-Type: application/json
{
  "id": "b0381fe4-4428-4dcb-8169-c8bbcab59626",
  "name": "Новый товар",
  "type": "COUNTABLE",
  "departmentId": 0,
  "quantity": 1000,
  "prices": [
    {
      "deviceId": 1,
      "value": 1200
    }
  ],
  "meta": {},
  "barcodes": [
    "AB_1234",
    "00000001"
  ],
  "tax": "NDS_0 .. NDS_100"
}
Создание нескольких товаров
Content-Type: application/json
[
  {
    "id": "b0381fe4-4428-4dcb-8169-c8bbcab59626",
    "name": "Новый товар",
    "type": "COUNTABLE",
    "departmentId": 0,
    "quantity": 1000,
    "prices": [
      {
        "deviceId": 1,
        "value": 1200
      }
    ],
    "meta": {},
    "barcodes": [
      "AB_1234",
      "00000001"
    ],
    "tax": "NDS_0 .. NDS_100"
  }
]
Пример ответа 201 Created
Content-Type: application/json
{
    "id": "b0381fe4-4428-4dcb-8169-c8bbcab59626"
}
Пример ответа 400 Bad Request
Content-Type: application/json
{
    "result": {
        "0": {
            "id": 1
        }
    },
    "errors": {
        "1": {
            "status": 400,
            "code": "E_VALIDATION_FAILED",
            "message": "Ошибка валидации",
            "data": {
                "errors": [
                    {
                        "code": "E_PRODUCT_INVALID_TAX",
                        "message": "Указан некорректный НДС"
                    }
                ]
            }
        }
    }
}

Множественное редактирование

PATCHhttps://kabinet.dreamkas.by/api/products
Пример запроса
Content-Type: application/json
[
  {
    "id": "",
    "name": "Новый товар",
    "type": "COUNTABLE",
    "departmentId": 0,
    "quantity": 1000,
    "prices": [
      {
        "deviceId": 1,
        "value": 1200
      }
    ],
    "meta": {},
    "barcodes": [
      "AB_1234",
      "00000001"
    ],
    "tax": "NDS_0 .. NDS_100"
  }
]
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Множественное удаление

DELETEhttps://kabinet.dreamkas.by/api/products

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

Пример запроса
Content-Type: application/json
[
  {
    "id": "cdaafe3d-a89a-4f66-afb6-ac8277d54110"
  }
]
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Работа с экземпляром товара

Параметры строки запроса
Параметр Тип Обяз. Описание
id string Да Идентификатор товара

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

GEThttps://kabinet.dreamkas.by/api/products/{id}
Параметры тела ответа
Параметр Тип Описание
id string

UUID товара (если не передан, UUID будет сгенерирован автоматически).

Указывать UUID можно только при создании товара. Изменить идентификатор товара после создания нельзя.

Пример: b0381fe4-4428-4dcb-8169-c8bbcab59626
name string

Название

По умолчанию: Новый товар
type enum

Тип продукта

Принимает одно из значений
Значение Описание
COUNTABLE

Штучный

SCALABLE

Весовой

ALCOHOL

Алкогольный

CLOTHES

Одежда

SHOES

Обувь

SERVICES

Услуги

departmentId number

ID отдела магазина

quantity number

Единица товара

Пример: 1000
prices array

Цена для каждого устройства

Параметр Тип Описание
deviceId number

ID устройства

Пример: 1
value number

Цена в копейках

Пример: 1200
price number

Цена товара для новых устройств (если не указать, будет взято максимальное значение из prices)

meta object

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

Параметр Тип Описание
barcodes array

Штрихкоды. Если длина 8, 12 или 13, то проверяется на контрольную сумму

Пример: ["AB_1234", "00000001"]
tax enum

Налог

Принимает одно из значений
Значение Описание
NDS_0 .. NDS_100

НДС 0% - 100% (подробнее в разделе “Товары”)

createdAt string

Дата создания

Пример: 2017-05-05T14:15:01.239Z
updatedAt string

Дата последнего изменения

Пример: 2017-05-05T14:15:01.239Z
Пример ответа 200 OK
Content-Type: application/json
{
  "id": "b0381fe4-4428-4dcb-8169-c8bbcab59626",
  "name": "Новый товар",
  "type": "COUNTABLE",
  "departmentId": 0,
  "quantity": 1000,
  "prices": [
    {
      "deviceId": 1,
      "value": 1200
    }
  ],
  "meta": {},
  "barcodes": [
    "AB_1234",
    "00000001"
  ],
  "tax": "NDS_0 .. NDS_100",
  "createdAt": "2017-05-05T14:15:01.239Z",
  "updatedAt": "2017-05-05T14:15:01.239Z"
}

Редактирование товара

PATCHhttps://kabinet.dreamkas.by/api/products/{id}
Параметры тела запроса
Параметр Тип Описание
id string

UUID товара (если не передан, UUID будет сгенерирован автоматически).

Указывать UUID можно только при создании товара. Изменить идентификатор товара после создания нельзя.

Пример: b0381fe4-4428-4dcb-8169-c8bbcab59626
name string

Название

По умолчанию: Новый товар
type enum

Тип продукта

Принимает одно из значений
Значение Описание
COUNTABLE

Штучный

SCALABLE

Весовой

ALCOHOL

Алкогольный

CLOTHES

Одежда

SHOES

Обувь

SERVICES

Услуги

departmentId number

ID отдела магазина

quantity number

Единица товара

Пример: 1000
prices array

Цена для каждого устройства

Параметр Тип Описание
deviceId number

ID устройства

Пример: 1
value number

Цена в копейках

Пример: 1200
price number

Цена товара для новых устройств (если не указать, будет взято максимальное значение из prices)

meta object

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

Параметр Тип Описание
barcodes array

Штрихкоды. Если длина 8, 12 или 13, то проверяется на контрольную сумму

Пример: ["AB_1234", "00000001"]
tax enum

Налог

Принимает одно из значений
Значение Описание
NDS_0 .. NDS_100

НДС 0% - 100% (подробнее в разделе “Товары”)

Пример запроса
Content-Type: application/json
{
  "id": "b0381fe4-4428-4dcb-8169-c8bbcab59626",
  "name": "Новый товар",
  "type": "COUNTABLE",
  "departmentId": 0,
  "quantity": 1000,
  "prices": [
    {
      "deviceId": 1,
      "value": 1200
    }
  ],
  "meta": {},
  "barcodes": [
    "AB_1234",
    "00000001"
  ],
  "tax": "NDS_0 .. NDS_100"
}
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Удаление товара

DELETEhttps://kabinet.dreamkas.by/api/products/{id}
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Товары V2

/v2/products

Список товаров

GEThttps://kabinet.dreamkas.by/api/V2/products{?limit,offset}
Параметры строки запроса
Параметр Тип Обяз. Описание
limit number Нет Количество записей в ответе, по умолчанию 100
offset number Нет Смещение
Пример ответа 200 OK
Content-Type: application/json
[
  {
    "id": "b0381fe4-4428-4dcb-8169-c8bbcab59626",
    "name": "Новый товар",
    "type": "COUNTABLE",
    "departmentId": 0,
    "quantity": 1000,
    "prices": [
      {
        "deviceId": 1,
        "value": 1200
      }
    ],
    "meta": {},
    "barcodes": [
      "12341238"
    ],
    "vendorCodes": [
      "AB_1234"
    ],
    "tax": "NDS_0 .. NDS_100",
    "createdAt": "2017-05-05T14:15:01.239Z",
    "updatedAt": "2017-05-05T14:15:01.239Z"
  }
]

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

POSThttps://kabinet.dreamkas.by/api/v2/products

Данный метод поддерживает создание одного или нескольких товаров. Для создания одного товара тело запроса должно содержать объект с данными товара. Для создания нескольких товаров нужно передать массив вида [{ Товар 1 }, { Товар 2 }, { Товар 3 }].

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

Параметры тела запроса
Параметр Тип Описание
id string

UUID товара (если не передан, UUID будет сгенерирован автоматически).

Указывать UUID можно только при создании товара. Изменить идентификатор товара после создания нельзя.

Пример: b0381fe4-4428-4dcb-8169-c8bbcab59626
name string

Название

По умолчанию: Новый товар
type enum

Тип продукта

Принимает одно из значений
Значение Описание
COUNTABLE

Штучный

SCALABLE

Весовой

ALCOHOL

Алкогольный

CLOTHES

Одежда

SHOES

Обувь

SERVICES

Услуги

departmentId number

ID отдела магазина

quantity number

Единица товара

Пример: 1000
prices array

Цена для каждого устройства

Параметр Тип Описание
deviceId number

ID устройства

Пример: 1
value number

Цена в копейках

Пример: 1200
price number

Цена товара для новых устройств (если не указать, будет взято максимальное значение из prices)

meta object

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

Параметр Тип Описание
barcodes array

Штрихкоды. Только длины 8, 12 или 13. Проверяется на контрольную сумму

Пример: ["12341238"]
vendorCodes array

Артикулы, никаких валидаций

Пример: ["AB_1234"]
tax enum

Налог

Принимает одно из значений
Значение Описание
NDS_0 .. NDS_100

НДС 0% - 100% (подробнее в разделе “Товары”)

Создание одного товара
Content-Type: application/json
{
  "id": "b0381fe4-4428-4dcb-8169-c8bbcab59626",
  "name": "Новый товар",
  "type": "COUNTABLE",
  "departmentId": 0,
  "quantity": 1000,
  "prices": [
    {
      "deviceId": 1,
      "value": 1200
    }
  ],
  "meta": {},
  "barcodes": [
    "12341238"
  ],
  "vendorCodes": [
    "AB_1234"
  ],
  "tax": "NDS_0 .. NDS_100"
}
Создание нескольких товаров
Content-Type: application/json
[
  {
    "id": "b0381fe4-4428-4dcb-8169-c8bbcab59626",
    "name": "Новый товар",
    "type": "COUNTABLE",
    "departmentId": 0,
    "quantity": 1000,
    "prices": [
      {
        "deviceId": 1,
        "value": 1200
      }
    ],
    "meta": {},
    "barcodes": [
      "12341238"
    ],
    "vendorCodes": [
      "AB_1234"
    ],
    "tax": "NDS_0 .. NDS_100"
  }
]
Пример ответа 201 Created
Content-Type: application/json
{
    "id": "b0381fe4-4428-4dcb-8169-c8bbcab59626"
}
Пример ответа 201 Created
Content-Type: application/json
{
    "result": {
        "0": {
            "id": 1
        }
    },
    "errors": {
        "1": {
            "status": 400,
            "code": "E_VALIDATION_FAILED",
            "message": "Ошибка валидации",
            "data": {
                "errors": [
                    {
                        "code": "E_PRODUCT_INVALID_TAX",
                        "message": "Указан некорректный НДС"
                    }
                ]
            }
        }
    }
}

Множественное редактирование

PATCHhttps://kabinet.dreamkas.by/api/v2/products
Пример запроса
Content-Type: application/json
[
  {
    "id": "",
    "name": "Новый товар",
    "type": "COUNTABLE",
    "departmentId": 0,
    "quantity": 1000,
    "prices": [
      {
        "deviceId": 1,
        "value": 1200
      }
    ],
    "meta": {},
    "barcodes": [
      "12341238"
    ],
    "vendorCodes": [
      "AB_1234"
    ],
    "tax": "NDS_0 .. NDS_100"
  }
]
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Множественное удаление

DELETEhttps://kabinet.dreamkas.by/api/v2/products
Пример запроса
Content-Type: application/json
[
  {
    "id": "cdaafe3d-a89a-4f66-afb6-ac8277d54110"
  }
]
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

/v2/products/{id}

Параметры строки запроса
Параметр Тип Обяз. Описание
id string Да Идентификатор

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

GEThttps://kabinet.dreamkas.by/api/v2/products/{id}
Параметры тела ответа
Параметр Тип Описание
id string

UUID товара (если не передан, UUID будет сгенерирован автоматически).

Указывать UUID можно только при создании товара. Изменить идентификатор товара после создания нельзя.

Пример: b0381fe4-4428-4dcb-8169-c8bbcab59626
name string

Название

По умолчанию: Новый товар
type enum

Тип продукта

Принимает одно из значений
Значение Описание
COUNTABLE

Штучный

SCALABLE

Весовой

ALCOHOL

Алкогольный

CLOTHES

Одежда

SHOES

Обувь

SERVICES

Услуги

departmentId number

ID отдела магазина

quantity number

Единица товара

Пример: 1000
prices array

Цена для каждого устройства

Параметр Тип Описание
deviceId number

ID устройства

Пример: 1
value number

Цена в копейках

Пример: 1200
price number

Цена товара для новых устройств (если не указать, будет взято максимальное значение из prices)

meta object

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

Параметр Тип Описание
barcodes array

Штрихкоды. Только длины 8, 12 или 13. Проверяется на контрольную сумму

Пример: ["12341238"]
vendorCodes array

Артикулы, никаких валидаций

Пример: ["AB_1234"]
tax enum

Налог

Принимает одно из значений
Значение Описание
NDS_0 .. NDS_100

НДС 0% - 100% (подробнее в разделе “Товары”)

createdAt string

Дата создания

Пример: 2017-05-05T14:15:01.239Z
updatedAt string

Дата последнего изменения

Пример: 2017-05-05T14:15:01.239Z
Пример ответа 200 OK
Content-Type: application/json
{
  "id": "b0381fe4-4428-4dcb-8169-c8bbcab59626",
  "name": "Новый товар",
  "type": "COUNTABLE",
  "departmentId": 0,
  "quantity": 1000,
  "prices": [
    {
      "deviceId": 1,
      "value": 1200
    }
  ],
  "meta": {},
  "barcodes": [
    "12341238"
  ],
  "vendorCodes": [
    "AB_1234"
  ],
  "tax": "NDS_0 .. NDS_100",
  "createdAt": "2017-05-05T14:15:01.239Z",
  "updatedAt": "2017-05-05T14:15:01.239Z"
}

Редактирование товара

PATCHhttps://kabinet.dreamkas.by/api/v2/products/{id}
Параметры тела запроса
Параметр Тип Описание
id string

UUID товара (если не передан, UUID будет сгенерирован автоматически).

Указывать UUID можно только при создании товара. Изменить идентификатор товара после создания нельзя.

Пример: b0381fe4-4428-4dcb-8169-c8bbcab59626
name string

Название

По умолчанию: Новый товар
type enum

Тип продукта

Принимает одно из значений
Значение Описание
COUNTABLE

Штучный

SCALABLE

Весовой

ALCOHOL

Алкогольный

CLOTHES

Одежда

SHOES

Обувь

SERVICES

Услуги

departmentId number

ID отдела магазина

quantity number

Единица товара

Пример: 1000
prices array

Цена для каждого устройства

Параметр Тип Описание
deviceId number

ID устройства

Пример: 1
value number

Цена в копейках

Пример: 1200
price number

Цена товара для новых устройств (если не указать, будет взято максимальное значение из prices)

meta object

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

Параметр Тип Описание
barcodes array

Штрихкоды. Только длины 8, 12 или 13. Проверяется на контрольную сумму

Пример: ["12341238"]
vendorCodes array

Артикулы, никаких валидаций

Пример: ["AB_1234"]
tax enum

Налог

Принимает одно из значений
Значение Описание
NDS_0 .. NDS_100

НДС 0% - 100% (подробнее в разделе “Товары”)

Пример запроса
Content-Type: application/json
{
  "id": "b0381fe4-4428-4dcb-8169-c8bbcab59626",
  "name": "Новый товар",
  "type": "COUNTABLE",
  "departmentId": 0,
  "quantity": 1000,
  "prices": [
    {
      "deviceId": 1,
      "value": 1200
    }
  ],
  "meta": {},
  "barcodes": [
    "12341238"
  ],
  "vendorCodes": [
    "AB_1234"
  ],
  "tax": "NDS_0 .. NDS_100"
}
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Удаление товара

DELETEhttps://kabinet.dreamkas.by/api/v2/products/{id}
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Магазины

Предоставляет методы для управления магазинами пользователя.

Основное предназначение магазинов - логическая группировка устройств в Кабинете

/shops

Список магазинов

GEThttps://kabinet.dreamkas.by/api/shops
Пример ответа 200 OK
Content-Type: application/json
[
  {
    "name": "Магазин №1",
    "sort": 999,
    "id": 1
  }
]

Создание магазина

POSThttps://kabinet.dreamkas.by/api/shops
Параметры тела запроса
Параметр Тип Описание
name string

Название магазина

Пример: Магазин №1
sort number

Индекс сортировки (для отображения)

Пример: 999
Параметры тела ответа
Параметр Тип Описание
name string

Название магазина

Пример: Магазин №1
sort number

Индекс сортировки (для отображения)

Пример: 999
id number

Идентификатор

Пример: 1
Пример запроса
Content-Type: application/json
{
  "name": "Магазин №1",
  "sort": 999
}
Пример ответа 201 Created
Content-Type: application/json
{
  "name": "Магазин №1",
  "sort": 999,
  "id": 1
}

Множественное редактирование

PATCHhttps://kabinet.dreamkas.by/api/shops
Пример запроса
Content-Type: application/json
[
  {
    "name": "Магазин №1",
    "sort": 999,
    "id": 1
  }
]
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

/shops/{id}

Параметры строки запроса
Параметр Тип Обяз. Описание
id number Да Идентификатор магазина

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

GEThttps://kabinet.dreamkas.by/api/shops/{id}
Параметры тела ответа
Параметр Тип Описание
name string

Название магазина

Пример: Магазин №1
sort number

Индекс сортировки (для отображения)

Пример: 999
id number

Идентификатор

Пример: 1
Пример ответа 200 OK
Content-Type: application/json
{
  "name": "Магазин №1",
  "sort": 999,
  "id": 1
}

Редактирование магазина

PATCHhttps://kabinet.dreamkas.by/api/shops/{id}
Параметры тела запроса
Параметр Тип Описание
name string

Название магазина

Пример: Магазин №1
sort number

Индекс сортировки (для отображения)

Пример: 999
Пример запроса
Content-Type: application/json
{
  "name": "Магазин №1",
  "sort": 999
}
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Удаление магазина

DELETEhttps://kabinet.dreamkas.by/api/shops/{id}
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Устройства

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

/devices

Список устройств

GEThttps://kabinet.dreamkas.by/api/devices
Пример ответа 200 OK
Content-Type: application/json
[
  {
    "name": "",
    "groupId": 0,
    "sort": 0,
    "id": 0,
    "timezoneOffset": 0
  }
]

Создание кассы (доступно только для приложений)

POSThttps://kabinet.dreamkas.by/api/devices
Параметры тела запроса
Параметр Тип Описание
uuid string

UUID кассы

modelCode enum

На данный момент доступен только Дримкас-ф

Принимает одно из значений
Значение Описание
DREAMKAS_F

касса Дримкас-ф

callback string

URL, куда будет вызван вебхук после подключения кассы

Пример запроса
Content-Type: application/json
{
  "uuid": "",
  "modelCode": "DREAMKAS_F",
  "callback": ""
}
Пример ответа 202 Accepted

/devices/{id}

Параметры строки запроса
Параметр Тип Обяз. Описание
id number Да Идентификатор устройства

Информация об устройстве

GEThttps://kabinet.dreamkas.by/api/devices/{id}
Параметры тела ответа
Параметр Тип Описание
name string

Название

groupId number

Идентификатор магазина

sort number

Индекс сортировки (для отображения)

id number

Идентификатор

timezoneOffset number

Часовой пояс кассы , смещение в минутах от UTC

Пример ответа 200 OK
Content-Type: application/json
{
  "name": "",
  "groupId": 0,
  "sort": 0,
  "id": 0,
  "timezoneOffset": 0
}

Редактирование устройства

PATCHhttps://kabinet.dreamkas.by/api/devices/{id}
Параметры тела запроса
Параметр Тип Описание
name string

Название

groupId number

Идентификатор магазина

sort number

Индекс сортировки (для отображения)

Пример запроса
Content-Type: application/json
{
  "name": "",
  "groupId": 0,
  "sort": 0
}
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Отделы

Предоставляет методы для управления отделами пользователя.

Основное предназначение отделов - логическая группировка товаров в Кабинете

/departments

Список отделов

GEThttps://kabinet.dreamkas.by/api/departments
Пример ответа 200 OK
Content-Type: application/json
[
  {
    "name": "Хлебобулочные изделия",
    "tax": "NDS_0 .. NDS_100",
    "id": 0
  }
]

Создание отдела

POSThttps://kabinet.dreamkas.by/api/departments
Параметры тела запроса
Параметр Тип Описание
name string

Название отдела

Пример: Хлебобулочные изделия
tax enum

Налог

Принимает одно из значений
Значение Описание
NDS_0 .. NDS_100

НДС 0% - 100% (подробнее в разделе “Товары”)

NDS_MIXED

Товары в отделе имеют смешанные НДС

Параметры тела ответа
Параметр Тип Описание
name string

Название отдела

Пример: Хлебобулочные изделия
tax enum

Налог

Принимает одно из значений
Значение Описание
NDS_0 .. NDS_100

НДС 0% - 100% (подробнее в разделе “Товары”)

NDS_MIXED

Товары в отделе имеют смешанные НДС

id number

Идентификатор отдела

Пример запроса
Content-Type: application/json
{
  "name": "Хлебобулочные изделия",
  "tax": "NDS_0 .. NDS_100"
}
Пример ответа 201 Created
Content-Type: application/json
{
  "name": "Хлебобулочные изделия",
  "tax": "NDS_0 .. NDS_100",
  "id": 0
}

/departments/{id}

Параметры строки запроса
Параметр Тип Обяз. Описание
id number Да Идентификатор отдела

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

GEThttps://kabinet.dreamkas.by/api/departments/{id}
Параметры тела ответа
Параметр Тип Описание
name string

Название отдела

Пример: Хлебобулочные изделия
tax enum

Налог

Принимает одно из значений
Значение Описание
NDS_0 .. NDS_100

НДС 0% - 100% (подробнее в разделе “Товары”)

NDS_MIXED

Товары в отделе имеют смешанные НДС

id number

Идентификатор отдела

Пример ответа 200 OK
Content-Type: application/json
{
  "name": "Хлебобулочные изделия",
  "tax": "NDS_0 .. NDS_100",
  "id": 0
}

Редактирование отдела

PATCHhttps://kabinet.dreamkas.by/api/departments/{id}
Параметры тела запроса
Параметр Тип Описание
name string

Название отдела

Пример: Хлебобулочные изделия
tax enum

Налог

Принимает одно из значений
Значение Описание
NDS_0 .. NDS_100

НДС 0% - 100% (подробнее в разделе “Товары”)

NDS_MIXED

Товары в отделе имеют смешанные НДС

Пример запроса
Content-Type: application/json
{
  "name": "Хлебобулочные изделия",
  "tax": "NDS_0 .. NDS_100"
}
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Удаление отдела

DELETEhttps://kabinet.dreamkas.by/api/departments/{id}

Удаление отдела не влечёт за собой удаление товаров внутри, они будут перенесены в отдел “Без отдела”

Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Отделы V2

Предоставляет методы для управления отделами пользователя.

Основное предназначение отделов - логическая группировка товаров в Кабинете

/v2/departments

Список отделов

GEThttps://kabinet.dreamkas.by/api/v2/departments
Пример ответа 200 OK
Content-Type: application/json
[
  {
    "name": "",
    "tax": "NDS_0 .. NDS_100",
    "id": 0
  }
]
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Создание отдела

POSThttps://kabinet.dreamkas.by/api/v2/departments
Параметры тела запроса
Параметр Тип Описание
name string

Название отдела

tax enum

Налог

Принимает одно из значений
Значение Описание
NDS_0 .. NDS_100

НДС 0% - 100% (подробнее в разделе “Товары”)

NDS_MIXED

Товары в отделе имеют смешанные НДС

Параметры тела ответа
Параметр Тип Описание
name string

Название отдела

tax enum

Налог

Принимает одно из значений
Значение Описание
NDS_0 .. NDS_100

НДС 0% - 100% (подробнее в разделе “Товары”)

NDS_MIXED

Товары в отделе имеют смешанные НДС

id number

Идентификатор отдела

Пример запроса
Content-Type: application/json
{
  "name": "",
  "tax": "NDS_0 .. NDS_100"
}
Пример ответа 201 Created
Content-Type: application/json
{
  "name": "",
  "tax": "NDS_0 .. NDS_100",
  "id": 0
}

/v2/departments/{id}

Параметры строки запроса
Параметр Тип Обяз. Описание
id number Да Идентификатор отдела

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

GEThttps://kabinet.dreamkas.by/api/v2/departments/{id}
Параметры тела ответа
Параметр Тип Описание
name string

Название отдела

tax enum

Налог

Принимает одно из значений
Значение Описание
NDS_0 .. NDS_100

НДС 0% - 100% (подробнее в разделе “Товары”)

NDS_MIXED

Товары в отделе имеют смешанные НДС

id number

Идентификатор отдела

Пример ответа 200 OK
Content-Type: application/json
{
  "name": "",
  "tax": "NDS_0 .. NDS_100",
  "id": 0
}

Редактирование отдела

PATCHhttps://kabinet.dreamkas.by/api/v2/departments/{id}
Параметры тела запроса
Параметр Тип Описание
name string

Название отдела

tax enum

Налог

Принимает одно из значений
Значение Описание
NDS_0 .. NDS_100

НДС 0% - 100% (подробнее в разделе “Товары”)

NDS_MIXED

Товары в отделе имеют смешанные НДС

Пример запроса
Content-Type: application/json
{
  "name": "",
  "tax": "NDS_0 .. NDS_100"
}
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Удаление отдела

DELETEhttps://kabinet.dreamkas.by/api/v2/departments/{id}

Удаление отдела не влечёт за собой удаление товаров внутри, они будут перенесены в отдел “Без отдела”

Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Чеки

Набор методов для работы с чеками.

/receipts

Данные о продажах

GEThttps://kabinet.dreamkas.by/api/receipts{?from,to,limit,offset,devices}
Параметры строки запроса
Параметр Тип Обяз. Описание
from string Нет Дата в ISO формате. По умолчанию 00:00:00 текущего дня
to string Нет Дата в ISO формате. По умолчанию 23:59:59 текущего дня
offset number Нет Смещение
limit number Нет Количество. Максимальное значение 1000
devices string Нет список идентификаторов устройств
Параметры тела ответа
Параметр Тип Описание
query object

Фактические значения, с которыми был выполнен запрос

Параметр Тип Описание
from string

Дата начала

Пример: 2017-10-13T14:15:01.239Z
to string

Дата окончания

Пример: 2017-10-14T14:15:01.239Z
limit number

Количество

offset number

Смещение

devices string

Список идентификаторов устройств

Пример: ["1"]
data array

Данные о продажах

Параметр Тип Описание
id number

Идентификатор чека

type enum

Тип чека (Продажа или Возврат)

Принимает одно из значений
Значение Описание
SALE

Приход

REFUND

Возврат прихода

SALE_ANNUL

Аннулирование продажи

amount number

Сумма чека

discount number

Сумма скидок (уже учтена в amount, т.е. клиент заплатил столько, сколько указано amount)

deviceId number

Идентификатор устройства, кассы

shopId number

Идентификатор магазина

operationId string

Идентификатор операции, если чек был пробит через интернет-магазин

shiftId number

Номер смены, уникален в рамках кассы

number number

Номер чека в смене

localDate string

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

date string

Время пробития чека (в ISO)

payments array

Детальная информация об оплате

Параметр Тип Описание
type enum

Тип оплаты

Принимает одно из значений
Значение Описание
CASH

CASHLESS

amount number

Сумма, которая была оплачена этим типом

positions array

Позиции в чеке

Параметр Тип Описание
id string

Идентификатор товара

name string

Кешированное название товара

type enum

Тип товара - Алкогольный, Штучный, Весовой = [‘ALCOHOL’, ‘COUNTABLE’, ‘SCALABLE’]

Принимает одно из значений
Значение Описание
COUNTABLE

SCALABLE

ALCOHOL

COUNTABLE

quantity number

Количество проданного товара в тысячных

price number

Стоимость единицы товара (сумма позиции = price * quantity)

discount number

Величина скидки (суммарная по позиции, а не по единице товара)

barcode string

Штрихкод, отсканированный на момент продажи

exciseBarcode string

bottleBarcode (PDF417), отсканированный в момент продажи бутылки

vendorCode string

Артикул, по которому нашли товар и продали

tax enum

Тип НДС на момент проджаи

Принимает одно из значений
Значение Описание
NDS_0 .. NDS_100

НДС 0% - 100% (подробнее в разделе “Товары”)

NDS_18

departmentId number

Идентификатор отдела, в котором был товар в Кабинете на момент продажи. null для товаров в “Без отдела”

cashier object

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

Параметр Тип Описание
tabNumber number

Табельный номер, уникален в рамках кассы

Пример: 88990
name string

Имя

Пример: Иванов Петр Олегович
inn string

ИНН

Пример: 1234567890
checkURL string

Сайт проверки чека

Пример: www.nalog.ru
fiscalDocumentNumber string

Фискальный номер документа

Пример: 200
fiscalDocumentSign string

Фискальный признак документа

Пример: 2147483647
fnNumber string

Номер фискального накопителя

Пример: 9999078900001712
registryNumber string

Регистрационный номер ККТ

Пример: 0000000001056589
Пример ответа 200 OK
Content-Type: application/json
{
  "query": {
    "from": "2017-10-13T14:15:01.239Z",
    "to": "2017-10-14T14:15:01.239Z",
    "limit": 0,
    "offset": 0,
    "devices": "[\"1\"]"
  },
  "data": [
    {
      "id": 0,
      "type": "SALE",
      "amount": 0,
      "discount": 0,
      "deviceId": 0,
      "shopId": 0,
      "operationId": "",
      "shiftId": 0,
      "number": 0,
      "localDate": "",
      "date": "",
      "payments": [
        {
          "type": "CASH",
          "amount": 0
        }
      ],
      "positions": [
        {
          "id": "",
          "name": "",
          "type": "COUNTABLE",
          "quantity": 0,
          "price": 0,
          "discount": 0,
          "barcode": "",
          "exciseBarcode": "",
          "vendorCode": "",
          "tax": "NDS_18",
          "departmentId": 0
        }
      ],
      "cashier": {
        "tabNumber": 88990,
        "name": "Иванов Петр Олегович",
        "inn": "1234567890"
      },
      "checkURL": "www.nalog.ru",
      "fiscalDocumentNumber": "200",
      "fiscalDocumentSign": "2147483647",
      "fnNumber": "9999078900001712",
      "registryNumber": "0000000001056589"
    }
  ]
}

Внесения/Изъятия

Возвращает информацию о внесениях и изъятиях за определенный интервал времени

/encashments{?from,to,limit,offset,devices}

Данные о внесениях и изъятиях

GEThttps://kabinet.dreamkas.by/api/encashments{?from,to,limit,offset,devices}
Параметры строки запроса
Параметр Тип Обяз. Описание
from string Нет Дата в ISO формате. По умолчанию 00:00:00 текущего дня
to string Нет Дата в ISO формате. По умолчанию 23:59:59 текущего дня
offset number Нет Смещение
limit number Нет Количество. Максимальное значение 1000
devices string Нет список идентификаторов устройств
Параметры тела ответа
Параметр Тип Описание
query object

Фактические значения, с которыми был выполнен запрос

Параметр Тип Описание
from string

Дата начала

Пример: 2017-10-13T14:15:01.239Z
to string

Дата окончания

Пример: 2017-10-14T14:15:01.239Z
limit number

Количество

offset number

Смещение

devices string

Список идентификаторов устройств

Пример: ["1"]
data array

Данные об изъятиях и внесениях

Параметр Тип Описание
deviceId number

Идентификатор устройства,

shopId number

Идентификатор магазина,

type enum

Тип операции,

Принимает одно из значений
Значение Описание
MONEY_IN

Операция внесения

MONEY_OUT

Операция изъятия

shiftId number

Номер смены, уникален в рамках одной кассы,

cashier object

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

Параметр Тип Описание
tabNumber number

Табельный номер, уникален в рамках кассы

Пример: 88990
name string

Имя

Пример: Иванов Петр Олегович
inn string

ИНН

Пример: 1234567890
sum number

Сумма операции, в абсолютном значении,

localDate string

Локальное время кассы во время операции внесения/изъятия

date string

Время в формате ISO

Пример ответа 200 OK
Content-Type: application/json
{
  "query": {
    "from": "2017-10-13T14:15:01.239Z",
    "to": "2017-10-14T14:15:01.239Z",
    "limit": 0,
    "offset": 0,
    "devices": "[\"1\"]"
  },
  "data": [
    {
      "deviceId": 0,
      "shopId": 0,
      "type": "MONEY_IN",
      "shiftId": 0,
      "cashier": {
        "tabNumber": 88990,
        "name": "Иванов Петр Олегович",
        "inn": "1234567890"
      },
      "sum": 0,
      "localDate": "",
      "date": ""
    }
  ]
}

Кассиры

Возвращает список кассиров

/cashiers{?devices}

Данные о кассирах

GEThttps://kabinet.dreamkas.by/api/cashiers{?devices}
Параметры строки запроса
Параметр Тип Обяз. Описание
devices string Нет список идентификаторов устройств
Параметры тела ответа
Параметр Тип Описание
tabNumber number

Табельный номер, уникален в рамках кассы

Пример: 88990
name string

Имя

Пример: Иванов Петр Олегович
inn string

ИНН

Пример: 1234567890
deviceId number

Идентификатор устройства, за которым работал кассир

Пример ответа 200 OK
Content-Type: application/json
{
  "tabNumber": 88990,
  "name": "Иванов Петр Олегович",
  "inn": "1234567890",
  "deviceId": 0
}

Смены

Возвращает список смен

/shifts{?from,to,devices,is_closed,limit,offset}

Список смен

GEThttps://kabinet.dreamkas.by/api/shifts{?from,to,devices,is_closed,limit,offset}

Возвращает список смен.

Параметры строки запроса
Параметр Тип Обяз. Описание
from string Нет Дата "от" (в ISO формате), открытие смены, не localDate, а UTC
to string Нет Дата "до" (в ISO формате), открытие смены, не localDate, a UTC
offset number Нет Смещение.
limit number Нет Количество. (макс. - 1000, по умолчанию - 100).
devices string Нет Список идентификаторов устройств (если нужно выбрать смены для конкретных устройств).
is_closed boolean Нет Если передать истинное значение (например: yes, y, true, 1), то будут показаны только закрытые смены. Если требуется отобразить только открытые смены, то следует передать ложное значение (no, n, false, 0). Если параметр не передан, то будут возвращены все смены (закрытые и открытые)
Пример ответа 200 OK
Content-Type: application/json
[
  {
    "id": "5949581a02c08a286420c6c7",
    "shiftId": 1,
    "deviceId": 1,
    "openedAt": "2017-06-20 12:01:47.990Z",
    "openedAtUTC": "2017-06-20 11:01:47.990Z",
    "closedAt": "2017-06-20 17:04:22.456Z",
    "closedAtUTC": "2017-06-20 16:04:22.456Z",
    "cashOnOpen": 24445,
    "cashOnClose": 44425,
    "isClosed": true,
    "cashier": {
      "tabNumber": 88990,
      "name": "Иванов Петр Олегович",
      "inn": "1234567890"
    }
  }
]

Операции

Набор методов для получения информации о статусе выполнения заданий.

Некоторые методы API (например, фискализация чека) возвращают HTTP-статус 202 Accepted, это означает, что запрос был принят в обработку, но его выполнение может занять некоторое время. В ответ на такие запросы в теле приходит идентификатор операции, по которому потом можно получить результат выполнения операции.

/operations

Список последних операций

GEThttps://kabinet.dreamkas.by/api/operations
Пример ответа 200 OK
Content-Type: application/json
[
  {
    "id": "5956889136fdd7733f19cfe6",
    "createdAt": "2017-06-20 12:01:47.990Z",
    "status": "ERROR",
    "completedAt": "2017-06-20 12:03:12.440Z",
    "data": {
      "error": {
        "code": "NeedUpdateCash",
        "message": "Требуется обновление кассы"
      }
    }
  }
]

/operations/{id}

Параметры строки запроса
Параметр Тип Обяз. Описание
id number Да Идентификатор операции

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

GEThttps://kabinet.dreamkas.by/api/operations/{id}
Параметры тела ответа
Параметр Тип Описание
id string

Идентификатор операции (см. API Операции)

Пример: 5956889136fdd7733f19cfe6
createdAt string

Дата формирования

Пример: 2017-06-20 12:01:47.990Z
status enum

Статус операции

Принимает одно из значений
Значение Описание
PENDING

В обработке

IN_PROGRESS

Задача принята в обработку (например, устройство приняло чек на фискализацию)

SUCCESS

Завершено успешно

ERROR

Завершено с ошибкой

ERROR

completedAt string

Дата завершения

Пример: 2017-06-20 12:03:12.440Z
data object

Дополнительные данные

Параметр Тип Описание
error object

Ошибка (если операция завершилась с ошибкой)

Параметр Тип Описание
code string

Код ошибки

Пример: NeedUpdateCash
message string

Сообщение об ошибки

Пример: Требуется обновление кассы
Пример ответа 200 OK
Content-Type: application/json
{
  "id": "5956889136fdd7733f19cfe6",
  "createdAt": "2017-06-20 12:01:47.990Z",
  "status": "ERROR",
  "completedAt": "2017-06-20 12:03:12.440Z",
  "data": {
    "error": {
      "code": "NeedUpdateCash",
      "message": "Требуется обновление кассы"
    }
  }
}

Вебхуки

Предоставляет методы для управления вебхуками.

HTTP-статус ответа на вебхук должен быть в диапазоне 200-299. Если ваш сервер ответит другим кодом, то вебхук не будет считаться успешно выполненным и спустя некоторое время будет произведена повторная попытка его выполнения.

При ошибке выполнения вебхука, спустя некоторое время будут предприниматься дополнительные попытки через разные интервалы времени. На текущий момент это: - сразу

  • через 5 сек

  • через 1 минуту

  • через 1 час

  • через 3 часа

  • через 24 часа

/webhooks

Список вебхуков

GEThttps://kabinet.dreamkas.by/api/webhooks
Пример ответа 200 OK
Content-Type: application/json
[
  {
    "url": "",
    "types": {
      "products": false,
      "devices": false,
      "encashments": false,
      "receipts": false,
      "shifts": false,
      "operations": false,
      "deviceRegistrations": false
    },
    "id": ""
  }
]

Создание вебхука

POSThttps://kabinet.dreamkas.by/api/webhooks
Параметры тела запроса
Параметр Тип Описание
url string

Ссылка, куда Кабинет отправит запрос

types object

Типы объектов, на которых можно подписаться

Параметр Тип Описание
products boolean

Товары. Создание, изменение и удаление

Пример: true
devices boolean

Устройства, в частности кассы

Пример: true
encashments boolean

Внесения и изъятия из кассы

Пример: true
receipts boolean

Чеки, как пробитые из кассы кассиром, так и чеки из интернет-магазина

Пример: true
shifts boolean

Новые смены, закрытие смены

Пример: true
operations boolean

Операции, в частности чеки из интернет-магазинов

Пример: true
deviceRegistrations boolean

Изменения регистрационных данных ККТ

Пример: true
isActive boolean

Состояние вебхука. Если не активен - не будет вызываться

Пример: true
Пример запроса
Content-Type: application/json
{
  "url": "",
  "types": {
    "products": false,
    "devices": false,
    "encashments": false,
    "receipts": false,
    "shifts": false,
    "operations": false,
    "deviceRegistrations": false
  }
}
Пример ответа 201 Created
Content-Type: application/json
{
    "id": "b0381fe4-4428-4dcb-8169-c8bbcab59626"
}

/webhooks/{id}

Параметры строки запроса
Параметр Тип Обяз. Описание
id string Да Идентификатор вебхука, UUIDv4

Информация о вебхуке

GEThttps://kabinet.dreamkas.by/api/webhooks/{id}
Параметры тела ответа
Параметр Тип Описание
url string

Ссылка, куда Кабинет отправит запрос

types object

Типы объектов, на которых можно подписаться

Параметр Тип Описание
products boolean

Товары. Создание, изменение и удаление

Пример: true
devices boolean

Устройства, в частности кассы

Пример: true
encashments boolean

Внесения и изъятия из кассы

Пример: true
receipts boolean

Чеки, как пробитые из кассы кассиром, так и чеки из интернет-магазина

Пример: true
shifts boolean

Новые смены, закрытие смены

Пример: true
operations boolean

Операции, в частности чеки из интернет-магазинов

Пример: true
deviceRegistrations boolean

Изменения регистрационных данных ККТ

Пример: true
isActive boolean

Состояние вебхука. Если не активен - не будет вызываться

Пример: true
id string

Идентификатор вебхука, UUIDv4

Пример ответа 200 OK
Content-Type: application/json
{
  "url": "",
  "types": {
    "products": false,
    "devices": false,
    "encashments": false,
    "receipts": false,
    "shifts": false,
    "operations": false,
    "deviceRegistrations": false
  },
  "id": ""
}

Редактирование вебхука

PATCHhttps://kabinet.dreamkas.by/api/webhooks/{id}
Параметры тела запроса
Параметр Тип Описание
url string

Ссылка, куда Кабинет отправит запрос

types object

Типы объектов, на которых можно подписаться

Параметр Тип Описание
products boolean

Товары. Создание, изменение и удаление

Пример: true
devices boolean

Устройства, в частности кассы

Пример: true
encashments boolean

Внесения и изъятия из кассы

Пример: true
receipts boolean

Чеки, как пробитые из кассы кассиром, так и чеки из интернет-магазина

Пример: true
shifts boolean

Новые смены, закрытие смены

Пример: true
operations boolean

Операции, в частности чеки из интернет-магазинов

Пример: true
deviceRegistrations boolean

Изменения регистрационных данных ККТ

Пример: true
isActive boolean

Состояние вебхука. Если не активен - не будет вызываться

Пример: true
Пример запроса
Content-Type: application/json
{
  "url": "",
  "types": {
    "products": false,
    "devices": false,
    "encashments": false,
    "receipts": false,
    "shifts": false,
    "operations": false,
    "deviceRegistrations": false
  }
}
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Удаление вебхука

DELETEhttps://kabinet.dreamkas.by/api/webhooks/{id}
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Пример выполнения вебхука

Пример тела вебхука

POSThttps://kabinet.dreamkas.by/api/#
Параметры тела запроса
Параметр Тип Описание
action enum

Тип действия

Принимает одно из значений
Значение Описание
CREATE

Создание сущности

UPDATE

Изменение сущности

DELETE

Удаление сущности

type enum

Тип сущности

Принимает одно из значений
Значение Описание
PRODUCT

Товар

DEVICE

Устройство, в частности касса. Может быть подключен, изменен или отключен

ENCASHMENT

Внесение(изъятие) денег в/с кассу

SHIFT

Открытие, закрытие смены

RECEIPT

Чеки, пробитые кассой “оффлайн” и из внешних источников(интернет-магазины, …)(успешно зафискализированные)

OPERATION

Операции. В том числе созданные при фискализации. В отличие от чеков, операции несут полную информацию о фискализации, например об ошибках

data object

Объект измененной сущности. Содержит поля сущности, как описано это в документации выше. В случае удаления - приходит с ключом id

Параметр Тип Описание
id string

UUID товара (если не передан, UUID будет сгенерирован автоматически).

Указывать UUID можно только при создании товара. Изменить идентификатор товара после создания нельзя.

Пример: b0381fe4-4428-4dcb-8169-c8bbcab59626
name string

Название

По умолчанию: Новый товар
type enum

Тип продукта

Принимает одно из значений
Значение Описание
COUNTABLE

Штучный

SCALABLE

Весовой

ALCOHOL

Алкогольный

CLOTHES

Одежда

SHOES

Обувь

SERVICES

Услуги

departmentId number

ID отдела магазина

quantity number

Единица товара

Пример: 1000
prices array

Цена для каждого устройства

Параметр Тип Описание
deviceId number

ID устройства

Пример: 1
value number

Цена в копейках

Пример: 1200
price number

Цена товара для новых устройств (если не указать, будет взято максимальное значение из prices)

meta object

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

Параметр Тип Описание
barcodes array

Штрихкоды. Только длины 8, 12 или 13. Проверяется на контрольную сумму

Пример: ["12341238"]
vendorCodes array

Артикулы, никаких валидаций

Пример: ["AB_1234"]
tax enum

Налог

Принимает одно из значений
Значение Описание
NDS_0 .. NDS_100

НДС 0% - 100% (подробнее в разделе “Товары”)

createdAt string

Дата создания

Пример: 2017-05-05T14:15:01.239Z
updatedAt string

Дата последнего изменения

Пример: 2017-05-05T14:15:01.239Z
Пример запроса
Content-Type: application/json
{
  "action": "CREATE",
  "type": "PRODUCT",
  "data": {
    "id": "b0381fe4-4428-4dcb-8169-c8bbcab59626",
    "name": "Новый товар",
    "type": "COUNTABLE",
    "departmentId": 0,
    "quantity": 1000,
    "prices": [
      {
        "deviceId": 1,
        "value": 1200
      }
    ],
    "meta": {},
    "barcodes": [
      "12341238"
    ],
    "vendorCodes": [
      "AB_1234"
    ],
    "tax": "NDS_0 .. NDS_100",
    "createdAt": "2017-05-05T14:15:01.239Z",
    "updatedAt": "2017-05-05T14:15:01.239Z"
  }
}
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Пользователи

Для создания пользователей требуется Application авторизация. Пользователи, создаваемые приложениями - это полноценные аккаунты Кабинета, но с небольшими отличиями: - подтверждение аккаунта в Кабинете не требуется (аккаунт уже активирован)

  • при создании аккаунта, пользователь не получит приветственных писем о регистрации

  • для аккаунта пароль генерируется автоматически, приложение не может его указать/изменить

  • для пользователя автоматически генерируется Bearer токен, которым может пользоваться приложение, для выполнения запросов от имени этого аккаунта

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

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

/users

Создание пользователя

POSThttps://kabinet.dreamkas.by/api/users
Параметры тела запроса
Параметр Тип Описание
name string

Имя пользователя

Пример: Василий
email string

E-mail пользователя

Пример: mail@example.com
Параметры тела ответа
Параметр Тип Описание
userId number

Идентификатор пользователя

Пример: 58835
accessToken string

Токен доступа (Bearer) пользователя, сгенерированный для приложения, которое выполнило запрос

Пример: 523cbe0f-99da-4f31-91b7-3f9754aeb04b
Пример запроса
Content-Type: application/json
{
  "name": "Василий",
  "email": "mail@example.com"
}
Пример ответа 201 Created
Content-Type: application/json
{
  "userId": 58835,
  "accessToken": "523cbe0f-99da-4f31-91b7-3f9754aeb04b"
}

Профиль

Набор методов для получения информации об аккаунте пользователя

/user/pin

Получение кода для привязки кассы

GEThttps://kabinet.dreamkas.by/api/user/pin
Параметры тела ответа
Параметр Тип Описание
code number

Пятизначный код привязки, который нужно ввести на устройстве

Пример: 42638
ttl number

Оставшееся время жизни кода в секундах

Пример: 1773
Пример ответа 200 OK
Content-Type: application/json
{
  "code": 42638,
  "ttl": 1773
}

Скидки

Методы для управления скидками

/discounts

Получение списка скидок

GEThttps://kabinet.dreamkas.by/api/discounts
Пример ответа 200 OK
Content-Type: application/json
[
  {
    "name": "Скидка на все товары 5%",
    "mode": "AUTO",
    "result": {
      "type": "PERCENT",
      "value": 0
    },
    "isActive": true,
    "targets": {
      "products": [
        {
          "id": "",
          "barcodes": []
        }
      ],
      "devices": [],
      "allDevices": false,
      "allProducts": false
    },
    "conditions": [
      {
        "type": "CARD_RANGE",
        "data": {
          "couponIds": []
        }
      }
    ],
    "id": 123
  }
]

Создание скидки

POSThttps://kabinet.dreamkas.by/api/discounts
Параметры тела запроса
Параметр Тип Описание
name string

Название скидки

Пример: Скидка на все товары 5%
mode enum

Режим скидки

Принимает одно из значений
Значение Описание
AUTO

Автоматичексий режим

MANUAL

ручной режим

result object

Результат скидки

Параметр Тип Описание
type enum

Тип скидки

Принимает одно из значений
Значение Описание
PERCENT

Процентная скидка

SUM

Фиксированная скидка

value number

Величина скидки. Измеряется в копейках и в сотых долях процента соответственно

isActive boolean

Статус активности скидки

Пример: true
targets object

на что действует скидка

Параметр Тип Описание
products array

Список товаров, на которых действует скидка. Если пустой, то скидка ни на что не будет действовать

Параметр Тип Описание
id string

Идентификатор товара, UUIDv4

name string

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

barcodes array

Штрихкоды

devices array

Список идентификаторов устройств, на которых будет задействована скидка

allDevices boolean

Применить скидку на всех устройствах. Также, значение true позволяет применять скидку для новых(привязанных) касс автоматически. Значение true имеет приоритет над devices

Пример: trueПо умолчанию: false
allProducts boolean

Применить скидку для всех товаров. Также, значение true позволяет применять скидку для новых(созданных) товаров автоматически. Значение true имеет приоритет над products

Пример: trueПо умолчанию: false
conditions array

Массив условий

Параметры тела ответа
Параметр Тип Описание
id number

Идентификатор созданной скидки

Пример: 123
Пример запроса
Content-Type: application/json
{
  "name": "Скидка на все товары 5%",
  "mode": "AUTO",
  "result": {
    "type": "PERCENT",
    "value": 0
  },
  "isActive": true,
  "targets": {
    "products": [
      {
        "id": "",
        "barcodes": []
      }
    ],
    "devices": [],
    "allDevices": false,
    "allProducts": false
  },
  "conditions": [
    {
      "type": "CARD_RANGE",
      "data": {
        "couponIds": []
      }
    }
  ]
}
Пример ответа 200 OK
Content-Type: application/json
{
  "id": 123
}

/discounts/{id}

Параметры строки запроса
Параметр Тип Обяз. Описание
id number Да Идентификатор скидки

Получение данных скидки

GEThttps://kabinet.dreamkas.by/api/discounts/{id}
Параметры тела ответа
Параметр Тип Описание
name string

Название скидки

Пример: Скидка на все товары 5%
mode enum

Режим скидки

Принимает одно из значений
Значение Описание
AUTO

Автоматичексий режим

MANUAL

ручной режим

result object

Результат скидки

Параметр Тип Описание
type enum

Тип скидки

Принимает одно из значений
Значение Описание
PERCENT

Процентная скидка

SUM

Фиксированная скидка

value number

Величина скидки. Измеряется в копейках и в сотых долях процента соответственно

isActive boolean

Статус активности скидки

Пример: true
targets object

на что действует скидка

Параметр Тип Описание
products array

Список товаров, на которых действует скидка. Если пустой, то скидка ни на что не будет действовать

Параметр Тип Описание
id string

Идентификатор товара, UUIDv4

name string

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

barcodes array

Штрихкоды

devices array

Список идентификаторов устройств, на которых будет задействована скидка

allDevices boolean

Применить скидку на всех устройствах. Также, значение true позволяет применять скидку для новых(привязанных) касс автоматически. Значение true имеет приоритет над devices

Пример: trueПо умолчанию: false
allProducts boolean

Применить скидку для всех товаров. Также, значение true позволяет применять скидку для новых(созданных) товаров автоматически. Значение true имеет приоритет над products

Пример: trueПо умолчанию: false
conditions array

Массив условий

id number

Идентификатор скидки

Пример: 123
Пример ответа 200 OK
Content-Type: application/json
{
  "name": "Скидка на все товары 5%",
  "mode": "AUTO",
  "result": {
    "type": "PERCENT",
    "value": 0
  },
  "isActive": true,
  "targets": {
    "products": [
      {
        "id": "",
        "barcodes": []
      }
    ],
    "devices": [],
    "allDevices": false,
    "allProducts": false
  },
  "conditions": [
    {
      "type": "CARD_RANGE",
      "data": {
        "couponIds": []
      }
    }
  ],
  "id": 123
}

Обновление скидки

PATCHhttps://kabinet.dreamkas.by/api/discounts/{id}
Пример запроса
Content-Type: application/json
{
  "name": "Скидка на все товары 5%",
  "mode": "AUTO",
  "result": {
    "type": "PERCENT",
    "value": 0
  },
  "isActive": true,
  "targets": {
    "products": [
      {
        "id": "",
        "barcodes": []
      }
    ],
    "devices": [],
    "allDevices": false,
    "allProducts": false
  },
  "conditions": [
    {
      "type": "CARD_RANGE",
      "data": {
        "couponIds": []
      }
    }
  ]
}
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Удаление скидки

DELETEhttps://kabinet.dreamkas.by/api/discounts/{id}
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.

Клиенты

Методы для управления клиентами

/clients

Список клиентов

GEThttps://kabinet.dreamkas.by/api/clients
Пример ответа 200 OK
Content-Type: application/json
[
  {
    "id": "276421f5-0a84-4c2c-a84d-96eb8b57dd55",
    "phone": "79441118833",
    "email": "user@example.com",
    "name": "Павел",
    "createdAt": "2017-11-14",
    "avatar": "https://kabinet-static.dreamkas.by/assets/avatars/24.svg",
    "seed": 84736438
  }
]

Создание клиента

POSThttps://kabinet.dreamkas.by/api/clients
Параметры тела запроса
Параметр Тип Описание
id string

Идентификатор клиента в формате UUID (любой версии). Если не передан, будет сгенерирован автоматически.

Пример: 276421f5-0a84-4c2c-a84d-96eb8b57dd55
phone string

Номер телефона

Пример: 79441118833
email string

Адрес электронной почты

Пример: user@example.com
name string

Имя

Пример: Павел
Параметры тела ответа
Параметр Тип Описание
id string

Идентификатор клиента в формате UUID (любой версии). Если не передан, будет сгенерирован автоматически.

Пример: 276421f5-0a84-4c2c-a84d-96eb8b57dd55
phone string

Номер телефона

Пример: 79441118833
email string

Адрес электронной почты

Пример: user@example.com
name string

Имя

Пример: Павел
createdAt string

Дата создания клиента в формате ГГГГ-ММ-ДД

Пример: 2017-11-14
avatar string

Ссылка на аватар

Пример: https://kabinet-static.dreamkas.by/assets/avatars/24.svg
seed number

Случайное число для выбора аватара (ID аватара = seed % 24). Можно явно выставить значение в диапазоне [0;23], чтобы явно выбрать аватар для клиента.

Пример: 84736438
Пример запроса
Content-Type: application/json
{
  "id": "276421f5-0a84-4c2c-a84d-96eb8b57dd55",
  "phone": "79441118833",
  "email": "user@example.com",
  "name": "Павел"
}
Пример ответа 200 OK
Content-Type: application/json
{
  "id": "276421f5-0a84-4c2c-a84d-96eb8b57dd55",
  "phone": "79441118833",
  "email": "user@example.com",
  "name": "Павел",
  "createdAt": "2017-11-14",
  "avatar": "https://kabinet-static.dreamkas.by/assets/avatars/24.svg",
  "seed": 84736438
}

/clients/{id}

Параметры строки запроса
Параметр Тип Обяз. Описание
id number Да Идентификатор клиента

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

GEThttps://kabinet.dreamkas.by/api/clients/{id}
Параметры тела ответа
Параметр Тип Описание
id string

Идентификатор клиента в формате UUID (любой версии). Если не передан, будет сгенерирован автоматически.

Пример: 276421f5-0a84-4c2c-a84d-96eb8b57dd55
phone string

Номер телефона

Пример: 79441118833
email string

Адрес электронной почты

Пример: user@example.com
name string

Имя

Пример: Павел
createdAt string

Дата создания клиента в формате ГГГГ-ММ-ДД

Пример: 2017-11-14
avatar string

Ссылка на аватар

Пример: https://kabinet-static.dreamkas.by/assets/avatars/24.svg
seed number

Случайное число для выбора аватара (ID аватара = seed % 24). Можно явно выставить значение в диапазоне [0;23], чтобы явно выбрать аватар для клиента.

Пример: 84736438
Пример ответа 200 OK
Content-Type: application/json
{
  "id": "276421f5-0a84-4c2c-a84d-96eb8b57dd55",
  "phone": "79441118833",
  "email": "user@example.com",
  "name": "Павел",
  "createdAt": "2017-11-14",
  "avatar": "https://kabinet-static.dreamkas.by/assets/avatars/24.svg",
  "seed": 84736438
}

Обновление клиента

PATCHhttps://kabinet.dreamkas.by/api/clients/{id}
Параметры тела ответа
Параметр Тип Описание
id string

Идентификатор клиента в формате UUID (любой версии). Если не передан, будет сгенерирован автоматически.

Пример: 276421f5-0a84-4c2c-a84d-96eb8b57dd55
phone string

Номер телефона

Пример: 79441118833
email string

Адрес электронной почты

Пример: user@example.com
name string

Имя

Пример: Павел
createdAt string

Дата создания клиента в формате ГГГГ-ММ-ДД

Пример: 2017-11-14
avatar string

Ссылка на аватар

Пример: https://kabinet-static.dreamkas.by/assets/avatars/24.svg
seed number

Случайное число для выбора аватара (ID аватара = seed % 24). Можно явно выставить значение в диапазоне [0;23], чтобы явно выбрать аватар для клиента.

Пример: 84736438
Пример запроса
Content-Type: application/json
{
  "id": "276421f5-0a84-4c2c-a84d-96eb8b57dd55",
  "phone": "79441118833",
  "email": "user@example.com",
  "name": "Павел"
}
Пример ответа 200 OK

Удаление клиента

DELETEhttps://kabinet.dreamkas.by/api/clients/{id}
Пример ответа 204 No Content
Ответ с таким статусом не содержит тела, но означает, что запрос выполнено успешно.