Адреса и общие правила

Контуры, токены, заголовки, деньги и коды ответа: всё, что одинаково для всех способов.

Адреса

Контур	База	Для чего
Рабочий	`https://ofd.yaros.kg:8143/ofd-work-0.0.1`	настоящие фискальные чеки
Демо	`https://ofd.yaros.kg:8143/ofd-0.0.1`	проба и отладка
Запасной домен	`https://ofd2.yaros.kg:8143` с теми же путями	если основной недоступен
TCP	`http://<IP кассы>:<порт>`, порт по умолчанию `8090`	напрямую в кассу по локальной сети

Документ, отправленный в демо, в рабочий ОФД не попадёт. Смена контура меняет только базовый путь, но касса подключена к одному контуру.

Проверить, что сервер отвечает, можно без токена:

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

curl 'https://ofd.yaros.kg:8143/ofd-0.0.1/gate/ping'

Токены

Токенов два вида, и они не взаимозаменяемы.

	Токен обмена	Токен V2
Где нужен	обмен через кассу по HTTP	фискализация без кассы
Вид	число: `123456789`	UUID
Откуда	экран кассы, Настройки → Обмен, строка «Номер для обмена»	запрос `get-token`
Как меняется	при каждом включении обмена на кассе	при каждом запросе `get-token`, не чаще раза в 5 минут
Заголовок	`token: <токен>`	`token: <токен>`

Токен передаётся только в заголовке: это не поле JSON, не логин и не Basic-авторизация. Храните его в настройках своей системы, а не в коде. По TCP токен не нужен, заголовок игнорируется.

Запрос

Тело запроса и ответа: JSON в UTF-8.
Заголовок Content-Type: application/json обязателен. Без него сервер ответит 415.
Без заголовка token или с неверным JSON сервер ответит 400.
Дробная часть числа пишется через точку: 100.50, 6.1.

Деньги

Где	Единицы
`price`, `cash_sum`, `cashless_sum`, `amount` в чеках	сомы с дробной частью
`amount` во внесении и изъятии	единицы валюты: `500` это 500 долларов, не центов
блок `receipt` в оповещениях	тыйыны: `12500` это 125 сом
теги налоговой в `gnsResult`	тыйыны

price принимает до 4 знаков после точки. Считайте суммы в целых тыйынах или в Decimal, а не в float: 0.1 + 0.2 в double даст расхождение со сверкой сумм.

Уникальный id

Поле id документа и guid операции с наличными это ключ от дублей. Генерируйте GUID один раз на операцию и храните его, пока операция не завершится. Повтор с тем же ключом безопасен, с новым это вторая операция.

Коды ответа

Сервер отвечает HTTP 200 и на успех, и на отказ по существу. Решение принимайте по полю status в теле, а не по коду HTTP.

Код	Когда	Тело
200	запрос разобран, в том числе отказ	JSON с `status`
400	нет заголовка `token`, неверный JSON, не хватает обязательного поля	служебный JSON сервера с полями `timestamp`, `status`, `error`, `path`
404	такого метода нет	служебный JSON сервера
415	нет `Content-Type: application/json`	служебный JSON сервера

Отсутствующее поле и null считайте одним и тем же: сервер не отправляет поля со значением null. Незнакомые поля пропускайте, в новых версиях их может стать больше.

Что писать в журнал

Записывайте по каждой операции id, канал, метод, время, код HTTP, status, info, число попыток и итоговые реквизиты. Не записывайте пароль, токен целиком и полный номер карты. При обращении в поддержку называйте id документа: по нему находят запрос.