Обмен через кассу: два канала

актуальная

Ваша программа отправляет документ, касса пробивает чек и принимает оплату на своём терминале. Связь через сервер или напрямую.

Физический терминал обслуживает сама YaKassa: запускает банковскую операцию, печатает чек, отправляет его в ОФД. Ваша программа только передаёт документ и получает результат. Формат документов на обоих каналах один и тот же.

HTTP, через сервер

 Ваша система              Сервер YaKassa               Касса
      │  POST /gate/receipt-v4  │                          │
      │  заголовок token ─────► │ документ ждёт в сессии   │
      │  ◄── OK, документ принят│ ◄── касса сама опрашивает│
      │                         │     сервер каждую секунду│ чек
      │  POST /gate/receipt-status-v4                      │ оплата
      │  ─────────────────────► │ ◄── результат от кассы ──│
      │  ◄── PROCESSING или OK  │                          │

Касса сама ходит на сервер, поэтому её не нужно публиковать в сеть. Ваша система общается только с сервером.

TCP, напрямую в кассу

 Ваша система                                     Касса
      │  POST http://<ip кассы>:8090/gate/receipt-v4  │
      │  ───────────────────────────────────────────► │ чек
      │  ◄── OK, документ принят                      │ оплата
      │  POST /gate/receipt-status-v4                 │
      │  ───────────────────────────────────────────► │
      │  ◄── PROCESSING или OK                        │

В кассе работает маленький HTTP-сервер. Чек в ОФД уходит самой кассой, как при обычной продаже.

Сравнение

	HTTP	TCP
Кто кого зовёт	вы и касса зовут сервер	вы зовёте кассу
Интернет	нужен у вас и у кассы	нужна только локальная сеть
Токен	да, заголовок `token`	нет
Касса видна в сети	не нужно	нужно, по IP и порту
Где хранится результат	в базе сервера, доступен и через сутки	в памяти приложения: 100 документов, не дольше суток
Задержка доставки документа	до 1–2 секунд	сразу
Приложение свёрнуто	не работает	не работает
Смена	`/gate/shift`	документом в `receipt-v4`
Внесение и изъятие	`/gate/cash`	нет
Оплата картой без чека	`fiscal: false`	`fiscal: false` и `/payment`

Для облачных систем и удалённых точек берите HTTP. Для кассового ПО в том же магазине, весов, киоска берите TCP. Каналы можно держать включёнными одновременно.

Подготовка кассы

Что	Где	Примечание
Включить HTTP	Настройки → Обмен → Обмен по http	появится «Номер для обмена», это и есть токен
Включить TCP	Настройки → Обмен → TCP сервер	порт указан в заголовке настройки, обычно `8090`, адрес кассы показан под ней
Проверить связь	правый верхний угол экрана	зелёные `Обмен` и `TCP`, красная плашка означает ошибку, нажмите для описания
Открыть смену	экран кассы или запрос	иначе ошибка «Смена закрыта. Откройте смену»

Настройки обмена относятся к конкретному устройству. Заменили кассу или сеть: заново проверьте IP, порт и токен.

Токен создаётся на устройстве при каждом включении обмена. Выключили и включили: токен другой, старый больше не действует.
Приложение должно быть на экране. Опрос сервера и TCP-сервер останавливаются, когда приложение уходит в фон. Включите режим «не гасить экран».
IP кассы закрепите на маршрутизаторе. При смене адреса обмен по TCP молча перестанет работать.
Настройки Автоматическая обработка и Автоматическое завершение относятся только к Intent. Документы по HTTP и TCP всегда обрабатываются автоматически.