Принимайте платежи и считайте выручку ЮKassa прямо в чате

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

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

Агент не только читает, но и принимает платежи: создаёт платёж и отдаёт покупателю ссылку на оплату, подтверждает или отменяет двухстадийный платёж, оформляет возврат, регистрирует чек по 54-ФЗ, в том числе второй чек, выставляет счёт и списывает автоплатёж по сохранённому способу оплаты. Каждое такое действие владелец магазина подтверждает в карточке согласия. Выплаты через API недоступны: «ЮKassa Выплаты» это отдельный продукт со своими agent_id и ключом.

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