Обмен валюты без кассы

актуальная

Продажа и покупка валюты через receipt-v2 для обменных пунктов. Физическая касса не нужна.

Что умеет

Продажа валюты клиенту и покупка у клиента.
Возврат по каждой из этих операций.
Внесение, изъятие и остаток по валютам смены.

Чек пробивается в валютном виде: валюта, курс, сумма в валюте и итог в сомах. В ГНС уходит обычный фискальный документ: тип продажа или покупка, наименование USD / Курс 87.5, сумма в сомах. Токен, адреса и общие правила те же, что в основном разделе.

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

Получить токен.
Внести валюту: cash-v2 с ADD. Смена откроется сама.
Пробивать чеки обмена: receipt-v2.
Смотреть остаток.
Изымать наличные: DEL, а когда забрали всё, RESET.
В конце дня закрыть смену: shift-v2 с close.

Баланс смены

Операция	Что должно быть на балансе
Продажа валюты `INCOME`	достаточно валюты
Покупка валюты `EXPENDITURE`	достаточно сомов
Возврат продажи `INCOME_RETURN`	достаточно сомов
Возврат покупки `EXPENDITURE_RETURN`	достаточно валюты

Если не хватает, чек не пробивается: ошибка На балансе недостаточно : USD. Это обычный отказ, а не сбой связи: повторять без пополнения бессмысленно.

Не путайте с get-balance: там лицевой счёт кассы, здесь наличная валюта за смену.

Чек

POST/gate/receipt-v2HTTPтокен V2

Валютным чек делает поле currency в позиции. Других признаков не нужно.

Продажа

curl -X POST 'https://ofd.yaros.kg:8143/ofd-0.0.1/gate/receipt-v2' \
  -H 'Content-Type: application/json' -H 'token: <токен>' \
  -d '{ "id": "<GUID>", "operation": "INCOME",
        "products": [ { "id": "1", "currency": "USD", "price": 87.50, "quantity": 100 } ] }'

Покупка

curl -X POST 'https://ofd.yaros.kg:8143/ofd-0.0.1/gate/receipt-v2' \
  -H 'Content-Type: application/json' -H 'token: <токен>' \
  -d '{ "id": "<GUID>", "operation": "EXPENDITURE",
        "products": [ { "id": "1", "currency": "USD", "price": 86.00, "quantity": 50 } ] }'

Возврат

curl -X POST 'https://ofd.yaros.kg:8143/ofd-0.0.1/gate/receipt-v2' \
  -H 'Content-Type: application/json' -H 'token: <токен>' \
  -d '{ "id": "<GUID>", "operation": "INCOME_RETURN", "fd_number": "5833",
        "products": [ { "id": "1", "currency": "USD", "price": 87.50, "quantity": 100 } ] }'

Продажа 100 USD по курсу 87.50 приносит кассе 8750 сом. Покупка 50 USD по курсу 86.00 забирает 4300 сом. Возврат покупки делается операцией EXPENDITURE_RETURN.

Обмен валюты это наличная операция, поле cashless не используется и на движение по балансу не влияет.

Поле позиции	Тип	Обяз.	Описание
`id`	String	да	идентификатор позиции в вашей базе
`currency`	String	да	код валюты. Именно он делает позицию валютной
`price`	Decimal	да	курс: сомов за единицу валюты
`quantity`	Decimal	да	сумма в валюте
`name`	String	нет	наименование. Без него сервер подпишет сам: `USD / Курс 87.5`
`vat_value`, `st_value`	Decimal	нет	ставки, для обмена обычно `0`, это значение по умолчанию

Ответ как у обычного чека, плюс balance с остатком после чека:

JSON

{
  "id": "07b2f33c-0eaf-4353-abbf-000000000101",
  "status": "OK",
  "qr": "https://…/ticket?date=20261102T183012&type=3&operation_type=1&…",
  "link": "https://ofd.yaros.kg:8143/ofd-0.0.1/gate/get-html-receipt/<id копии>",
  "amount": 8750.00,
  "shiftNumber": "550",
  "receiptNumber": "12",
  "balance": { "KGS": 21250.00, "USD": 400.00 }
}

При повторе с тем же id ответ тот же, что в первый раз, а balance текущий.

Округление и разрядность

Сумма каждой позиции считается отдельно: price × quantity переводится в тыйыны и округляется по правилу «половина вверх». Сумма чека это сумма уже округлённых позиций. Примеры: 0.1235 × 3 = 0.37, 0.125 × 1 = 0.13, 100 × 0.123456 = 12.35.

В price и quantity передавайте не больше 4 знаков после точки. Сервер лишние знаки не отрезает, но на большее гарантий нет.

Коды валют

KGS, USD, EUR, RUB, KZT, UZS, CNY, TRY, AED, GBP, CAD, JPY, KRW, CHF, SAR.

Правила

В одном чеке нельзя смешивать валютные и обычные позиции: для товаров отправляйте отдельный документ.
Курс и сумма строго больше нуля.
Курс задаёте вы.
Нефискальных валютных документов не бывает: на каждый обмен пробивается чек.
Возврат сверяется с чеком-основанием: вернуть можно не больше, чем продано, частями сколько угодно раз.