Смена

Для работы в POS терминале пользователю с ролью manager необходимо открыть смену c указанием точки, в которой он работает и, при необходимости, баланса кассы и комментария к открытию.

Проверка статуса смены

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

Для проверки статуса смены можно использовать API GET /api/session, либо данные, полученные в ходе авторизации пользователя через API POST /api/session (см. Получение сессии). В случае успешного выполнения оба этих API возвращают аналогичный результат - информацию о сотруднике, части системных настроек и текущей смене сотрудника.

В случае наличия у пользователя открытой смены, в информации о сессии будет присутствовать ключ shift.

Статус смены пользователя

curl "http://demo.idealist.one/api/session" \
     --header "Authorization: Bearer b3cd476d-fd53-4333-81ed-fd72bebb615e"

> GET /api/session HTTP/1.1
> Host: demo.idealist.one
> User-Agent: curl/7.56.1
> Accept: */*
> Authorization: Bearer b3cd476d-fd53-4333-81ed-fd72bebb615e

< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Tue, 28 Nov 2017 09:21:13 GMT
< Server: nginx/1.10.2
< Set-Cookie: session=b3cd476d-fd53-4333-81ed-fd72bebb615e; Expires=Thu, 30-Nov-2017 09:21:13 GMT; HttpOnly; Path=/
< X-Expires-In: 1512033673
< Content-Length: 1297
< Connection: keep-alive

{
  "authorization": "b3cd476d-fd53-4333-81ed-fd72bebb615e",
  "user": {
    "_cls": "User.Worker",
    "id": "56a052295de13123c8f1f072",
    "active": true,
    "username": "manager",
    "name": "Ильдар Манзуров (Бариста)",
    "first_name": "Ильдар",
    "last_name": "Манзуров",
    "role": "manager",
    "job_title": "Бариста",
    "image": null,
    "units": []
  },
  "franchising_enabled": false,
  "shift": {
    "id": "59acbf5bed98749cb26aca15",
    "user": {
      "_cls": "User.Worker",
      "id": "56a052295de13123c8f1f072",
      "active": true
    },
    "unit": {
      "id": "56704d20ec27b52d2ad573f9"
    },
    "open": "2017-11-25T05:50:03.007000+03:00",
    "open_comment": null,
    "close": null,
    "close_comment": null,
    "profit": {
      "cash": 10390,
      "cashless": 6350,
      "income": 0
    },
    "balance": 507890
  }
}

Если у пользователя есть открытая смена, то можно переходить к оформлению заказов.

Открытие смены

Минимальный набор полей, необходимый для открытия смены - идентификатор точки, на которой работает сотрудник. Для его получения необходимо после авторизации пользователя выполнить запрос на API GET /api/unit. Однако, следует учитывать следующие особенности:

  1. Сотрудники с ролью manager могут открывать смену только на точке, на которой разрешены продажи. Для фильтрации таких точек необходимо использовать GET-параметр can_sales со значением true.

  2. Если ключ units (user.units в API сессии) является непустым списком, то пользователь может открывать смену только в точках из этого списка. Корректное значение ключа units - List[ObjectId].

  3. Если в списке доступных точек только одно значение, то нет смысла выполнять запрос на получение списка точек. Это значение можно сразу передавать в запросе открытия смены.

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

curl "http://demo.idealist.one/api/unit?can_sales=true" \
     --header "Authorization: Bearer b3cd476d-fd53-4333-81ed-fd72bebb615e"

[
  {
    "id": "56985551ec27b52aed1580df",
    "changed": "2016-01-15T02:11:29+00:00",
    "active": true,
    "editable": true,
    "readable": true,
    "accessible": true,
    "name": "Династия",
    "location": null,
    "can_sales": true,
    "confirmed": true,
    "operation": null,
    "city": "Москва",
    "address": "ул. Заводская",
    "acquiring": false,
    "menus": [],
    "default_cash": {
      "id": "55c21a7a8ea6c632e51376f2"
    },
    "default_cashless": {
      "id": "55c3033b8ea6c632d1137898"
    },
    "use_remote_printer": false
  }
]

Одновременно с выбором точки необходимо получить настройки, используя API GET /api/settings

Получение дополнительных настроек

curl "http://demo.idealist.one/api/settings" \
     --header "Authorization: Bearer b3cd476d-fd53-4333-81ed-fd72bebb615e"

{
  "allow_sell_items": true,
  "default_payment_page": "ligth",
  "close_shift_list": [
    "test2"
  ],
  "open_shift_list": [
    "test1",
    "test2"
  ],
  "use_check_printer": true,
  "use_constructor": false,
  "currency": {
    "symbol": "₽",
    "name": "Российский рубль",
    "ISO": "RUB"
  },
  "hide_foreign_sale": true,
  "default_search": "by_phone",
  "allow_anonymous_clients": true,
  "timezone": "Europe/Moscow",
  "wish_list": [],
  "default_code": "+7",
  "local_offset": "+05:00",
  "default_sales_tab": "final",
  "hide_favorites": false,
  "allow_custom_discount": false,
  "ask_cashbox_balance": true,
  "ask_verification_terminal": true,
  "check_close_shift_list": true,
  "check_open_shift_list": true,
  "need_encashment": true,
  "ask_shift_duration": false
}

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

  1. ask_cashbox_balance - флаг необходимости ввода баланса кассы

  2. check_open_shift_list - флаг необходимости отображения чек-листа открытия смены

  3. open_shift_list - чек-лист открытия смены

Чек-лист открытия смены является формальной необходимостью и не влияет на данные, необходимые для открытия смены. Пункты из этого списка нужно показать пользователю и (в зависимости от интерфейса) не допускать дальнейших действий, пока он не отметит все как выполненные.

Флаг ask_cashbox_balance влияет на необходимость передачи ключа cash_open_condition. Значение этого ключа при открытии смены - баланс наличной кассы. Если флаг выставлен в true, предполагается, что пользователь пересчитает кассу при открытии и введенный баланс будет передан в ключе cash_open_condition. Отсутствие ключа в данных, либо передача null будут означать то, что пользователь не выполнил этой операции.

Поля открытия смены

Поле

Обязательное

Тип

Описание

unit

Почти 1

ObjectId

Точка, на которой открывается смена

open_comment

Нет

str

Комментарий открытия смены

cash_open_condition

Нет

number

Баланс кассы при открытии

Запрос открытия смены

curl "http://demo.idealist.one/api/workshift" \
     --header "Authorization: Bearer b3cd476d-fd53-4333-81ed-fd72bebb615e"
     -d '{"unit":"56985551ec27b52aed1580df","cash_open_condition": 1500}'

{
  "id": "5a1d310050f9046a65f826c6",
  "user": {
    "_cls": "User.Worker",
    "id": "56a052295de13123c8f1f072",
    "active": true,
    "username": "manager",
    "name": "Ильдар Манзуров (Бариста)",
    "first_name": "Ильдар",
    "last_name": "Манзуров",
    "role": "manager",
    "job_title": "Бариста",
    "image": null,
    "units": []
  },
  "unit": {
    "id": "56985551ec27b52aed1580df",
    "changed": "2016-01-15T02:11:29+00:00",
    "active": true,
    "editable": true,
    "readable": true,
    "accessible": true,
    "name": "Династия",
    "location": null,
    "can_sales": true,
    "confirmed": true,
    "operation": null,
    "city": "Москва",
    "address": "ул. Заводская",
    "acquiring": false
  },
  "open": "2017-11-28T12:48:48.602644+03:00",
  "open_comment": null,
  "close": null,
  "close_comment": null,
  "profit": {
    "cash": 0,
    "cashless": 0,
    "income": 0
  },
  "balance": 796260,
  "duration": null,
  "cash_open_condition": 1500,
  "cash_close_condition": null,
  "encashment": null,
  "verification_terminal": null,
  "open_fix": {
    "id": "5a1d31003bba84000cc0d1f4",
    "type": "fix",
    "subtype": null,
    "desc": "Фикс открытия смены",
    "user": null,
    "contractor": null,
    "transactions": [
      {
        "_cls": "Transaction",
        "uuid": "bb9af575-7237-4351-8af2-d218d3fe6916",
        "amount": null,
        "balance": 1500,
        "date": "2017-11-28T12:48:48.602644+03:00",
        "change": "edit",
        "cashbox": {
          "id": "55c21a7a8ea6c632e51376f2"
        },
        "user": {
          "id": "56a052295de13123c8f1f072"
        }
      }
    ],
    "date": "2017-11-28T12:48:48.644611+03:00"
  },
  "close_fix": null,
  "encashment_action": null,
  "verification_terminal_action": null
}

Закрытие смены

По завершении работы пользователь может закрыть смену. Для этого необходимо использовать API POST /api/workshift/current/close. По аналогии с открытием, в настройках присутствуют поля, которые влияют на необходимые для передачи данные:

  1. ask_cashbox_balance - флаг необходимости ввода баланса кассы

  2. ask_verification_terminal - флаг необходимости сверки терминала

  3. check_close_shift_list - флаг отображение чек-листа закрытия смены

  4. close_shift_list - чек-лист закрытия смены

Как и при открытии смены, чек-лист не влияет на данные.

При установленном флаге ask_cashbox_balance необходимо передать ключ cash_close_condition с балансом наличной кассы на момент закрытия смены.

Ключ ask_verification_terminal требует 2 передачи значения сверки терминала в ключе verification_terminal.

Ключ need_encashment требует 2 установки ключа encashment с суммой инкассации при закрытии смены.

Ключ ask_shift_duration требует 2 установки ключа duration с длительностью смены в минутах

Поля открытия смены

Поле

Обязательное

Тип

Описание

encashment

Нет

number

Сумма инкассации

verification_terminal

Нет

number

Сумма операций по терминалу

cash_close_condition

Нет

number

Баланс кассы при закрытии

comment

Нет

str

Комментарий закрытия смены

duration

Нет

number

Длительность смены в минутах

Запрос закрытия смены

curl "http://demo.idealist.one/api/workshift/current/close" \
     --header "Authorization: Bearer b3cd476d-fd53-4333-81ed-fd72bebb615e" \
     -d '{"cash_close_condition":100,"verification_terminal":2000,"encashment":200}'

{
  "id": "5a1d310050f9046a65f826c6",
  "user": {
    "_cls": "User.Worker",
    "id": "56a052295de13123c8f1f072",
    "active": true,
    "username": "manager",
    "name": "Ильдар Манзуров (Бариста)",
    "first_name": "Ильдар",
    "last_name": "Манзуров",
    "role": "manager",
    "job_title": "Бариста",
    "image": null,
    "units": []
  },
  "unit": {
    "id": "56985551ec27b52aed1580df",
    "changed": "2016-01-15T02:11:29+00:00",
    "active": true,
    "editable": true,
    "readable": true,
    "accessible": true,
    "name": "Династия",
    "location": null,
    "can_sales": true,
    "confirmed": true,
    "operation": null,
    "city": "Москва",
    "address": "ул. Заводская",
    "acquiring": false
  },
  "open": "2017-11-28T12:48:48.602000+03:00",
  "open_comment": null,
  "close": "2017-11-28T13:20:51.797342+03:00",
  "close_comment": null,
  "profit": {
    "cash": 0,
    "cashless": 0,
    "income": 0
  },
  "balance": 1500,
  "duration": 32,
  "cash_open_condition": 1500,
  "cash_close_condition": 100,
  "encashment": 200,
  "verification_terminal": 2000,
  "open_fix": {
    "id": "5a1d31003bba84000cc0d1f4",
    "type": "fix",
    "subtype": null,
    "desc": "Фикс открытия смены",
    "user": null,
    "contractor": null,
    "transactions": [
      {
        "_cls": "Transaction",
        "uuid": "bb9af575-7237-4351-8af2-d218d3fe6916",
        "amount": -22085647,
        "balance": 1500,
        "date": "2017-11-28T12:48:48.602000+03:00",
        "change": null,
        "cashbox": {
          "id": "55c21a7a8ea6c632e51376f2"
        },
        "user": {
          "id": "56a052295de13123c8f1f072"
        }
      }
    ],
    "date": "2017-11-28T12:48:48.644000+03:00"
  },
  "close_fix": {
    "id": "5a1d38833bba84001228b655",
    "type": "fix",
    "subtype": null,
    "desc": "Фикс закрытия смены",
    "user": null,
    "contractor": null,
    "transactions": [
      {
        "_cls": "Transaction",
        "uuid": "5d9125aa-35b7-4d67-a5c0-88917c0c612d",
        "amount": null,
        "balance": 100,
        "date": "2017-11-28T13:20:51.848040+03:00",
        "change": "edit",
        "cashbox": {
          "id": "55c21a7a8ea6c632e51376f2"
        },
        "user": {
          "id": "56a052295de13123c8f1f072"
        }
      }
    ],
    "date": "2017-11-28T13:20:51.847925+03:00"
  },
  "encashment_action": {
    "id": "5a1d38833bba84001228b653",
    "type": "transfer",
    "subtype": "Инкассация",
    "desc": "Инкассация во время закрытия смены",
    "user": {
      "_cls": "User.Worker",
      "id": "56a052295de13123c8f1f072",
      "active": true,
      "username": "manager",
      "name": "Ильдар Манзуров (Бариста)",
      "first_name": "Ильдар",
      "last_name": "Манзуров",
      "role": "manager",
      "job_title": "Бариста",
      "image": null,
      "units": []
    },
    "contractor": null,
    "transactions": [
      {
        "_cls": "Transaction",
        "uuid": "51259214-f09f-4cad-ba56-bf5db61f5ea4",
        "amount": -200,
        "balance": null,
        "date": "2017-11-28T13:20:51.797342+03:00",
        "change": "edit",
        "cashbox": {
          "id": "55c21a7a8ea6c632e51376f2"
        },
        "user": {
          "id": "56a052295de13123c8f1f072"
        }
      },
      {
        "_cls": "Transaction",
        "uuid": "f51c8255-c51d-4799-a54a-4d1c46f46971",
        "amount": 200,
        "balance": null,
        "date": "2017-11-28T13:20:51.797342+03:00",
        "change": "edit",
        "cashbox": {
          "id": "5a1d33e13bba84001228b5e9"
        },
        "user": {
          "id": "56a052295de13123c8f1f072"
        }
      }
    ],
    "date": "2017-11-28T13:20:51.797342+03:00"
  },
  "verification_terminal_action": {
    "id": "5a1d38833bba84001228b657",
    "type": "term_fix",
    "subtype": null,
    "desc": "Сверка терминала",
    "user": null,
    "contractor": null,
    "transactions": [
      {
        "_cls": "Transaction",
        "uuid": "755d66a7-369e-4717-b1ce-b333efa171c1",
        "amount": null,
        "balance": null,
        "date": "2017-11-28T13:20:51.878394+03:00",
        "change": "edit",
        "cashbox": {
          "id": "55c3033b8ea6c632d1137898"
        },
        "user": {
          "id": "56a052295de13123c8f1f072"
        }
      }
    ],
    "date": "2017-11-28T13:20:51.871178+03:00"
  }
}
1

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

2(1,2,3)

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