Skip to content

Описание протокола JSON API для обмена данными с Nextmarket

В Nextmarket есть программный интерфейс (JSON API) для возможности получения информации путем http-запросов. Например, это может использоваться для интеграции с другими учетными системами.

На текущий момент API работает только в режиме read-only (только чтение) и не предполагает внесение каких-то изменений в базу данных.

Настройка API

Активация API

Для работы с API необходимо выполнить его активацию и настройку.

  • с главной формы откройте Файл - Настройки
  • перейдите на вкладку "Интеграции"
  • включите опцию Активировать API

Кассовая программа Nextmarket. Опция для включения API

Настройки подключения

При необходимости вы можете настроить дополнительные параметры:

  • порт - порт, по которому программа будет прослушивать запросы
  • логин - имя пользователя для авторизации при выполнении запросов
  • пароль - пароль для авторизации

После завершения настройки сохраните изменения. Чтобы API начал работать, обязательно перезапустите Nextmarket

!!! warning "Важно" Обратите внимание, что если программа запущена с правами обычного пользователя Windows, то запросы могут быть прослушаны только с localhost. Для доступна к API из вне необходимо запустить программу от имени администратора Windows или настроить проксирование, например, средствами nginx

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

Чтобы проверить, что API работает, можно открыть в браузере следующий url: http://localhost:8419/api/v1/status, а затем ввести логин и пароль, указанные в настройках.

Кассовая программа Nextmarket. Проверка работы API

Если все сделано верно, то после авторизации вы увидите страницу с кодом ответа:

{
  "Status": "Ok",
  "ResponseTime": 0,
  "Data": {
    "Type": "StatusInfo",
    "GbsId": "3CA3126FAAD94144947085D8A0145B10",
    "LicenseExpiration": "2024-07-17T00:00:00",
    "AppVersion": "6.6.0.2465"
  }
}

Работа с API

Основная информация

Базовый URL: http://localhost:8419/api/v1 Формат ответов: 

{
  "Status": "Ok", //статус ответа
  "ResponseTime": 0, //время ответа, мс
  "TotalPages": 77, //кол-во страниц с записями по запросу
  "TotalItems": 7677, //всего элементов по запросу
  "Data": { //json-объект или массив json-объектов 

  } 
}

Для авторизации необходимо передавать заголовки аутентификации. Авторизация базовая (basic)

Все запросы выполняются методом GET.

Кэширование

Для построения ответов используется кэширование, что может привести к задержке отображения информации. Для обновления кэша можно использовать соответствующий метод.

Обратите внимание, что загрузка кэша может занимать длительное время при большом объеме данных. Кэш обновляется автоматически обычно с периодичностью в 5-20 минут, поэтому нет необходимости перед каждым запросом обновлять кэш.

!!! warning "Важно" Документы кэшируются только за последние год. Для повышения производительности необходимо использовать небольшие периоды для запроса списка документов, т.к. на БД с большим количеством документов возможны большие задержки.

Пагинация

Разделение ответов на страницы

Запросы товаров, категорий товаров, документов поддерживают пагинацию через параметры запросов: - page - номер запрашиваемой страницы - page_size - размер страницы (кол-во записей на страницу), по умолчанию 100 записей на страницу

Пример запроса: http://localhost:8419/api/v1/documents?page=2&page_size=10 - записи будут поделены на страницы по 10 записей, в ответе будет содержимое страницы 2

Запросы

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

Метод: /status

Возвращает информацию:

  • GBS.ID
  • срок истечения лицензии
  • версия программы

Пример

Запрос: http://localhost:8419/api/v1/status

Ответ: 

{
  "Status": "Ok",
  "ResponseTime": 0,
  "Data": {
    "Type": "StatusInfo",
    "GbsId": "AD6E5736820C4B9A864A2A9417E9FE43", //ИД
    "LicenseExpiration": "2022-07-10T00:00:00", //срок окончания лицензии
    "AppVersion": "6.3.0.1745" //версия ПО
  }
}

