Считайте выручку, возвраты и чеки ЮKassa прямо в чате

Агент ходит в API ЮKassa версии v3 и читает всё, что относится к приёму платежей: сами платежи и их статусы, возвраты, фискальные чеки и способы оплаты. Первым запросом он спрашивает /me и подтверждает, чей магазин подключён, — чтобы сводка не оказалась про соседний shopId. Дальше считает выручку за период, отмены и возвраты, разбирает конкретный платёж по дате, сумме или статусу и присылает сводку по расписанию.

Возврат в ЮKassa — отдельный объект, связанный с платежом, а не правка самого платежа. Поэтому агент считает выручку как платежи периода за вычетом привязанных к ним возвратов и отдельно помечает те возвраты, что пришли позже исходной оплаты: иначе месяц закрывается красивее, чем он есть. И принятый платёж — ещё не деньги на расчётном счёте: на счёт они приходят выплатой, и увидеть её можно уже в банковском коннекторе.

На этой паре ключей агент работает на чтение: он считает, сопоставляет и объясняет — связывает возвраты с исходными платежами, показывает, по каким способам оплаты их больше всего, и находит платёж, о котором спрашивает бухгалтерия. Выплаты через API недоступны: «ЮKassa Выплаты» — отдельный продукт со своими agent_id и ключом, и агент не делает вид, что может распорядиться деньгами магазина.

Доступ — пара shopId и секретного ключа: она подставляется в каждый запрос и жёстко привязана к одному магазину, поэтому сводка всегда про него, а не про соседний. Подписки на вебхуки этой парой не задаются — уведомления настраиваются в кабинете ЮKassa, — поэтому агент забирает данные сам, по запросу и по расписанию, листая список платежей курсором. Если данных за период нет, он говорит об этом прямо, а не показывает пустую таблицу.