Руководство July 22, 2026

Как восстановить пропущенные Webhook о покупках в LINE MINI App: сверка за 7 дней

Чтобы восстановить пропущенный Webhook о покупке в LINE MINI App, запросите официальную историю событий LINE в пределах семи дней, при пагинации не меняйте исходный временной диапазон и фильтры, а каждое возвращённое событие purchaseComplete передайте в идемпотентный handler с ключом orderId. Успешное резервирование покупки не доказывает, что платёж завершён. Endpoint истории служит источником для восстановления, но не заменяет мониторинг Webhook в реальном времени.

Главное

История событий LINE охватывает доставки Webhook за последние семь дней и возвращает до 100 записей на страницу.
status=FAILED означает ошибку доставки Webhook, а не неудачный платёж покупателя.
Сохраняйте orderId при резервировании покупки, затем используйте его для дедупликации как live-событий, так и восстановленных событий purchaseComplete.
Отделяйте восстановление платежей от маршрутизации сообщений клиентов. У этих контуров разные типы событий, учётные данные, подписи и ответственные команды.

Почему успешное резервирование ещё не означает завершённую покупку

Встроенная покупка в LINE MINI App проходит по официальному многоэтапному процессу. Сначала ваш сервер резервирует покупку запросом POST https://api.line.me/iap/v1/product/reserve. LINE возвращает orderId, однако пользователь всё ещё может закрыть приложение, отменить операцию в магазине приложений, потерять соединение или не завершить оплату. Поэтому руководство по интеграции LINE предписывает выдавать цифровой объект только после получения Webhook о завершённой покупке.

Эта граница разделяет проверку сбоя на четыре отдельных вопроса:

Вопрос	Надёжное подтверждение
Успешен ли запрос резервирования?	Ответ reserve, сохранённый `orderId` и `x-line-request-id`
Завершена ли покупка?	Событие `purchaseComplete` или официальный результат сверки
Получил ли ваш endpoint live-доставку?	Журнал исходного запроса и запись обработки Webhook
Выдал ли бизнес-handler право ровно один раз?	Идемпотентная запись с ключом `orderId`

В существующем руководстве по комиссиям LINE MINI App и Webhook поддержки объясняется, почему платёжные события и сообщения клиентов должны относиться к разным системам. Этот регламент рассматривает следующий уровень: платёжный Webhook должен был прийти, но endpoint был недоступен или обработка завершилась ошибкой.

Как восстановить пропущенные Webhook о покупках в LINE MINI App за 7 дней

1. Обнаружьте пробел до истечения семидневного окна

При резервировании покупки сохраняйте следующие значения:

внутренний checkout ID;
orderId от LINE;
заголовок ответа x-line-request-id;
время резервирования и ожидаемый продукт;
признак применения события purchaseComplete.

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

2. Запросите фиксированное окно восстановления

Официальный справочник API LINE MINI App описывает следующий endpoint восстановления:

curl --get "https://api.line.me/iap/v1/webhook/events" \
  -H "Authorization: Bearer ${LINE_CHANNEL_ACCESS_TOKEN}" \
  --data-urlencode "startEpochSeconds=1784678400" \
  --data-urlencode "endEpochSeconds=1784700000" \
  --data-urlencode "pageSize=100" \
  --data-urlencode "status=FAILED"

Временные метки выше показывают конкретный пример окна 22 июля 2026 года; не копируйте эти значения в production. Сформируйте epoch-секунды UTC по началу и окончанию инцидента. Используйте status=FAILED, чтобы найти доставки, которые LINE не смогла завершить, либо исключите status, если сверяете все доставки в выбранном окне. SUCCESS и FAILED описывают статус доставки, а не результат покупки.

3. Не меняйте параметры запроса при пагинации

Результаты упорядочены по времени, когда LINE начала отправлять каждый Webhook. Страница содержит не более 100 записей и может включать nextCursor. Для всех следующих страниц сохраняйте startEpochSeconds, endEpochSeconds, pageSize и status; меняйте только cursor.

Этот пример на Node.js явно фиксирует данную границу:

const baseUrl = "https://api.line.me/iap/v1/webhook/events";
const fixedQuery = {
  startEpochSeconds: "1784678400",
  endEpochSeconds: "1784700000",
  pageSize: "100",
  status: "FAILED",
};

let cursor;

do {
  const query = new URLSearchParams(fixedQuery);
  if (cursor) query.set("cursor", cursor);

  const response = await fetch(`${baseUrl}?${query}`, {
    headers: { Authorization: `Bearer ${process.env.LINE_CHANNEL_ACCESS_TOKEN}` },
  });

  if (!response.ok) {
    throw new Error(`LINE event history failed: ${response.status}`);
  }

  const page = await response.json();
  for (const record of page.events) {
    if (record.event.type === "purchaseComplete") {
      await applyPurchaseOnce(record.event.orderId, record.event);
    }
  }

  cursor = page.nextCursor ?? undefined;
} while (cursor);