Загрузка кэша

Метод: /load_caches

Обновляет кэш данных, используемых для предоставления ответов на запросы

Пример

Запрос: http://localhost:8419/api/v1/load_caches

Ответ:

{
  "Status": "Ok",
  "ResponseTime": 3683,
  "Data": {
    "Type": "Message",
    "Message": "Кэш данных успешно обновлен"
  }
}

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

Метод: /goods

Возвращает массив товаров из базы данных.

Доступны параметры:

  • uid - uid товара

Пример

Запрос: http://localhost:8419/api/v1/goods?page=2

Ответ:

{
  "Status": "Ok", //успешно
  "ResponseTime": 24, //время выполнения
  "TotalPages": 77, //всего страниц
  "TotalItems": 7677, //всего записей
  "Data": [ //массив json-объектов
    {
      "Type": "Good", //тип объекта - товар
      "IsDeleted": false, //удален - нет
      "Properties": [ //доп. поля, массив
        {
          "TypeUid": "24aaef1f-d733-47f1-ada7-ac3627cf4068", //uid-доп. поля
          "TypeName": "Код товара", //название доп. поля
          "Value": "56" //значение доп. поля
        }
      ],
      "Stocks": [ //остатки, массив
        {
          "Quantity": 0.0, //кол-во на остатке
          "Price": 875.0, //цена розничная
          "Storage": { //склад остатка
            "Uid": "2eff591c-93de-4409-b6c5-6d1fb54d3f70", //uid-склада
            "Name": "Основной" //название склада
          }
        },
        {
          "Quantity": 20.0,
          "Price": 950.0,
          "Storage": {
            "Uid": "2eff591c-93de-4409-b6c5-6d1fb54d3f70",
            "Name": "Основной"
          }
        }
      ],
      "Uid": "a4eb0bb3-9244-4549-9c9e-463261feb368", //uid товара
      "Barcode": "2013815156242", //штрихкод
      "Name": "Флеш накопитель 32 Гб \"Триколор ТВ\"", //название
      "Group": { //категория
        "Name": "Флешки", //название категории
        "Uid": "24d2ac23-468d-49c1-b73a-57005a41fada" //uid категории
      }
    },
    {
      "Type": "Good", //следующий товар
      "IsDeleted": true,
      "Properties": [

      ],
      "Stocks": [
        {
          "Quantity": 0.0,
          "Price": 190.0,
          "Storage": {
            "Uid": "2eff591c-93de-4409-b6c5-6d1fb54d3f70",
            "Name": "Основной"
          }
        }
      ],
      "Uid": "cfdf20b2-8197-41b0-83e0-8ea28ca9e39a",
      "Barcode": "4690241027964",
      "Name": "Battlefield: Битва за Нью-Йорк - игра (Новый диск)",
      "Group": {
        "Name": "Игры ",
        "Uid": "775c61d2-4399-4797-a86f-e13fcf396561"
      }
    }
  ]
}

Получение категорий (групп) товаров

Метод: /good_groups

Возвращает массив категорий товаров из базы данных.

Доступны параметры:

  • uid - uid категории

Пример

Запрос: http://localhost:8419/api/v1/good_groups

Ответ:

{
  "Status": "Ok", //статус
  "ResponseTime": 92, //время ответа
  "TotalPages": 1, //всего страниц 
  "TotalItems": 36, //всего элементов
  "Data": [ //массив категорий
    {
      "Name": "Для компьютеров", //название
      "Type": "GoodGroup", //категория товара объекта
      "IsDeleted": true, //удалена?
      "Uid": "260ecc3e-af14-444b-bdec-4ccaeb9fce9a" //uid
    },
    {
      "Name": "Шнуры, кабеля, з/у для телефонов",
      "Type": "GoodGroup",
      "IsDeleted": false,
      "Uid": "ee48135f-ddd9-43a5-a89f-e26744462e58"
    }
  ]
}

Получение документов

Метод: /documents

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

