Перейти к основному содержимому

Payload Examples For Top Critical Events — Первые example payloads для ключевых async событий

Версия: 1.0
Дата: 24.04.2026
Статус: Готов к обсуждению

Назначение документа​

Этот документ фиксирует первые example payloads для наиболее критичных async событий платформы.

Его задача — показать:

  • как на практике должны выглядеть envelope-level и domain-level поля;
  • как удерживаются correlation, tenant, actor, surface, replay и financial context;
  • где payload должен оставаться bounded, а где ему нужна richer operational shape;
  • как payload examples соотносятся с payload family outlines, channel catalog и contract package.

Документ не является финальным schema package. Он является первым concrete example layer для high-value async events.

Опорные документы​

Почему Этот Документ Нужен Отдельно​

После появления payload family outlines уже недостаточно иметь только список полей и design rules.

Команде нужен следующий шаг:

  • увидеть реальные example shapes;
  • проверить, что поля together образуют usable event contract;
  • заметить accidental payload bloat или missing context до формализации schema package;
  • согласовать, какие события требуют richer operational payload, а какие могут оставаться reference-heavy.

Без этого payload-layer остаётся слишком абстрактным и плохо проверяется на практическую пригодность.

Главный Принцип​

Example payload должен быть:

  • contract-honest;
  • operationally useful;
  • bounded by the documented domain;
  • readable for humans;
  • close enough to future schema drafts, но без premature freezing of every optional detail.

Example 1. quote.created​

Почему Это Критично​

quote.created — это первый сильный commercial promise event, который должен быть пригоден и для downstream UI refresh, и для booking guard, и для support trace.

Example Payload​

{
  "event_name": "quote.created",
  "event_version": "1.0",
  "event_id": "evt_quote_01J9W2R6D7K8M9N0P1Q2R3S4",
  "occurred_at": "2026-04-24T16:10:12Z",
  "producer": "commercial-quote-runtime",
  "correlation_id": "corr_search_01J9W2Q7K6N5M4P3R2S1T0U9",
  "causation_id": "cmd_quote_create_01J9W2R1H2J3K4L5M6N7P8Q9",
  "actor_context_id": "actorctx_01J9W2QAZ1X2C3V4B5N6M7K8",
  "tenant_id": "tenant_agency_kyivtravel",
  "workspace_id": "workspace_agency_sales_ua",
  "delivery_class": "domain-event",
  "replay_sensitivity": "high",
  "schema_family": "quote-lifecycle",
  "payload": {
    "quote_id": "quote_01J9W2R4S5D6F7G8H9J0K1L2",
    "offer_id": "offer_01J9W2QW3E4R5T6Y7U8I9O0P",
    "quote_state": "active",
    "price_basis_ref": "pricebasis_01J9W2QWPRICE001",
    "currency_code": "EUR",
    "quote_valid_until": "2026-04-24T16:25:12Z",
    "commercial_context_ref": "commercialctx_partner_standard_eu",
    "price_view_class": "agency-sellable",
    "quote_visibility_scope": "agency-surface"
  }
}

Что Здесь Важно​

  • есть tenant_id, workspace_id, actor_context_id;
  • monetary promise не превращён в full financial dump;
  • есть references на price basis и commercial context;
  • payload пригоден для UI, booking guard и support trace.

Example 2. quote.invalidated​

Почему Это Критично​

Это boundary event между обещанием и потерей пригодности обещания. Он должен быть достаточно сильным, чтобы booking path не продолжал жить на устаревшей quote truth.

Example Payload​

{
  "event_name": "quote.invalidated",
  "event_version": "1.0",
  "event_id": "evt_quoteinv_01J9W3A6S7D8F9G0H1J2K3L4",
  "occurred_at": "2026-04-24T16:18:40Z",
  "producer": "commercial-quote-runtime",
  "correlation_id": "corr_search_01J9W2Q7K6N5M4P3R2S1T0U9",
  "causation_id": "evt_offer_updated_01J9W39T7Y6U5I4O3P2A1S0D",
  "actor_context_id": "actorctx_01J9W2QAZ1X2C3V4B5N6M7K8",
  "tenant_id": "tenant_agency_kyivtravel",
  "workspace_id": "workspace_agency_sales_ua",
  "delivery_class": "domain-event",
  "replay_sensitivity": "high",
  "schema_family": "quote-lifecycle",
  "payload": {
    "quote_id": "quote_01J9W2R4S5D6F7G8H9J0K1L2",
    "offer_id": "offer_01J9W2QW3E4R5T6Y7U8I9O0P",
    "quote_state": "invalidated",
    "invalidated_by_event_ref": "evt_offer_updated_01J9W39T7Y6U5I4O3P2A1S0D",
    "repricing_reason_code": "upstream_offer_change",
    "price_view_class": "agency-sellable"
  }
}

