Фискализация без кассы: токен и порядок работы

актуальная

Чек формирует сервер, приложение YaKassa и физическая касса не участвуют. Подходит для сайтов, сервисов и обменных пунктов.

Чем отличается от обмена через кассу

	Обмен через кассу v4	Фискализация без кассы V2
Кто пробивает чек	касса	сервер
Нужно устройство	да	нет
Токен	число с экрана кассы	UUID из `get-token`
Оплата картой	на терминале кассы	на вашей стороне, банк не вызывается
Печать	касса	на вашей стороне: придут ссылки `qr` и `link`
Смена	ведёт касса	сервер открывает и закрывает сам или по команде

Операции V2 синхронные: результат приходит в ответе на сам запрос.

Подготовка

Касса должна быть зарегистрирована через ЦТО. После регистрации вы получаете логин, пароль и идентификатор кассы kkmID. Для проб на демо-контуре данные выдаёт поддержка YaKassa.

Адреса

Контур	База
Рабочий	`https://ofd.yaros.kg:8143/ofd-work-0.0.1/gate/`
Демо	`https://ofd.yaros.kg:8143/ofd-0.0.1/gate/`
Запасной домен	`ofd2.yaros.kg:8143`, те же пути

Все запросы только по HTTPS, тело в JSON и UTF-8, заголовок Content-Type: application/json обязателен. Подробнее в общих правилах.

Получить токен

POST/gate/get-tokenбез токена

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

curl -X POST 'https://ofd.yaros.kg:8143/ofd-0.0.1/gate/get-token' \
  -H 'Content-Type: application/json' \
  -d '{ "login": "<логин>", "password": "<пароль>", "kkmID": "<kkmID>" }'

Поле	Тип	Обяз.	Описание
`login`	String	да	логин от ЦТО
`password`	String	да	пароль от ЦТО
`kkmID`	String	да	идентификатор кассы

Успех

{ "status": "OK", "info": "", "token": "00000000-1111-2222-3333-444444444444" }

Ошибка

{ "status": "ERROR", "info": "ККМ не найден с id : 65f1234567890abcdef12345" }

Как устроен токен:

Действует до получения следующего: новый запрос отменяет прежний токен.
Запрашивать чаще одного раза в 5 минут нельзя, ответ Токен можно запрашивать не чаще чем раз в 5 минут.
Рекомендуем обновлять раз в день. Храните токен у себя и не запрашивайте его перед каждым чеком.
Передаётся в заголовке token во всех запросах ниже.
Если тариф не оплачен, токен сбрасывается: после оплаты получите новый.

Порядок работы

Получить токен и сохранить его.
Если ведёте обмен валюты, внести валюту: cash-v2.
Пробивать чеки: receipt-v2. Смена откроется сама.
В конце дня закрыть смену: shift-v2. В ответе придёт ссылка на Z-отчёт.

Баланс лицевого счёта

GET/gate/get-balance/{kkmID}без токена

Состояние оплаты тарифа кассы. Не путать с остатком наличных. Ответ обычным текстом, а не JSON: баланс, срок оплаты, лицевой счёт и адрес.

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

curl 'https://ofd.yaros.kg:8143/ofd-0.0.1/gate/get-balance/<kkmID>'

Если касса не найдена, придёт текст ККМ не найден по id …. Это удобно показывать человеку, но разбирать такой ответ программой не стоит.