applyPurchaseOnce — граница вашей бизнес-транзакции. В одной атомарной операции handler должен добавить идемпотентную запись и выдать цифровой объект либо ничего не менять, если тот же orderId уже применён. Один Webhook может доставляться несколько раз, поэтому рекомендации по разработке встроенных покупок LINE прямо советуют использовать orderId, чтобы исключить повторную выдачу.

4. Сверьте историю с live-обработкой

Не создавайте отдельный контур выдачи прав только для восстановления. Преобразуйте восстановленное событие в ту же внутреннюю команду, которую использует live-Webhook, и дополнительно запишите источник line_event_history. Затем сравните:

зарезервированные orderId без завершённого внутреннего состояния;
журналы live-Webhook;
записи истории для фиксированного окна инцидента;
идемпотентные записи и изменения выданных прав.

Ответ истории получают с помощью channel access token. Это не исходная HTTP-доставка, поэтому не ожидайте в нём оригинальный заголовок x-line-signature. Продолжайте проверять этот заголовок для live-Webhook: LINE вычисляет HMAC-SHA256 digest от raw request body с помощью channel secret и кодирует подпись в Base64.

5. Завершите инцидент по измеримому контрольному состоянию

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

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

Где применим UnifyPort, а где нет

UnifyPort не резервирует покупки LINE MINI App, не подтверждает платежи магазина приложений, не восстанавливает платёжные события LINE, не выдаёт цифровые объекты и не выполняет требования проверки LINE. За все эти задачи отвечает официальный процесс встроенных покупок LINE.

UnifyPort применим, когда следующим событием становится обычное сообщение клиента. Например, покупатель обращается после оплаты, потому что цифровой объект не появился. Поддерживаемый аккаунт LINE может доставить такой диалог как нормализованное событие message.received. Если у Webhook endpoint UnifyPort задан signing_secret, доставка использует X-Device-Timestamp и X-Device-Signature. Это отдельная схема подписи, не связанная с x-line-signature платёжного Webhook LINE.

Подробное описание retry и идемпотентности на стороне сообщений клиентов приведено в материале Защита Webhook HMAC от повторного воспроизведения: временные метки, retry и идемпотентность. Не объединяйте два handler, даже если в итоге они обновляют одну систему поддержки или заказов.

Ограничения и компромиссы

Официальный API истории — правильный путь восстановления Webhook покупок LINE MINI App. Неофициальный интерфейс не может продлить срок хранения или восстановить платёжные записи платформы.
Семидневная ретроспектива не заменяет долгосрочный реестр. Храните собственные записи резервирований, событий, выданных прав и взаиморасчётов.
status=FAILED сужает выборку до ошибок доставки, но может пропустить доставку, которую endpoint принял, а затем не смог обработать. Если точка отказа находилась в приложении, а не в transport, выполняйте более широкую сверку.
Встроенные покупки по-прежнему доступны для японского рынка и требуют проверки MINI App. До проектирования платёжного процесса подтвердите актуальные критерии доступа; более раннее решение описано в чек-листе верифицированных и неверифицированных MINI App.

FAQ

За какой период можно получить историю Webhook покупок LINE MINI App?

Официальный endpoint принимает запросы истории Webhook за последние семь дней. Запускайте восстановление до истечения этого срока и ведите собственный постоянный реестр для более старых инцидентов.

Означает ли `status=FAILED`, что платёж клиента не прошёл?

Нет. Это значит, что LINE не смогла доставить Webhook. Состояние покупки и состояние доставки различаются; для сверки заказа используйте возвращённое событие вместе с записями резервирования и выдачи прав.

Можно ли выдать цифровой объект после ответа `200` от endpoint резервирования?

Нет. Успешное резервирование не гарантирует завершения покупки. Выдавайте цифровой объект только после обработки события purchaseComplete, обеспечив идемпотентность по orderId.

Может ли восстановление из истории обработать одну покупку дважды?

Запрос может вернуть событие, которое уже применил live-handler. Оба пути должны вызывать один атомарный идемпотентный handler с ключом orderId, тогда вторая попытка не изменит состояние.

Подпись LINE `x-line-signature` совпадает с подписью Webhook UnifyPort?

Нет. LINE подписывает raw body платёжного Webhook и отправляет подпись в Base64. При включённом signing_secret UnifyPort подписывает timestamp вместе с raw body и отправляет собственные заголовки timestamp и подписи. Проверяйте каждый протокол независимо.

Следующий шаг

Реализуйте и протестируйте запрос восстановления по официальному справочнику API LINE MINI App, затем настройте его запуск в пределах семидневного срока хранения. Если вам отдельно требуется принимать обычные сообщения поддержки LINE, после стабилизации платёжного контура подключите его по руководству авторизации LINE в UnifyPort.

Источники

Официальные сведения проверены 22 июля 2026 года.