Что Здесь Важно​

  • payload остаётся bounded;
  • есть явная связь с event-cause;
  • booking contour может остановить commit path без дополнительной археологии;
  • support видит причину invalidation на правильном abstraction level.

Example 3. offer.publication.suppressed​

Почему Это Критично​

Это ключевой governance/integrity event, который защищает платформу от unsafe publication.

Example Payload​

{
  "event_name": "offer.publication.suppressed",
  "event_version": "1.0",
  "event_id": "evt_offerpubsup_01J9W3M4N5B6V7C8X9Z0A1S2",
  "occurred_at": "2026-04-24T16:21:04Z",
  "producer": "publication-gating-runtime",
  "correlation_id": "corr_ingestion_01J9W34E5R6T7Y8U9I0O1P2A",
  "causation_id": "evt_offer_integrity_blocked_01J9W3J7K8L9M0N1B2V3C4X5",
  "delivery_class": "integration-domain-hybrid",
  "replay_sensitivity": "high",
  "schema_family": "offer-publication",
  "payload": {
    "offer_id": "offer_01J9W2QW3E4R5T6Y7U8I9O0P",
    "offer_revision": 17,
    "property_id": "property_istanbul_hotel_00041",
    "publication_state": "suppressed",
    "integrity_state": "blocked",
    "freshness_state": "stale-risk",
    "suppression_reason_codes": [
      "integrity_rule_failed",
      "price_anomaly_unresolved"
    ],
    "publication_scope": "all-external-surfaces",
    "affected_surface_classes": [
      "agency-surface",
      "partner-api",
      "b2c-surface"
    ]
  }
}

Что Здесь Важно​

  • payload пригоден для projections и operator diagnostics;
  • не раскрывает raw supplier internals;
  • suppression reason codes остаются bounded и policy-oriented.

Example 4. booking.confirmed​

Почему Это Критично​

Это один из strongest truth-bearing events платформы. Он должен быть usable downstream для post-booking, settlement, clearing и surface refresh.

Example Payload​

{
  "event_name": "booking.confirmed",
  "event_version": "1.0",
  "event_id": "evt_bookingconf_01J9W3Y4U5I6O7P8A9S0D1F2",
  "occurred_at": "2026-04-24T16:27:51Z",
  "producer": "booking-runtime",
  "correlation_id": "corr_booking_01J9W3V4B5N6M7K8J9H0G1F2",
  "causation_id": "cmd_booking_create_01J9W3T3R4E5W6Q7A8S9D0F1",
  "actor_context_id": "actorctx_01J9W2QAZ1X2C3V4B5N6M7K8",
  "tenant_id": "tenant_agency_kyivtravel",
  "workspace_id": "workspace_agency_sales_ua",
  "delivery_class": "domain-event",
  "replay_sensitivity": "high",
  "schema_family": "booking-transitions",
  "payload": {
    "booking_id": "booking_01J9W3X1C2V3B4N5M6A7S8D9",
    "booking_state": "confirmed",
    "quote_id": "quote_01J9W2R4S5D6F7G8H9J0K1L2",
    "booking_reference_scope": "platform-and-supplier-bound",
    "supplier_confirmation_state": "confirmed",
    "transactional_outcome_class": "success",
    "support_visibility_class": "normal",
    "manual_intervention_required": false,
    "supplier_booking_ref": "SUP-HTL-5567281"
  }
}

Что Здесь Важно​

  • downstream contours получают достаточно данных без full booking snapshot;
  • есть связь с quote truth;
  • payload пригоден для support, clearing и settlement start triggers.

Example 5. booking.unknown.external.state​

Почему Это Критично​

Это один из hardest operational events. Он не должен быть thin или ambiguous, иначе support и recovery contours будут слепыми.

Example Payload​

{
  "event_name": "booking.unknown.external.state",
  "event_version": "1.0",
  "event_id": "evt_bookingunk_01J9W49L8K7J6H5G4F3D2S1A",
  "occurred_at": "2026-04-24T16:31:18Z",
  "producer": "booking-followup-runtime",
  "correlation_id": "corr_booking_01J9W3V4B5N6M7K8J9H0G1F2",
  "causation_id": "job_booking_confirmation_poll_01J9W47Q6W5E4R3T2Y1U0I9O",
  "actor_context_id": "actorctx_01J9W2QAZ1X2C3V4B5N6M7K8",
  "tenant_id": "tenant_agency_kyivtravel",
  "workspace_id": "workspace_agency_sales_ua",
  "delivery_class": "domain-operational-hybrid",
  "replay_sensitivity": "high",
  "schema_family": "booking-transitions",
  "payload": {
    "booking_id": "booking_01J9W3X1C2V3B4N5M6A7S8D9",
    "booking_state": "unknown_external_state",
    "quote_id": "quote_01J9W2R4S5D6F7G8H9J0K1L2",
    "booking_reference_scope": "platform-bound-awaiting-supplier-truth",
    "supplier_confirmation_state": "unknown",
    "transactional_outcome_class": "uncertain",
    "support_visibility_class": "urgent-review",
    "manual_intervention_required": true,
    "recovery_path_ref": "recovery_booking_supplier_recheck",
    "unknown_state_reason_code": "supplier_timeout_after_commit_attempt"
  }
}

