CASHDESK API:Создание онлайн заказа: различия между версиями

Материал из Касса
Перейти к навигации Перейти к поиску
 
(не показана 41 промежуточная версия 2 участников)
Строка 1: Строка 1:
__TOC__
== CASHDESK API==
 
'''API''' (Application Programming Interface или интерфейс программирования приложений) — это совокупность инструментов и функций в виде интерфейса для создания новых приложений, благодаря которому одна программа будет взаимодействовать с другой.
'''API''' (Application Programming Interface или интерфейс программирования приложений) — это совокупность инструментов и функций в виде интерфейса для создания новых приложений, благодаря которому одна программа будет взаимодействовать с другой.


Строка 10: Строка 11:
  base URL: https://kassa.bifit.com/cashdesk-api/v1/protected/online_orders
  base URL: https://kassa.bifit.com/cashdesk-api/v1/protected/online_orders


В рамках согласованного процесса, заказы создаются в статусе “Подтвержден” или “Новый”.
В '''HEADERS''' укажите значение access_token согласно:
* Для заказов, передаваемых курьерам необходимо использовать статус NEW при создании заказа
'''authorization''': Bearer <значение '''acces_token'''>
* Для заказов самовывоза необходимо использовать статус ACCEPTED при создании заказа
 
 
В '''BODY''' запроса передайте заказ в JSON согласно структуре описанной в [https://kassa.bifit.com/cashdesk-api/v1/swagger-ui.html#/online_orders/createOnlineOrderUsingPOST SWAGGER].
 
''Пример JSON:''
 
{
    "onlineOrder": {
        "visible": true,                                ''//Признак видимости заказа''
        "created": 1644828163053,                        ''//Время создания в формате UNIX TIME''
        "changed": 1644828163053,                       ''//Время создания в формате UNIX TIME''
        "organizationId": "<''organization_id''>",          ''//ID организации''
        "tradeObjectId": "<''trade_object_id''>",            ''//ID торгового объекта''
        "taxSystem": "COMMON",                          ''//Система налогообложения '''COMMON''' - ОСН (см. [[#Систем налогообложения|Таблица систем налогообложения]])''
        "externalId": "BFt-002",                        ''//Номер заказа в информационной системе интегратора''
        "deliveryType": "COURIER",                      ''//Тип доставки '''COURIER''' - Курьером (либо '''SELF''' - Самовывоз)''
        "deliveryAmount": null,                          ''//''
        "deliveryTime": null,                            ''//Время доставки в формате UNIX TIME''
        "paid": false,                                  ''//Признак оплаты заказа''
        "orderTime": 1644828134297,
        "clientId": 124329,                              ''//ID клиента''
        "address": "Адрес",                              ''//Адрес доставки''
        "responsiblePersonLogin": "7xxxxxxxxxx",        ''//Логин (номер телефона) ответственного сотрудника. После создания заказа логин будет равен логину создателя заказа''
        "discount": 0.00,                                ''//Величина скидки на заказ ('''не используется''')''
        "discountType": 0,                              ''//Тип скидки на заказ ('''не используется''')''
        "location": null,                                ''//GPS координаты курьера''
        "totalAmount": 14500.00,                        ''//Итоговая стоимость заказа''
        "comment": null,                                ''//Комментарий к заказу''
        "currentStatusType": "NEW",                     ''//Текущий статус заказа NEW - новый, только что созданный заказ (см. [[#Статусы заказов|Таблица статусов заказов]])''
        "currentStatusTime": 1644828159791,              ''//Время изменения статуса заказа в формате UNIX TIME''
        "substatusId": null,                            ''//ID пользовательского статуса''
        "shopId": null,                                  ''//ID интернет витрины''
        "endLockTime": null,
        "routeSheetDocumentId": null,                    ''//ID Маршрутного листа''
        "routeSheetDocumentPosition": null,              ''//Номер позиции заказа в маршрутном листе''
        "routeSheetDocumentNumber": null,
        "size": null,
        "actualDeliveryTime": null,
        "cashierName": null,                            ''//Имя кассира''
        "clientName": null                              ''//Имя клиента''
    },
    "onlineOrderItems": [
        {
            "nomenclatureId": 22090265,                  ''//ID номенклатурной позиции из справочника номенклатур''
            "description": "Букет белых роз",            ''//Наименование товарной позиции''
            "price": 3000,                              ''//Цена товарной позиции''
            "vatValue": 20,                              ''//Величина ставки НДС (см. [[#Ставки НДС|Таблица ставок НДС]])''
            "quantity": 1,                              ''//Кол-во''
            "discount": 0,                              ''//% скидки''
            "calculationMethod": null,                  ''//Признак способа расчёта (см. [[#Признаки способа расчётов|Таблица признаков способа расчётов (тэг 1214)]])''
            "paymentSubject": "PRODUCT",                ''//Признак предмета расчёта (см. [[#Признаки предмета расчётов|Таблица признаков предмета расчётов (тэг 1212)]])''
            "contractorAddress": null,                  ''//Адрес поставщика (при реализации агентских товаров и услуг)''
            "contractorInn": null,                      ''//ИНН поставщика (при реализации агентских товаров и услуг)''
            "contractorName": null,                      ''//Наименование организации поставщика (при реализации агентских товаров и услуг)''
            "contractorPhone": null,                    ''//Телефон поставщика (при реализации агентских товаров и услуг)''
            "organizationPhone": null,                  ''//Телефон''
            "contractorActivityType": null,              ''//''
            "markType": "UNKNOWN",                      ''//Тип маркировки (см. [[#Типы маркировок|Таблица Типов маркировок]])''
            "codeForOfd": null,                          ''//Код маркировки (КМ)''
            "barcode": null,                            ''//Штрих код позиции (EAN-8, EAN-13)''
            "vendorCode": null,                          ''//Артикул производителя''
            "unitCode": 796,                            ''//Код единицы измерения по ОКЕИ''
            "editable": true,                            ''//Признак редактируемости позиции в приложении''
            "total": null                               
        },
        {
            "nomenclatureId": 22090204,
            "description": "Букет роз, 40 шт",
            "price": 7000,
            "vatValue": 20,
            "quantity": 1,
            "discount": 0,
            "calculationMethod": null,
            "paymentSubject": "PRODUCT",
            "contractorAddress": null,
            "contractorInn": null,
            "contractorName": null,
            "contractorPhone": null,
            "organizationPhone": null,
            "contractorActivityType": null,
            "markType": "UNKNOWN",
            "codeForOfd": null,
            "barcode": null,
            "vendorCode": null,
            "unitCode": 796,
            "editable": true,
            "total": null
        },
        {
            "nomenclatureId": 22090243,
            "description": "Букет розовых и белых роз, 15 штук",
            "price": 4500,
            "vatValue": 20,
            "quantity": 1,
            "discount": 0,
            "calculationMethod": null,
            "paymentSubject": "PRODUCT",
            "contractorAddress": null,
            "contractorInn": null,
            "contractorName": null,
            "contractorPhone": null,
            "organizationPhone": null,
            "contractorActivityType": null,
            "markType": "UNKNOWN",
            "codeForOfd": null,
            "barcode": null,
            "vendorCode": null,
            "unitCode": 796,
            "editable": true,
            "total": null
        }
    ], 
    "properties": {                                    ''//Свойства''
        "fullSettlement": true,                        ''//Курьеру разрешено принимать полную оплату''
        "prepayment": false,                            ''//Курьеру запрещено принимать предоплату''
        "credit": false                                ''//Курьеру запрещено передавать заказ в кредит''
    },
    "client": {
        "organizationId": "<''organization_id''>",      ''//ID организации''
        "address": "Адрес",                            ''//Адрес доставки''
        "phone": "79999999999",                        ''//Номер телефона клиента''
        "lastName": "Иванов",                          ''//Фамилия клиента''
        "firstName": "Иван",                            ''//Имя клиента клиента''
        "patronymic": "Иванович",                      ''//Отчество клиента клиента''
        "email": "",                                    ''//Электронная почта клиента, сюда будет отправлен чек''
        "comment": null,                                ''//Комментарий''
    },
    "organizationId": null,
    "cashierInfos": null
}
 
=== Систем налогообложения ===
{| class="wikitable"
|+ Таблица систем налогообложения
|-
! Значение нумератора !! Описание
|-
| '''COMMON''' || (ОСН - Общая система налогообложения)
|-
| '''SIMPLIFIED''' || (УСН 6% с дохода)
|-
| '''SIMPLIFIED_WITH_EXPENSE'''  || (УСН 15% доход - расход)
|-
|'''ENVD''' || ('''ЕНВД не используется с 01.01.2020''')
|-
| '''COMMON_AGRICULTURAL''' || (ЕСН или ЕСХН)
|-
| '''PATENT''' || (ПАТЕНТНАЯ система налогообложения)
|}
 
=== Статусы заказов ===
 
{| class="wikitable"
|+ Таблица статусов заказов
|-
! Значение нумератора !! Описание
|-
| '''NEW''' || НОВЫЙ
|-
| '''ACCEPTED''' || ПОДТВЕРЖДЕН
|-
| '''DISTRIBUTED'''  || РАСПРЕДЕЛЕН
|-
|'''ISSUED''' || ВЫДАННЫЙ
|-
| '''REFUSED''' || ОТКАЗ
|-
| '''DELETED''' || УДАЛЕН
|-
| '''FINISHED''' || ЗАВЕРШЕН
|}
 
=== Ставки НДС ===


{| class="wikitable"
|+ Таблица ставок НДС
|-
! Значение нумератора !! Описание
|-
| '''null''' || БЕЗ НДС
|-
| '''0''' || НДС 0%
|-
| '''10'''  || НДС 10%
|-
|'''20''' || НДС 20%
|-
| '''110''' || НДС 10/110%
|-
| '''120''' || НДС 20/120%
|}


Для самовывоза или доставки необходимо передавать "employeeAccess": null
=== Признаки способа расчётов ===
{| class="wikitable"
|+ Таблица признаков способа расчётов (тэг 1214)
|-
! Значение нумератора !! Описание
|-
| '''null''' || ПОЛНАЯ ОПЛАТА
|-
| '''FULL_PAY''' || ПОЛНАЯ ОПЛАТА
|-
| '''PREPAY_FULL'''  || 100% ПРЕДОПЛАТА
|-
|'''PREPAY''' || ЧАСТИЧНАЯ ПРЕДОПЛАТА
|}




В массив onlineOrder передаются следующие обязательные значения:
=== Признаки предмета расчётов ===
{| class="wikitable"
|+ Таблица признаков предмета расчётов (тэг 1212)
|-
! Значение нумератора !! Описание
|-
| '''PRODUCT''' || ТОВАР
|-
| '''SERVICE''' || УСЛУГА
|-
| '''EXCISABLE_PRODUCT '''  || ПОДАКЦИЗНЫЙ ТОВАР
|-
|'''JOB''' || РАБОТА
|-
|'''GAMBLING_RATE''' || ИГРОВАЯ СТАВКА
|}


"visible": true,  \\Видимость онлайн-заказа
=== Типы маркировок ===
!"organizationId": "16286094820321052850480", \\В какую организацию создаем заказ
{| class="wikitable"
!"tradeObjectId": "1628609482057-1613612358", \\В какой торговый объект создаем заказ
|+ Таблица типов маркировок
!"taxSystem": "COMMON", \\СНО заказа
|-
"externalId": "VQ12345678", \\Номер заказа во внешней системе
! Значение нумератора !! Описание
!"deliveryType": "COURIER", \\Тип доставки
|-
"COURIER" - в случае, если используется курьерская доставка
| '''UNKNOWN ''' || БЕЗ МАРКИРОВКИ
                            "SELF" - самовывоз, в этом случае адрес доставки не требуется, место расчетов в чеке берется из ККТ/ТО
|-
                        "SERVICE" - не используется
| '''OTHER''' || МАРКИРОВКА (обувь, шины, духи, лег.пром, молоко)
|}


!"paid": false,
{{ Note |'''''Примечание'''''<br>
"employeeAccess": "NULL",
* При создании заказа, есть несколько видов доставки. Ознакомьтесь с типами доставки:
"orderTime": 1631094730812,
** "COURIER" - в случае, если используется курьерская доставка
"address": "Адрес",
** "SELF" - самовывоз, в этом случае адрес доставки не требуется, место расчетов в чеке берется из ККТ/ТО
"responsiblePersonLogin": "79295444301",
** "SERVICE" - не используется
!"totalAmount": 95,
* Каждому созданному заказу присваивается определенный статус. Ознакомьтесь со статусами заказов:
!"currentStatusType": "NEW",
** "ACCEPTED" -  статус “Подтвержден”, заказы в данном статусе доступны для отображения всем сотрудникам на МКТ. Используем при создании заказа.
  !"currentStatusTime": 1630936599865
** "DISTRIBUTED" - статус “Распределен”, заказы в данном статусе доступны для отображения на МКТ только тем сотрудникам, на которых эти заказы назначены.
** "REFUSED" - статус “Отменен”, заказ с таким статусом невозможно создать, можно добавить статус с помощью PUT запроса, либо перевести заказ в данный статус из клиентского ПО, отменить заказ можно только в статусах "DISTRIBUTED","ACCEPTED".  Статус REFUSED необходимо использовать при отмене заказа в статусах DISTRIBUTED и ACCEPTED.
**"DELETED" - статус “Удален”, заказ с таким статусом невозможно создать, можно добавить статус с помощью PUT запроса, заказ, в статусе “Удален” не будет доступен для работы, удалить можно только заказ в статусе "currentStatusType": "NEW". Статус DELETED необходимо использовать при отмене заказа только в статусе NEW.
  |800}}

Текущая версия на 17:16, 23 марта 2022

CASHDESK API

API (Application Programming Interface или интерфейс программирования приложений) — это совокупность инструментов и функций в виде интерфейса для создания новых приложений, благодаря которому одна программа будет взаимодействовать с другой.

Для работы с API сервиса БИФИТ Касса, пользователю необходимо получить токен доступа. Генерация токена происходит по правилам авторизации OAuth2. С инструкцией авторизации по API можно ознакомиться здесь.

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

Подготовьте POST запрос следующего вида:

base URL: https://kassa.bifit.com/cashdesk-api/v1/protected/online_orders

В HEADERS укажите значение access_token согласно:

authorization: Bearer <значение acces_token>


В BODY запроса передайте заказ в JSON согласно структуре описанной в SWAGGER.

Пример JSON:

{
   "onlineOrder": {
       "visible": true,                                 //Признак видимости заказа
       "created": 1644828163053,                        //Время создания в формате UNIX TIME
       "changed": 1644828163053,                        //Время создания в формате UNIX TIME
       "organizationId": "<organization_id>",           //ID организации
       "tradeObjectId": "<trade_object_id>",            //ID торгового объекта
       "taxSystem": "COMMON",                           //Система налогообложения COMMON - ОСН (см. Таблица систем налогообложения)
       "externalId": "BFt-002",                         //Номер заказа в информационной системе интегратора
       "deliveryType": "COURIER",                       //Тип доставки COURIER - Курьером (либо SELF - Самовывоз)
       "deliveryAmount": null,                          //
       "deliveryTime": null,                            //Время доставки в формате UNIX TIME
       "paid": false,                                   //Признак оплаты заказа
       "orderTime": 1644828134297,
       "clientId": 124329,                              //ID клиента
       "address": "Адрес",                              //Адрес доставки
       "responsiblePersonLogin": "7xxxxxxxxxx",         //Логин (номер телефона) ответственного сотрудника. После создания заказа логин будет равен логину создателя заказа
       "discount": 0.00,                                //Величина скидки на заказ (не используется)
       "discountType": 0,                               //Тип скидки на заказ (не используется)
       "location": null,                                //GPS координаты курьера
       "totalAmount": 14500.00,                         //Итоговая стоимость заказа
       "comment": null,                                 //Комментарий к заказу
       "currentStatusType": "NEW",                      //Текущий статус заказа NEW - новый, только что созданный заказ (см. Таблица статусов заказов)
       "currentStatusTime": 1644828159791,              //Время изменения статуса заказа в формате UNIX TIME
       "substatusId": null,                             //ID пользовательского статуса
       "shopId": null,                                  //ID интернет витрины
       "endLockTime": null,
       "routeSheetDocumentId": null,                    //ID Маршрутного листа
       "routeSheetDocumentPosition": null,              //Номер позиции заказа в маршрутном листе
       "routeSheetDocumentNumber": null,
       "size": null,
       "actualDeliveryTime": null,
       "cashierName": null,                             //Имя кассира
       "clientName": null                               //Имя клиента
   },
   "onlineOrderItems": [
       {
           "nomenclatureId": 22090265,                  //ID номенклатурной позиции из справочника номенклатур
           "description": "Букет белых роз",            //Наименование товарной позиции
           "price": 3000,                               //Цена товарной позиции
           "vatValue": 20,                              //Величина ставки НДС (см. Таблица ставок НДС)
           "quantity": 1,                               //Кол-во
           "discount": 0,                               //% скидки
           "calculationMethod": null,                   //Признак способа расчёта (см. Таблица признаков способа расчётов (тэг 1214))
           "paymentSubject": "PRODUCT",                 //Признак предмета расчёта (см. Таблица признаков предмета расчётов (тэг 1212))
           "contractorAddress": null,                   //Адрес поставщика (при реализации агентских товаров и услуг) 
           "contractorInn": null,                       //ИНН поставщика (при реализации агентских товаров и услуг) 
           "contractorName": null,                      //Наименование организации поставщика (при реализации агентских товаров и услуг) 
           "contractorPhone": null,                     //Телефон поставщика (при реализации агентских товаров и услуг) 
           "organizationPhone": null,                   //Телефон 
           "contractorActivityType": null,              // 
           "markType": "UNKNOWN",                       //Тип маркировки (см. Таблица Типов маркировок) 
           "codeForOfd": null,                          //Код маркировки (КМ) 
           "barcode": null,                             //Штрих код позиции (EAN-8, EAN-13) 
           "vendorCode": null,                          //Артикул производителя 
           "unitCode": 796,                             //Код единицы измерения по ОКЕИ 
           "editable": true,                            //Признак редактируемости позиции в приложении 
           "total": null                                
       },
       {
           "nomenclatureId": 22090204,
           "description": "Букет роз, 40 шт",
           "price": 7000,
           "vatValue": 20,
           "quantity": 1,
           "discount": 0,
           "calculationMethod": null,
           "paymentSubject": "PRODUCT",
           "contractorAddress": null,
           "contractorInn": null,
           "contractorName": null,
           "contractorPhone": null,
           "organizationPhone": null,
           "contractorActivityType": null,
           "markType": "UNKNOWN",
           "codeForOfd": null,
           "barcode": null,
           "vendorCode": null,
           "unitCode": 796,
           "editable": true,
           "total": null
       },
       {
           "nomenclatureId": 22090243,
           "description": "Букет розовых и белых роз, 15 штук",
           "price": 4500,
           "vatValue": 20,
           "quantity": 1,
           "discount": 0,
           "calculationMethod": null,
           "paymentSubject": "PRODUCT",
           "contractorAddress": null,
           "contractorInn": null,
           "contractorName": null,
           "contractorPhone": null,
           "organizationPhone": null,
           "contractorActivityType": null,
           "markType": "UNKNOWN",
           "codeForOfd": null,
           "barcode": null,
           "vendorCode": null,
           "unitCode": 796,
           "editable": true,
           "total": null
       }
   ],  
   "properties": {                                     //Свойства 
       "fullSettlement": true,                         //Курьеру разрешено принимать полную оплату 
       "prepayment": false,                            //Курьеру запрещено принимать предоплату 
       "credit": false                                 //Курьеру запрещено передавать заказ в кредит 
   },
   "client": {
       "organizationId": "<organization_id>",      //ID организации
       "address": "Адрес",                             //Адрес доставки
       "phone": "79999999999",                         //Номер телефона клиента
       "lastName": "Иванов",                           //Фамилия клиента
       "firstName": "Иван",                            //Имя клиента клиента
       "patronymic": "Иванович",                       //Отчество клиента клиента
       "email": "",                                    //Электронная почта клиента, сюда будет отправлен чек
       "comment": null,                                //Комментарий
   },
   "organizationId": null,
   "cashierInfos": null
}

Систем налогообложения

Таблица систем налогообложения
Значение нумератора Описание
COMMON (ОСН - Общая система налогообложения)
SIMPLIFIED (УСН 6% с дохода)
SIMPLIFIED_WITH_EXPENSE (УСН 15% доход - расход)
ENVD (ЕНВД не используется с 01.01.2020)
COMMON_AGRICULTURAL (ЕСН или ЕСХН)
PATENT (ПАТЕНТНАЯ система налогообложения)

Статусы заказов

Таблица статусов заказов
Значение нумератора Описание
NEW НОВЫЙ
ACCEPTED ПОДТВЕРЖДЕН
DISTRIBUTED РАСПРЕДЕЛЕН
ISSUED ВЫДАННЫЙ
REFUSED ОТКАЗ
DELETED УДАЛЕН
FINISHED ЗАВЕРШЕН

Ставки НДС

Таблица ставок НДС
Значение нумератора Описание
null БЕЗ НДС
0 НДС 0%
10 НДС 10%
20 НДС 20%
110 НДС 10/110%
120 НДС 20/120%

Признаки способа расчётов

Таблица признаков способа расчётов (тэг 1214)
Значение нумератора Описание
null ПОЛНАЯ ОПЛАТА
FULL_PAY ПОЛНАЯ ОПЛАТА
PREPAY_FULL 100% ПРЕДОПЛАТА
PREPAY ЧАСТИЧНАЯ ПРЕДОПЛАТА


Признаки предмета расчётов

Таблица признаков предмета расчётов (тэг 1212)
Значение нумератора Описание
PRODUCT ТОВАР
SERVICE УСЛУГА
EXCISABLE_PRODUCT ПОДАКЦИЗНЫЙ ТОВАР
JOB РАБОТА
GAMBLING_RATE ИГРОВАЯ СТАВКА

Типы маркировок

Таблица типов маркировок
Значение нумератора Описание
UNKNOWN БЕЗ МАРКИРОВКИ
OTHER МАРКИРОВКА (обувь, шины, духи, лег.пром, молоко)

Note.svg Примечание

  • При создании заказа, есть несколько видов доставки. Ознакомьтесь с типами доставки:
    • "COURIER" - в случае, если используется курьерская доставка
    • "SELF" - самовывоз, в этом случае адрес доставки не требуется, место расчетов в чеке берется из ККТ/ТО
    • "SERVICE" - не используется
  • Каждому созданному заказу присваивается определенный статус. Ознакомьтесь со статусами заказов:
    • "ACCEPTED" - статус “Подтвержден”, заказы в данном статусе доступны для отображения всем сотрудникам на МКТ. Используем при создании заказа.
    • "DISTRIBUTED" - статус “Распределен”, заказы в данном статусе доступны для отображения на МКТ только тем сотрудникам, на которых эти заказы назначены.
    • "REFUSED" - статус “Отменен”, заказ с таким статусом невозможно создать, можно добавить статус с помощью PUT запроса, либо перевести заказ в данный статус из клиентского ПО, отменить заказ можно только в статусах "DISTRIBUTED","ACCEPTED". Статус REFUSED необходимо использовать при отмене заказа в статусах DISTRIBUTED и ACCEPTED.
    • "DELETED" - статус “Удален”, заказ с таким статусом невозможно создать, можно добавить статус с помощью PUT запроса, заказ, в статусе “Удален” не будет доступен для работы, удалить можно только заказ в статусе "currentStatusType": "NEW". Статус DELETED необходимо использовать при отмене заказа только в статусе NEW.