Доступны параметры:

  • date_start - начало периода (включительно)
  • date_end - конец периода (включительно)
  • type - тип документа (ВАЖНО: регистрозависимый параметр)

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

  • Sale - продажа
  • SaleReturn - возврат продажи
  • Buy - входящая накладная (поступление)

Типы оплат:

  • MoneyDocumentPayment - платеж деньгами по документу
  • BonusesDocumentPayment - платеж бонусами по документу
  • Prepaid - предоплата по документу (для заказов)
  • CheckDiscount - скидка по документу (используется для округления)

Пример 1

Запрос продаж за период с 01.07.2023 по 31.07.2023: http://localhost:8419/api/v1/documents?type=Sale&date_start=2023-07-01&date_end=2023-07-31

Пример 2

Запрос: http://localhost:8419/api/v1/documents

Ответ:

{
  "Status": "Ok", //успешно
  "ResponseTime": 24, //время ответа
  "TotalPages": 182, //всего страниц
  "TotalItems": 18119, //всего записей
  "Data": [ //массив объектов
    {
      "Type": "Document", //тип объекта - документ
      "ParentUid":"00000000-0000-0000-0000-000000000000", //uid родителя (для возвратов, например)
      "Uid": "a36c63fb-0654-4731-b205-6914272754c3", //uid-документа
      "IsDeleted": false, //удален?
      "DocumentType": "SaleReturn", //возврат продажи
      "DateTime": "2019-08-07T16:29:50.478", //дата, время
      "Items": [ //массив записей в документе
        {
          "Uid": "1306b3fa-aaa9-4013-a805-16ae024fbf20", //uid-записи
          "Good": { //товар
            "Uid": "f5a57fd1-9aef-40b2-a238-9374f1fb7185", //uid-товара
            "Barcode": "2067518736034", //штрихкод
            "Name": "Единый мульти ЛАЙТ 1 год", //название товара
            "Group": { //категория
              "Name": "Оплата Триколор", //название категории
              "Uid": "e1b32b53-5c2e-498f-8dc1-ec9ffd4be1be" //uid-категории
            }
          },
          "Quantity": 1.0, //кол-во
          "BuyPrice": 0.0, //закупочная цена (для накладных)
          "SalePrice": 1590.0, //розничная цена
          "Discount": 0.0 //скидка (для продажи)
        }
      ],
        "Payments": [ //массив платежей
        {
          "Uid": "191066a9-3f60-47c6-9352-6df63431eddd", //uid-платежа
          "DateTime": "2020-12-27T10:28:55.784", //дата-время платежа (может не совпадать с датой документа, т.к. оплата может быть совершена позже)
          "SumIn": 1590.0, //сумма, полученная по документу
          "SumOut": 0.0, //сумма, выплаченная по документу
          "Method": { //способ оплаты, может быть null
            "Uid": "ec3fa8ee-e3b3-46dc-a736-62c3932590bd", //uid-способа
            "Name": "Наличными" //название способа оплаты
          },
          "Type": "MoneyDocumentPayment" //тип оплаты
        }
      ]
    },
    {
      "Type": "Document",
      "Uid": "f116d8af-fb6f-428b-8b90-9acf3f50e5b1",
      "IsDeleted": false,
      "DocumentType": "Buy", // входящая накладная
      "DateTime": "2019-08-07T16:30:45.604",
      "Items": [
        {
          "Uid": "f8b0df39-a7a7-4f5e-9163-f5dc2d9f88a6",
          "Good": {
            "Uid": "aded9bd2-35ec-47bd-93ad-750f57b214cf",
            "Barcode": "4605840733826",
            "Name": "личный счет триколор тв 100р",
            "Group": {
              "Name": "Оплата Триколор",
              "Uid": "e1b32b53-5c2e-498f-8dc1-ec9ffd4be1be"
            }
          },
          "Quantity": 100.0,
          "BuyPrice": 100.0,
          "SalePrice": 110.0,
          "Discount": 0.0
        }
      ]
    }
  ]
}