Что Здесь Важно​

  • event явно operationally serious;
  • payload пригоден для support queueing и incident routing;
  • unknown-state reason не завязан на vendor-specific details.

Example 6. settlement.event.posted​

Почему Это Критично​

Это один из самых важных financial-domain events. Он должен быть traceable, но не превращаться в full ledger export.

Example Payload​

{
  "event_name": "settlement.event.posted",
  "event_version": "1.0",
  "event_id": "evt_settlement_01J9W4G5H6J7K8L9Z0X1C2V3",
  "occurred_at": "2026-04-24T16:35:44Z",
  "producer": "settlement-runtime",
  "correlation_id": "corr_booking_01J9W3V4B5N6M7K8J9H0G1F2",
  "causation_id": "evt_bookingconf_01J9W3Y4U5I6O7P8A9S0D1F2",
  "tenant_id": "tenant_agency_kyivtravel",
  "workspace_id": "workspace_agency_sales_ua",
  "delivery_class": "financial-domain-event",
  "replay_sensitivity": "high",
  "schema_family": "settlement-reconciliation",
  "payload": {
    "financial_event_id": "finsettle_01J9W4F2D3S4A5Q6W7E8R9T0",
    "booking_id": "booking_01J9W3X1C2V3B4N5M6A7S8D9",
    "financial_state_class": "initial-posted",
    "currency_code": "EUR",
    "amount_scope_class": "booking-gross-basis",
    "financial_counterparty_scope": "supplier-and-platform",
    "settlement_basis_ref": "settbasis_01J9W4C3V4B5N6M7K8J9H0G1",
    "clearing_context_ref": "clearingctx_partner_standard_eu"
  }
}

Что Здесь Важно​

  • financial payload остаётся controlled;
  • есть booking linkage, settlement basis и clearing context;
  • downstream reconciliation может работать без full accounting mirror.

Example 7. usage.quota.exhausted​

Почему Это Критично​

Это важный external governance event, который должен одинаково хорошо работать для surface enforcement и operator/partner-success коммуникации.

Example Payload​

{
  "event_name": "usage.quota.exhausted",
  "event_version": "1.0",
  "event_id": "evt_usagequota_01J9W4T6Y7U8I9O0P1A2S3D4",
  "occurred_at": "2026-04-24T16:41:09Z",
  "producer": "usage-governance-runtime",
  "correlation_id": "corr_usageagg_01J9W4Q5W6E7R8T9Y0U1I2O3",
  "tenant_id": "tenant_partner_holidayhub",
  "delivery_class": "integration-control-signal",
  "replay_sensitivity": "medium",
  "schema_family": "usage-governance",
  "payload": {
    "tenant_id": "tenant_partner_holidayhub",
    "usage_profile_id": "usageprof_partner_holidayhub_monthly",
    "governance_state": "quota_exhausted",
    "affected_surface_scope": "partner-api",
    "enforcement_class": "hard-throttle",
    "quota_window_ref": "quota_2026_04_partner_holidayhub",
    "throttle_policy_ref": "policy_throttle_partner_standard"
  }
}

Что Здесь Важно​

  • payload пригоден для gateway/policy layer;
  • не перегружен low-level metering details;
  • сохраняет tenant-level governance truth.

Cross-Example Observations​

На этих examples уже видно:

  • quote и booking payloadы требуют richer operational context;
  • offer publication и usage governance могут оставаться более bounded;
  • settlement payload должен быть traceable, но не accounting-heavy;
  • unknown external state требует stronger operational shape, чем обычные booking transitions.

What Must Stay Out Of Scope​

Пока не нужно:

  • фиксировать exhaustive optional fields;
  • делать these examples vendor-specific;
  • смешивать example payloads с final JSON Schema;
  • добавлять binary attachments or transport-specific headers;
  • превращать examples в final compatibility promise.

Что Должно Появиться Следом​

Следующий слой после этих examples:

Этот документ даёт первый concrete example baseline и переводит payload-layer ещё на шаг ближе к formal schema drafting.

Уточнение под Фазы 4–6 (28.04.2026) — каноничные источники payload definitions​

Документ опубликован 24.04.2026 (Фаза 3). После Фаз 4–6 каноничные payload structures каждого критичного event теперь живут в специализированных reference-документах.

При создании payload examples — использовать актуальные структуры из:

Сводный каталог имён событий — reference/initial-event-taxonomy.md.

Уточнение выполнено через no-destruction.