Если возврат уже принят складом или деньги отправлены, а кабинет показывает старый статус, клиент не понимает, что происходит, и обращается в поддержку. Нужно проследить один возврат от учетной системы до API и интерфейса.

Сравните внешний return_id и внутренний ID, последнее событие, состояние в базе и ответ API кабинета. Затем проверьте webhook, очередь и кеш.

Коротко: что сделать

  • Выбрать один возврат с известным статусом
  • Сверить ID во всех системах
  • Проверить последнее событие и HTTP-ответ
  • Проверить worker синхронизации
  • Проверить API кабинета и кеш

Почему возникает проблема

Статус проходит несколько систем, и каждая может использовать свой справочник. Потеря события или неверное сопоставление оставляет кабинет на предыдущем шаге.

  • Webhook не доставлен или отклонен
  • Внешний статус отсутствует в mapping
  • Worker упал и событие попало в DLQ
  • Return ID сопоставлен с другим заказом
  • API отдает кешированную модель
  • Frontend не обновляет состояние после запроса

Пошаговая диагностика

Проверку лучше проводить на одном воспроизводимом примере и фиксировать результат каждого шага. Так можно быстро отделить первопричину от побочных ошибок и не менять несколько компонентов одновременно.

  • Построить timeline статуса по return_id
  • Проверить raw webhook и подпись
  • Проверить очередь и число повторов
  • Сверить mapping внешних и внутренних статусов
  • Вызвать API кабинета напрямую
  • Очистить только релевантный кеш и повторить

Как исправить

Нужно восстановить потерянное событие и сделать обработку устойчивой к повторам и неизвестным статусам.

  • Добавить уникальный external return_id
  • Сохранять журнал переходов статуса
  • Добавить недостающий mapping с контролем допустимых переходов
  • Настроить retries и DLQ
  • Инвалидировать кеш после изменения
  • Добавить периодическую сверку с учетной системой

Как проверить результат

  • Пройти возврат по всем этапам
  • Повторить webhook
  • Проверить неизвестный статус
  • Проверить кабинет сразу и после кеша
  • Проверить уведомление клиента и менеджера

Как не допустить повторения

Клиентский статус должен строиться из надежного журнала переходов и быть объяснимым поддержке.

  • Мониторить зависшие возвраты
  • Показывать дату последнего обновления
  • Версионировать mapping статусов
  • Иметь инструмент безопасной повторной синхронизации

Чего не стоит делать

  • Не менять статус напрямую в интерфейсе
  • Не удалять неизвестные события
  • Не отправлять клиенту успешное уведомление до фиксации статуса
  • Не выполнять replay без идемпотентности

Что подготовить для диагностики

  • Return ID и order ID
  • Ожидаемый и фактический статус
  • Логи webhook/worker
  • Таблица mapping
  • Ответ API кабинета

Частые вопросы

Почему статус обновился в CRM, но не на сайте?

CRM могла не отправить событие, сайт его отклонил или кабинет читает кешированную запись.

Можно ли обновлять статусы по расписанию?

Да, как резервную сверку. Webhook дает скорость, а периодический опрос восстанавливает пропуски.

Нужно ли хранить историю?

Да. Она помогает объяснить переходы, найти потерянное событие и не откатывать статус назад.

Когда стоит обратиться за помощью

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

Итог

Статус возврата нужно проследить по ID через webhook, очередь, базу, API и кеш. Восстановить и автоматизировать эту цепочку можно через @rabotator_support.