База знаний EMS-платформы PlatParts Руководство по настройке EMS-платформы PlatParts

Хуки и события

На этой странице 10

Хуки и события платформы

Имена: домен.сущность.действие. Payload — immutable snapshot (массив), без моделей Eloquent.

Где смотреть доставку

  • Модули интеграций → Очередь хуков модулей — статус handler‑доставки
  • storage/logs/integrations.log при INTEGRATIONS_DEBUG=true

Подписка в модуле

modules/Integrations/{Code}/hooks.php:

php
return [
    'order.created' => \Modules\Integrations\MyCrm\Handlers\OrderCreatedHandler::class,
];

Обработчик:

php
public function handle(IntegrationHookContext $context): void
{
    $payload = $context->payload;
    $hook = $context->hook;
    $pickupPointId = $context->pickupPointId;
}

Фаза P1 — заказы и пользователи

Хук Когда Основные поля payload
order.created После создания заказа id, user_id, pickup_point_id, status_id, status_code, status_semantic, total, items[], created_at
order.updated Смысловое изменение заказа (не touch()) те же + updated_at
order.status_changed Смена status_id после commit + previous_status_*, status_locked
order.item_status_changed Смена статуса позиции после commit id, order_id, product_name, status_code, previous_*, status_locked
order.cancelled Статус заказа с действием «отмена» + cancelled_at (ISO8601)
user.registered Регистрация после commit id, email, phone, name, pick_up_point_id
user.updated Изменение профиля те же + updated_at

Позиция в order.*.items[]

Поле Описание
id ID позиции
product_name Название
quantity, price Количество, цена (руб.)
status_id, status_code, status_semantic Статус позиции

Фаза P1.5 — оплаты, документы, организации

Хук Payload (кратко)
payment.created id, order_id, amount, status, method
payment.paid Оплата подтверждена
payment.failed Отклонена / отменена
payment.refunded Возврат
document.issued id, order_id, type, number, payload
document.cancelled Документ архивирован
organization.created, organization.updated id, name, inn, kpp

Фаза P2+

Хук Статус
integration.sync_requested Ручной/API запуск синха модуля
product.*, cart.abandoned По мере внедрения в ядре

integration.sync_requested вызывается, в том числе, из POST /api/integrations/v1/integrations/{package}/sync (scope integrations.trigger_sync).

Статусы: подводные камни

Внимание

status_id В админке статусы настраиваемые. Для правил используйте status_code или status_semantic (CREATED, PAYED, CANCELLED, …). Если status_code = null — задайте код в Настройки → Статусы.

  1. Пачка хуков при отмене заказа — сервис статусов может обновить все позиции → много order.item_status_changed, затем order.status_changed. Фильтруйте по status_semantic или слушайте только order.status_changed.

  2. Порядок — хук позиции может прийти чуть раньше пересчёта статуса заказа. Нужен итог по заказу — подпишитесь на order.status_changed.

  3. status_locked — в snapshot есть флаг; робот system такую сущность не меняет. Интеграция через API может сменить статус позиции с lock (в отличие от робота).

  4. Хуки только после commit — откат транзакции → событий нет.

  5. order.updated не на touch() — смена цены позиции не шлёт лишний хук заказа.

Пример payload order.status_changed

json
{
  "id": 42,
  "pickup_point_id": 1,
  "status_id": 5,
  "status_code": "order.in_progress",
  "status_semantic": "IN_PROGRESS",
  "status_name": "В работе",
  "previous_status_id": 3,
  "previous_status_code": "order.created",
  "previous_status_semantic": "CREATED",
  "items": []
}

Идемпотентность

Запись в integration_hook_deliveries по (package, hook, idempotency_key). Повторная доставка с тем же ключом после completed handler не вызывает.

Пишите обработчики так, чтобы повторный POST/webhook не создавал дубликат в CRM.

Связанные разделы