Создание маршрутного листа: различия между версиями

Материал из Касса
Перейти к навигации Перейти к поиску
 
(не показаны 22 промежуточные версии этого же участника)
Строка 1: Строка 1:
== CASHDESK API==
= CASHDESK API=


'''API''' (Application Programming Interface или интерфейс программирования приложений) — это совокупность инструментов и функций в виде интерфейса для создания новых приложений, благодаря которому одна программа будет взаимодействовать с другой.
'''API''' (Application Programming Interface или интерфейс программирования приложений) — это совокупность инструментов и функций в виде интерфейса для создания новых приложений, благодаря которому одна программа будет взаимодействовать с другой.
Строка 5: Строка 5:
Для работы с API сервиса БИФИТ Касса, пользователю необходимо получить токен доступа. Генерация токена происходит по правилам авторизации OAuth2. С инструкцией авторизации по API можно ознакомиться <b>[https://kassa.bifit.com/wiki/index.php?title=ИНСТРУКЦИИ:Авторизация_при_интеграции_по_API здесь]</b>.
Для работы с API сервиса БИФИТ Касса, пользователю необходимо получить токен доступа. Генерация токена происходит по правилам авторизации OAuth2. С инструкцией авторизации по API можно ознакомиться <b>[https://kassa.bifit.com/wiki/index.php?title=ИНСТРУКЦИИ:Авторизация_при_интеграции_по_API здесь]</b>.


= Нумераторы =
{{ProductTable-2
|title-left='''TaxSystem''' - cистема налогообложения (тэг 1055). Если при регистрации устройства в ФНС было выбрано более одного режима налогообложения, то в '''TaxSystem''' необходимо указать, к какой системе налогообложения относится данный чек.
|title-right=
|content-left=
&nbsp;
* '''COMMON'''
* '''SIMPLIFIED'''
* '''SIMPLIFIED_WITH_EXPENSE'''
* '''COMMON_AGRICULTURAL'''
* '''PATENT'''
|content-right=
&nbsp;
* ОСН
* УСН доход
* УСН доход - расход
* ЕСХН
* ПАТЕНТ
|}}<br>
{{ProductTable-2
|title-left='''СurrentStatusType''' - Статусы онлайн-заказов
|title-right=
|content-left=
&nbsp;
* '''NEW'''
* '''ACCEPTED'''
* '''DISTRIBUTED'''
* '''ISSUED'''
* '''REFUSED'''
* '''DELETED'''
* '''FINISHED'''
|content-right=
&nbsp;
* НОВЫЙ
* ПОДТВЕРЖДЕН
* РАСПРЕДЕЛЕН
* ВЫДАННЫЙ
* ОТКАЗ
* УДАЛЕН
* ЗАВЕРШЕН
|}}<br>


= Создание маршрутного листа=
= Создание маршрутного листа=


Подготовьте POST запрос следующего вида:
{{ProductTable-2
 
|title-left='''Запрос'''
base URL: https://kassa.bifit.com/cashdesk-api/v1/protected/route_sheet_document
|title-right='''POST'''
|content-left= <br>URL: https://kassa.bifit.com/cashdesk-api/v1/protected/route_sheet_document
|content-right=
<syntaxhighlight>
https://kassa.bifit.com/cashdesk-api/v1/protected/route_sheet_document
</syntaxhighlight>
|}}<br>


В '''AUTHORIZATION''' укажите значение access_token согласно:
{{Note|'''''Важно!'''''<br>
В '''HEADERS''' укажите значение '''access_token''' согласно:'''authorization''': Bearer <значение '''acces_token'''> .|800}}


Bearer token : token <значение '''acces_token'''>


В '''BODY''' запроса укажите данные, согласно структуре описанной в [https://kassa.bifit.com/cashdesk-api/v1/swagger-ui.html#/online_orders/createOnlineOrderUsingPOST SWAGGER].
{{ProductTable-2
|title-left= Request Body
|title-right= type: '''raw''' (JSON)
|content-left=&nbsp;
''document'':
* '''amount''': Сумма заказов маршрутного листа
* '''cashierName''': Имя кассира
* '''courierUserId''': ID курьера
* '''courierUserName''': Логин (номер телефона) курьера
* '''description''': Описание
* '''documentDate''': Дата создания маршрутного листа в формате '''UNIX TIME''' '''*'''
* '''documentNumber''': Номер маршрутного листа '''*'''
* '''firstDeliveryTime''': Время первой доставки '''*'''
* '''lastDeliveryTime''': Время последней доставки '''*'''
* '''ordersCount''': Количество заказов '''*'''
* '''organizationId''': ID организации '''*'''
* '''priority''': Приоритетность маршрутного листа в системе '''*'''
* '''responsiblePerson''': Ответственный сотрудник
* '''responsibleUserId''': ID Ответственного сотрудника '''*'''
* '''status''': Статус маршрутного листа '''*'''
* '''tradeObjectId''': ID торгового объекта '''*'''
''items'':
* '''organizationId''': ID организации '''*'''
* '''tradeObjectId''': ID торгового обекта '''*'''
* '''taxSystem''': Система налогообложения '''*'''
* '''externalId''': Номер онлайн-заказа '''*'''
* '''deliveryType''': Тип доставки '''*'''
* '''deliveryAmount''': Стоимость доставки
* '''deliveryTime''': Время доставки в формате '''UNIX TIME''' '''*'''
* '''paid''': Признак оплаты заказа '''*'''
* '''orderTime''': Время заказа '''UNIX TIME''' '''*'''
* '''clientId''': ID клиента '''*'''
* '''address''': Адрес доставки '''*'''
* '''responsiblePersonLogin''': Логин (номер телефона) ответственного сотрудника. После создания заказа логин будет равен логину создателя заказа '''*'''
* '''location''': GPS координаты курьера
* '''totalAmount''': Итоговая стоимость заказа '''*'''
* '''comment''': Комментарий к заказу
* '''currentStatusType''': Текущий статус заказа NEW - новый, только что созданный заказ '''*'''
* '''currentStatusTime''': Время изменения статуса заказа в формате '''UNIX TIME''' '''*'''
* '''substatusId''': ID пользовательского статуса
* '''shopId''': ID интернет витрины
* '''endLockTime''': Время окончания блокировки онлайн-заказа курьером
* '''size''': Количество позиций в заказе
* '''actualDeliveryTime''': Фактическое время доставки
* '''routeSheetDocumentPosition''': Позиция заказа в маршрутном листе '''*'''
* '''cashierName''': Имя кассира
* '''clientName''': Имя клиента


|content-right=&nbsp;
<syntaxhighlight lang="JSON">
  {
  {
   "document": {
   "document": {
Строка 25: Строка 123:
     "courierUserName": null,
     "courierUserName": null,
     "description": null,
     "description": null,
     "documentDate": 1646143440371 ,                           ''//Дата создания маршрутного листа''*
     "documentDate": 1646143440371 ,              
     "documentNumber": "114477",                               ''//Номер маршрутного листа''
     "documentNumber": "114477",            
     "firstDeliveryTime": 1646143440371,                       ''//Время первой доставки''
     "firstDeliveryTime": 1646143440371,    
     "lastDeliveryTime": 1646143440371,                       ''//Время последней доставки''
     "lastDeliveryTime": 1646143440371,  
     "ordersCount": 1,                                         ''//Количество заказов''
     "ordersCount": 1,                
     "organizationId": "<organization_id>",                   ''//ID организации''
     "organizationId": "<organization_id>",  
     "priority": "LOW",                                       ''//Приоритетность маршрутного листа в системе''
     "priority": "LOW",  
     "responsiblePerson": null,
     "responsiblePerson": null,
     "responsibleUserId": 93727,                               ''//ID Ответственного сотрудника''
     "responsibleUserId": 93727,    
     "status": "NEW",                                         ''//Статус маршрутного листа''
     "status": "NEW",                
     "tradeObjectId": "<trade_object_id>"                     ''//ID торгового объекта''
     "tradeObjectId": "<trade_object_id>"  
   },
   },
   "items": [
   "items": [
     {
     {
       "organizationId": "<organization_id>",                 ''//ID организации''
       "organizationId": "<organization_id>",                
       "tradeObjectId": "<trade_object_id>",                   ''//ID торгового обекта''
       "tradeObjectId": "<trade_object_id>",            
       "taxSystem": "COMMON",                                 ''//Система налогообложения '''COMMON''' - ОСН (см. [[#Систем налогообложения|Таблица систем налогообложения]])''
       "taxSystem": "COMMON",            
       "externalId": "11223344",                               ''//Номер онлайн-заказа''
       "externalId": "11223344",          
       "deliveryType": "COURIER",                             ''//Тип доставки''
       "deliveryType": "COURIER",          
       "deliveryAmount": null,                                 ''//Стоимость доставки''
       "deliveryAmount": null,                          
       "deliveryTime": 1646143684830,                         ''//Время доставки в формате UNIX TIME''
       "deliveryTime": 1646143684830,  
       "paid": false,                                         ''//Признак оплаты заказа''
       "paid": false,    
       "orderTime": 1646137566448,                             ''//Время заказа''
       "orderTime": 1646137566448,
       "clientId": 195363,                                     ''//ID клиента''
       "clientId": 195363,  
       "address": "Адрес",                                     ''//Адрес доставки''
       "address": "Адрес",    
       "responsiblePersonLogin": "7хххххххххх",               ''//Логин (номер телефона) ответственного сотрудника. После создания заказа логин будет равен логину создателя заказа''
       "responsiblePersonLogin": "7хххххххххх",        
       "location": null,                                       ''//GPS координаты курьера''
       "location": null,            
       "totalAmount": 57.00,                                   ''//Итоговая стоимость заказа''
       "totalAmount": 57.00,          
       "comment": null,                                       ''//Комментарий к заказу''
       "comment": null,            
       "currentStatusType": "NEW",                             ''//Текущий статус заказа NEW - новый, только что созданный заказ (см. [[#Статусы заказов|Таблица статусов заказов]])''
       "currentStatusType": "NEW",          
       "currentStatusTime": 1646135475820,                     ''//Время изменения статуса заказа в формате UNIX TIME''
       "currentStatusTime": 1646135475820,      
       "substatusId": null,                                   ''//ID пользовательского статуса''
       "substatusId": null,          
       "shopId": null,                                         ''//ID интернет витрины''
       "shopId": null,                
       "endLockTime": null,                                   ''//Время окончания блокировки онлайн-заказа курьером''
       "endLockTime": null,        
       "size": 1,                                             ''//Количество позиций в заказе''
       "size": 1,                  
       "actualDeliveryTime": null,                             ''//Фактическое время доставки''
       "actualDeliveryTime": null,  
       "routeSheetDocumentPosition": 1                         ''//Позиция заказа в маршрутном листе''
       "routeSheetDocumentPosition": 1    
       "cashierName": null,                                   ''//Имя кассира''
       "cashierName": null,  
       "clientName": null,                                     ''//Имя клиента''
       "clientName": null,  
     }
     }
   ]
   ]
  }
  }
</syntaxhighlight>
|}}<br>


=== Систем налогообложения ===
{{Note|'''Важно'''
{| class="wikitable"
* Поля обязательные для заполнения помечены '''*'''.
|+ Таблица систем налогообложения
* При создании маршрутного листа, статус онлайн заказа должен быть: "NEW", "ACCEPTED" или "DISTRIBUTED".
|-
|700}}
! Значение нумератора !! Описание
|-
| '''COMMON''' || (ОСН - Общая система налогообложения)
|-
| '''SIMPLIFIED''' || (УСН 6% с дохода)
|-
| '''SIMPLIFIED_WITH_EXPENSE'''  || (УСН 15% доход - расход)
|-
|'''ENVD''' || ('''ЕНВД не используется с 01.01.2020''')
|-
| '''COMMON_AGRICULTURAL''' || (ЕСН или ЕСХН)
|-
| '''PATENT''' || (ПАТЕНТНАЯ система налогообложения)
|}


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


{| class="wikitable"
{{ProductTable-2
|+ Таблица статусов заказов
|title-left='''Response'''
|-
|title-right=
! Значение нумератора !! Описание
|content-left= <br>ID созданного маршрутного листа
|-
|content-right=
| '''NEW''' || НОВЫЙ
<syntaxhighlight>
|-
208
| '''ACCEPTED''' || ПОДТВЕРЖДЕН
</syntaxhighlight>
|-
|}}<br>
| '''DISTRIBUTED'''  || РАСПРЕДЕЛЕН
|-
|'''ISSUED''' || ВЫДАННЫЙ
|-
| '''REFUSED''' || ОТКАЗ
|-
| '''DELETED''' || УДАЛЕН
|-
| '''FINISHED''' || ЗАВЕРШЕН
|}


{{ Note |'''''Примечание'''''<br>  
{{Note|'''''Примечание'''''<br>
* При создании заказа, есть несколько видов доставки. Ознакомьтесь с типами доставки:
После получения ID созданного маршрутного, укажите его в поисковом запросе https://kassa.bifit.com/cashdesk/#/app_cashdesk/online_orders/route_sheet_document/ после знака /.|800}}
** "COURIER" - в случае, если используется курьерская доставка
** "SELF" - самовывоз, в этом случае адрес доставки не требуется, место расчетов в чеке берется из ККТ/ТО
** "SERVICE" - не используется
* Каждому созданному заказу присваивается определенный статус. Ознакомьтесь со статусами заказов:
** "ACCEPTED" -  статус “Подтвержден”, заказы в данном статусе доступны для отображения всем сотрудникам на МКТ. Используем при создании заказа.
** "DISTRIBUTED" - статус “Распределен”, заказы в данном статусе доступны для отображения на МКТ только тем сотрудникам, на которых эти заказы назначены.
** "REFUSED" - статус “Отменен”, заказ с таким статусом невозможно создать, можно добавить статус с помощью PUT запроса, либо перевести заказ в данный статус из клиентского ПО, отменить заказ можно только в статусах "DISTRIBUTED","ACCEPTED"Статус REFUSED необходимо использовать при отмене заказа в статусах DISTRIBUTED и ACCEPTED.
**"DELETED" - статус “Удален”, заказ с таким статусом невозможно создать, можно добавить статус с помощью PUT запроса, заказ, в статусе “Удален” не будет доступен для работы, удалить можно только заказ в статусе "currentStatusType": "NEW". Статус DELETED необходимо использовать при отмене заказа только в статусе NEW.
|800}}

Текущая версия на 11:02, 8 ноября 2022

CASHDESK API

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

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

Нумераторы

TaxSystem - cистема налогообложения (тэг 1055). Если при регистрации устройства в ФНС было выбрано более одного режима налогообложения, то в TaxSystem необходимо указать, к какой системе налогообложения относится данный чек.
 
  • COMMON
  • SIMPLIFIED
  • SIMPLIFIED_WITH_EXPENSE
  • COMMON_AGRICULTURAL
  • PATENT
 
  • ОСН
  • УСН доход
  • УСН доход - расход
  • ЕСХН
  • ПАТЕНТ


СurrentStatusType - Статусы онлайн-заказов
 
  • NEW
  • ACCEPTED
  • DISTRIBUTED
  • ISSUED
  • REFUSED
  • DELETED
  • FINISHED
 
  • НОВЫЙ
  • ПОДТВЕРЖДЕН
  • РАСПРЕДЕЛЕН
  • ВЫДАННЫЙ
  • ОТКАЗ
  • УДАЛЕН
  • ЗАВЕРШЕН


Создание маршрутного листа

Запрос POST

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


Note.svg Важно!
В HEADERS укажите значение access_token согласно:authorization: Bearer <значение acces_token> .


Request Body type: raw (JSON)
 

document:

  • amount: Сумма заказов маршрутного листа
  • cashierName: Имя кассира
  • courierUserId: ID курьера
  • courierUserName: Логин (номер телефона) курьера
  • description: Описание
  • documentDate: Дата создания маршрутного листа в формате UNIX TIME *
  • documentNumber: Номер маршрутного листа *
  • firstDeliveryTime: Время первой доставки *
  • lastDeliveryTime: Время последней доставки *
  • ordersCount: Количество заказов *
  • organizationId: ID организации *
  • priority: Приоритетность маршрутного листа в системе *
  • responsiblePerson: Ответственный сотрудник
  • responsibleUserId: ID Ответственного сотрудника *
  • status: Статус маршрутного листа *
  • tradeObjectId: ID торгового объекта *

items:

  • organizationId: ID организации *
  • tradeObjectId: ID торгового обекта *
  • taxSystem: Система налогообложения *
  • externalId: Номер онлайн-заказа *
  • deliveryType: Тип доставки *
  • deliveryAmount: Стоимость доставки
  • deliveryTime: Время доставки в формате UNIX TIME *
  • paid: Признак оплаты заказа *
  • orderTime: Время заказа UNIX TIME *
  • clientId: ID клиента *
  • address: Адрес доставки *
  • responsiblePersonLogin: Логин (номер телефона) ответственного сотрудника. После создания заказа логин будет равен логину создателя заказа *
  • location: GPS координаты курьера
  • totalAmount: Итоговая стоимость заказа *
  • comment: Комментарий к заказу
  • currentStatusType: Текущий статус заказа NEW - новый, только что созданный заказ *
  • currentStatusTime: Время изменения статуса заказа в формате UNIX TIME *
  • substatusId: ID пользовательского статуса
  • shopId: ID интернет витрины
  • endLockTime: Время окончания блокировки онлайн-заказа курьером
  • size: Количество позиций в заказе
  • actualDeliveryTime: Фактическое время доставки
  • routeSheetDocumentPosition: Позиция заказа в маршрутном листе *
  • cashierName: Имя кассира
  • clientName: Имя клиента
 
 {
  "document": {
    "amount": 0,
    "cashierName": null,
    "courierUserId": null,
    "courierUserName": null,
    "description": null,
    "documentDate": 1646143440371 ,               
    "documentNumber": "114477",              
    "firstDeliveryTime": 1646143440371,     
    "lastDeliveryTime": 1646143440371,   
    "ordersCount": 1,                  
    "organizationId": "<organization_id>",   
    "priority": "LOW",    
    "responsiblePerson": null,
    "responsibleUserId": 93727,     
    "status": "NEW",                 
    "tradeObjectId": "<trade_object_id>"   
  },
  "items": [
    {
      "organizationId": "<organization_id>",                 
      "tradeObjectId": "<trade_object_id>",              
      "taxSystem": "COMMON",             
      "externalId": "11223344",            
      "deliveryType": "COURIER",            
      "deliveryAmount": null,                            
      "deliveryTime": 1646143684830, 
      "paid": false,     
      "orderTime": 1646137566448,  
      "clientId": 195363,    
      "address": "Адрес",     
      "responsiblePersonLogin": "7хххххххххх",          
      "location": null,             
      "totalAmount": 57.00,           
      "comment": null,              
      "currentStatusType": "NEW",           
      "currentStatusTime": 1646135475820,       
      "substatusId": null,           
      "shopId": null,                 
      "endLockTime": null,          
      "size": 1,                    
      "actualDeliveryTime": null,    
      "routeSheetDocumentPosition": 1     
      "cashierName": null,   
      "clientName": null, 
     }
   ]
 }


Note.svg Важно

  • Поля обязательные для заполнения помечены *.
  • При создании маршрутного листа, статус онлайн заказа должен быть: "NEW", "ACCEPTED" или "DISTRIBUTED".


Response

ID созданного маршрутного листа
208


Note.svg Примечание
После получения ID созданного маршрутного, укажите его в поисковом запросе https://kassa.bifit.com/cashdesk/#/app_cashdesk/online_orders/route_sheet_document/ после знака /.