Смена

актуальная

Открыть, закрыть смену и узнать её состояние. На HTTP и TCP это делается по-разному.

Обычно сменой управляет сама касса или кассир. Запросы нужны, если ваша программа ведёт смену сама.

	HTTP	TCP
Путь	отдельный `/gate/shift`	тот же `/gate/receipt-v4`
Операции	`open`, `close`, `state` строчными	`OPEN`, `CLOSE`, `STATE` прописными
Ответ	синхронно, до 30 секунд	через `receipt-status-v4`
Теги документа	по запросу `fullResult: true`	приходят всегда

HTTP

POST/gate/shiftHTTP

Командная строка

curl -X POST 'https://ofd.yaros.kg:8143/ofd-0.0.1/gate/shift' \
  -H 'token: <токен>' -H 'Content-Type: application/json' \
  -d '{ "operation": "open" }'

Поле	Тип	Обяз.	Описание
`operation`	String	да	`open`, `close`, `state` строчными буквами
`fullResult`	Boolean	нет	`true` добавит в `gnsResult` теги документа

В ответе shiftNumber, fdNumber, fpd, rnKKM, fnKKM, при закрытии ещё link на HTML-копию Z-отчёта.

Разные отказы показывают, где остановилось:

`info`	Что произошло
`Operation 'OPEN' not found`	операция написана прописными, здесь нужны строчные
`YaKassa session not Found`, `YaKassa session closed`	обмен на кассе выключен или касса давно не выходила на связь
`YaKassa session not working`	касса не появилась на связи за 30 секунд, команду забрать некому
`time out`	касса приняла команду, но за 30 секунд не ответила
`Смена закрыта`, `Смена уже открыта`, `Смена уже закрыта`	касса отказала: операция невозможна в текущем состоянии смены

TCP

POST/gate/receipt-v4TCP

Отдельной точки входа нет. Операция отправляется как документ, результат забирается обычным receipt-status-v4. Весь протокол тот же, что у чека. Смена по TCP работает с версии кассы 2.2.09.384.

Открыть

curl -X POST 'http://192.168.0.50:8090/gate/receipt-v4' \
  -H 'Content-Type: application/json' \
  -d '{ "id": "<GUID>", "type": "SHIFT", "operation": "OPEN" }'

Результат

curl -X POST 'http://192.168.0.50:8090/gate/receipt-status-v4' \
  -H 'Content-Type: application/json' \
  -d '{ "id": "<GUID>" }'

Поле	Тип	Обяз.	Описание
`id`	String	да	GUID операции, один на операцию
`type`	String	нет	`SHIFT`. Лучше указывать явно
`operation`	String	да	`OPEN`, `CLOSE`, `STATE` прописными

Позиции не нужны, остальные поля документа к смене отношения не имеют.

Ответ на статус	Что означает	Что делать
`OK`, «Операция со сменой выполнена»	смена открыта или закрыта	завершить операцию
`PROCESSING`	операция идёт	спросить через 1–2 секунды
`ERROR`, «Смена закрыта» и подобные	операция невозможна в текущем состоянии	показать причину, не повторять вслепую
`ERROR`, «Документ не найден. Сначала отправьте документ»	неизвестный `id` или результат вытеснен	проверить состояние запросом `STATE`

Что приходит при OK

Поле	Что это
`fdNumber`	номер фискального документа, тег 1040
`shiftNumber`	номер смены, тег 1038
`fpd`	фискальный признак, тег 1077
`gnsDate`	дата и время документа
`rnKKM`, `fnKKM`	регистрационный номер и номер фискального модуля
`gnsResult`	все теги документа: `{"fields": { … }}`

В gnsResult.fields лежит всё для собственного Z-отчёта: итоги по операциям (тег 1194), наличные и безнал, число чеков, разбивка по ставкам НДС (1006) и НСП (1007), кассир (1021), ИНН (1018). При STATE то же по X-отчёту, без создания документа.

При STATE поля fdNumber, fpd и gnsDate относятся к последнему документу, а не к самому запросу: X-отчёт это снимок итогов, а не подписанный документ. На кассе с SAM-картой fpd и gnsDate при STATE не приходят вовсе.

У документа смены нет qr. link на копию Z-отчёта приходит только по HTTP. Свой Z-отчёт касса печатает в любом случае.

Сколько ждать

Опрашивайте статус раз в 1–2 секунды. Открытие занимает секунды. Закрытие на кассе с SAM-картой дольше: карта считает итоги, на отдельных терминалах одна команда идёт десятки секунд. Разумный запас: несколько минут.

Типовые сценарии

Открыть смену перед началом работы
  POST receipt-v4         {"id":"<GUID-1>","type":"SHIFT","operation":"STATE"}
  POST receipt-status-v4  {"id":"<GUID-1>"}   → ERROR «Смена закрыта»
  POST receipt-v4         {"id":"<GUID-2>","type":"SHIFT","operation":"OPEN"}
  POST receipt-status-v4  {"id":"<GUID-2>"}   → OK

Закрыть смену в конце дня
  POST receipt-v4         {"id":"<GUID-3>","type":"SHIFT","operation":"CLOSE"}
  POST receipt-status-v4  {"id":"<GUID-3>"}   → PROCESSING … → OK

Проверять смену перед каждым чеком не нужно. Если смена закрыта, а автооткрытие на кассе выключено, чек завершится ошибкой «Смена закрыта. Откройте смену». Откройте смену и повторите чек с тем же id. При включённом автооткрытии касса откроет смену сама.

Перед закрытием дождитесь завершения всех документов и всех внесений и изъятий: иначе операция может не попасть в итоги смены.

Смена старше суток считается устаревшей: документ завершится ошибкой Смена устарела, если касса не открыла новую сама.