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

Материал из Касса
Перейти к навигации Перейти к поиску
 
(не показано 12 промежуточных версий этого же участника)
Строка 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>


= Создание маршрутного листа=
= Создание маршрутного листа=
Строка 18: Строка 62:
|}}<br>
|}}<br>


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


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


{{Note|'''Важно'''
{{Note|'''Важно'''
Строка 182: Строка 173:
|700}}
|700}}


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


=== Статусы заказов ===
{{ProductTable-2
|title-left='''Response'''
|title-right=
|content-left= <br>ID созданного маршрутного листа
|content-right=
<syntaxhighlight>
208
</syntaxhighlight>
|}}<br>


{| class="wikitable"
{{Note|'''''Примечание'''''<br>
|+ Таблица статусов заказов
После получения ID созданного маршрутного, укажите его в поисковом запросе https://kassa.bifit.com/cashdesk/#/app_cashdesk/online_orders/route_sheet_document/ после знака /.|800}}
|-
! Значение нумератора !! Описание
|-
| '''NEW''' || НОВЫЙ
|-
| '''ACCEPTED''' || ПОДТВЕРЖДЕН
|-
| '''DISTRIBUTED'''  || РАСПРЕДЕЛЕН
|-
|'''ISSUED''' || ВЫДАННЫЙ
|-
| '''REFUSED''' || ОТКАЗ
|-
| '''DELETED''' || УДАЛЕН
|-
| '''FINISHED''' || ЗАВЕРШЕН
|}
 
{{ Note |'''''Примечание'''''<br>  
* При создании заказа, есть несколько видов доставки. Ознакомьтесь с типами доставки:
** "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/ после знака /.