@mamindom/contracts 1.0.207 → 1.0.210

package/dist/events/orders/index.d.ts

@@ -3,4 +3,5 @@ export * from './order-created.interface';
 export * from './order-side-effects.interface';
 export * from './order-status-changed.interface';
 export * from './order-crm.interface';
+export * from './order-money.interface';
 export * from './order-one-c.interface';

package/dist/events/orders/index.js

@@ -19,4 +19,5 @@ __exportStar(require("./order-created.interface"), exports);
 __exportStar(require("./order-side-effects.interface"), exports);
 __exportStar(require("./order-status-changed.interface"), exports);
 __exportStar(require("./order-crm.interface"), exports);
+__exportStar(require("./order-money.interface"), exports);
 __exportStar(require("./order-one-c.interface"), exports);

package/dist/events/orders/order-money.interface.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Менеджер виставив клієнту доплату за перерахунком замовлення в 1С.
+ *
+ * Подія йде в notification-service: покупець дізнається про доплату з
+ * повідомлення (SMS / e-mail) і бачить її в кабінеті. Публікується ЛИШЕ після
+ * того, як рахунок реально створено в payment-service — повідомлення
+ * «доплатіть» без робочого посилання гірше за мовчання.
+ */
+export interface OrderSurchargeRequestedEvent {
+    orderId: string;
+    orderNumber: string;
+    userId?: string;
+    adjustmentId: string;
+    /** Сума доплати у гривнях, рядком (`Money.toWire`). */
+    amount: string;
+    paymentUrl: string;
+    /** Доки посилання дійсне. */
+    expiresAt: number;
+    customer: {
+        firstName: string;
+        lastName: string;
+        email: string;
+        phone: string;
+    };
+}

package/dist/events/orders/order-money.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/events/payments/payment-cancelled.interface.d.ts

@@ -6,4 +6,16 @@ export interface PaymentCancelledEvent {
     amount: string;
     reason?: string;
     cancelledAt: number;
+    /**
+     * `primary` — оплата замовлення, `surcharge` — доплата за перерахунком
+     * у 1С (`order_money_adjustments`).
+     *
+     * Поле є в КОЖНІЙ платіжній події, а не лише в `captured`: споживачі
+     * шукають платіж замовлення за `orderId`, і без `kind` подія про доплату
+     * переписувала б стан ОСНОВНОГО платежу. Наприклад, повернення доплати
+     * 240 ₴ робило все замовлення на 1200 ₴ «поверненим».
+     */
+    kind?: string;
+    /** Врегулювання, яке породило доплату. Порожнє для основного платежу. */
+    adjustmentId?: string;
 }

package/dist/events/payments/payment-captured.interface.d.ts

@@ -7,4 +7,12 @@ export interface PaymentCapturedEvent {
     capturedAmount: string;
     currency: string;
     capturedAt: number;
+    /**
+     * `primary` — оплата замовлення, `surcharge` — доплата за перерахунком
+     * у 1С. Без цього поля споживач не міг відрізнити їх і переписував статус
+     * ОСНОВНОГО платежу на подію про доплату.
+     */
+    kind?: string;
+    /** Врегулювання, яке породило доплату. Порожнє для основного платежу. */
+    adjustmentId?: string;
 }

package/dist/events/payments/payment-failed.interface.d.ts

@@ -6,4 +6,16 @@ export interface PaymentFailedEvent {
     amount: string;
     failureReason: string;
     failedAt: number;
+    /**
+     * `primary` — оплата замовлення, `surcharge` — доплата за перерахунком
+     * у 1С (`order_money_adjustments`).
+     *
+     * Поле є в КОЖНІЙ платіжній події, а не лише в `captured`: споживачі
+     * шукають платіж замовлення за `orderId`, і без `kind` подія про доплату
+     * переписувала б стан ОСНОВНОГО платежу. Наприклад, повернення доплати
+     * 240 ₴ робило все замовлення на 1200 ₴ «поверненим».
+     */
+    kind?: string;
+    /** Врегулювання, яке породило доплату. Порожнє для основного платежу. */
+    adjustmentId?: string;
 }

package/dist/events/payments/payment-held.interface.d.ts

@@ -6,4 +6,16 @@ export interface PaymentHeldEvent {
     amount: string;
     currency: string;
     heldAt: number;
+    /**
+     * `primary` — оплата замовлення, `surcharge` — доплата за перерахунком
+     * у 1С (`order_money_adjustments`).
+     *
+     * Поле є в КОЖНІЙ платіжній події, а не лише в `captured`: споживачі
+     * шукають платіж замовлення за `orderId`, і без `kind` подія про доплату
+     * переписувала б стан ОСНОВНОГО платежу. Наприклад, повернення доплати
+     * 240 ₴ робило все замовлення на 1200 ₴ «поверненим».
+     */
+    kind?: string;
+    /** Врегулювання, яке породило доплату. Порожнє для основного платежу. */
+    adjustmentId?: string;
 }

package/dist/events/payments/payment-refunded.interface.d.ts

@@ -9,4 +9,16 @@ export interface PaymentRefundedEvent {
     isPartial: boolean;
     reason?: string;
     refundedAt: number;
+    /**
+     * `primary` — оплата замовлення, `surcharge` — доплата за перерахунком
+     * у 1С (`order_money_adjustments`).
+     *
+     * Поле є в КОЖНІЙ платіжній події, а не лише в `captured`: споживачі
+     * шукають платіж замовлення за `orderId`, і без `kind` подія про доплату
+     * переписувала б стан ОСНОВНОГО платежу. Наприклад, повернення доплати
+     * 240 ₴ робило все замовлення на 1200 ₴ «поверненим».
+     */
+    kind?: string;
+    /** Врегулювання, яке породило доплату. Порожнє для основного платежу. */
+    adjustmentId?: string;
 }

package/dist/events/stock/stock-restock-requested.interface.d.ts

@@ -2,6 +2,17 @@ export interface StockRestockRequestedEvent {
     orderId: string;
     orderNumber: string;
     reason: string;
+    /**
+     * Ідентифікатор ОПЕРАЦІЇ повернення. Стабільний для однієї події: RMQ
+     * доставляє щонайменше один раз, і дубль несе те саме значення.
+     *
+     * Саме на ньому тримається ідемпотентність у catalog. Виводити ключ зі
+     * стану складу не можна в принципі: перше ж виконання цей стан міняє, тож
+     * повтор отримував би інший ключ і повертав товар удруге. А відрізнити
+     * дубль від ЗАКОННОГО другого часткового повернення тієї самої позиції
+     * (1С зняла ще одну штуку) можна тільки за ідентифікатором операції.
+     */
+    operationId?: string;
     items: Array<{
         productId: string;
         variantId?: string;

package/dist/gen/order.d.ts

@@ -223,6 +223,7 @@ export interface OrderItemInput {
     variantId: string;
     quantity: number;
     priceOverride: number;
+    priceProvided: boolean;
 }
 export interface GetOrderRequest {
     id: string;
@@ -281,6 +282,85 @@ export interface SetCrmOrderIdRequest {
     id: string;
     crmOrderId: string;
 }
+export interface MoneyAdjustment {
+    id: string;
+    orderId: string;
+    kind: string;
+    status: string;
+    amount: number;
+    totalBefore: number;
+    totalAfter: number;
+    source: string;
+    paymentId: string;
+    paymentUrl: string;
+    expiresAt: number;
+    resolvedBy: string;
+    resolvedAt: number;
+    resolution: string;
+    dismissReason: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface MoneyAdjustmentResponse {
+    ok: boolean;
+    adjustment: MoneyAdjustment | undefined;
+    errorMessage: string;
+}
+export interface ListMoneyAdjustmentsRequest {
+    orderId: string;
+    onlyOpen: boolean;
+    limit: number;
+}
+export interface ListMoneyAdjustmentsResponse {
+    items: MoneyAdjustment[];
+}
+export interface GetMoneyAdjustmentRequest {
+    id: string;
+}
+export interface MarkSurchargeIssuedRequest {
+    id: string;
+    paymentId: string;
+    paymentUrl: string;
+    actorId: string;
+    actorName: string;
+}
+export interface SettleMoneyAdjustmentRequest {
+    id: string;
+    resolution: string;
+    actorId: string;
+    actorName: string;
+    paymentId: string;
+    amount: number;
+    amountProvided: boolean;
+}
+export interface DismissMoneyAdjustmentRequest {
+    id: string;
+    reason: string;
+    actorId: string;
+    actorName: string;
+}
+export interface ListStuckEventsRequest {
+    limit: number;
+}
+export interface StuckEvent {
+    id: string;
+    pattern: string;
+    orderKey: string;
+    attempts: number;
+    lastError: string;
+    createdAt: number;
+    acknowledged: boolean;
+}
+export interface ListStuckEventsResponse {
+    items: StuckEvent[];
+}
+export interface StuckEventsActionRequest {
+    ids: string[];
+    actorId: string;
+}
+export interface StuckEventsActionResponse {
+    affected: number;
+}
 export interface SetOneCOrderRefRequest {
     id: string;
     oneCOrderNumber: string;
@@ -423,6 +503,25 @@ export interface OrderServiceClient {
     setCrmOrderId(request: SetCrmOrderIdRequest): Observable<OrderResponse>;
     setOneCOrderRef(request: SetOneCOrderRefRequest): Observable<OrderResponse>;
     applyOneCStatus(request: ApplyOneCStatusRequest): Observable<OrderResponse>;
+    /** Врегулювання грошей після перерахунку (доплата / повернення). */
+    listMoneyAdjustments(request: ListMoneyAdjustmentsRequest): Observable<ListMoneyAdjustmentsResponse>;
+    getMoneyAdjustment(request: GetMoneyAdjustmentRequest): Observable<MoneyAdjustmentResponse>;
+    /**
+     * Перевірка ПЕРЕД створенням рахунку: чи можна взагалі виставляти доплату.
+     * Без неї платіжне посилання встигало зʼявитись раніше за відмову.
+     */
+    assertCanIssueSurcharge(request: GetMoneyAdjustmentRequest): Observable<MoneyAdjustmentResponse>;
+    markSurchargeIssued(request: MarkSurchargeIssuedRequest): Observable<MoneyAdjustmentResponse>;
+    settleMoneyAdjustment(request: SettleMoneyAdjustmentRequest): Observable<MoneyAdjustmentResponse>;
+    dismissMoneyAdjustment(request: DismissMoneyAdjustmentRequest): Observable<MoneyAdjustmentResponse>;
+    /**
+     * Розбір заторів у черзі подій: подія, яка вичерпала ретраї, навмисно
+     * блокує всі наступні події свого замовлення (інакше `stock.reserve` поїхав
+     * би без свого `stock.release`). Тому потрібен і вихід із цього стану.
+     */
+    listStuckEvents(request: ListStuckEventsRequest): Observable<ListStuckEventsResponse>;
+    retryStuckEvents(request: StuckEventsActionRequest): Observable<StuckEventsActionResponse>;
+    dismissStuckEvents(request: StuckEventsActionRequest): Observable<StuckEventsActionResponse>;
     confirmPickup(request: ConfirmPickupRequest): Observable<OrderResponse>;
     reorderOrder(request: ReorderOrderRequest): Observable<ReorderResponse>;
     listHistory(request: ListHistoryRequest): Observable<ListHistoryResponse>;
@@ -451,6 +550,25 @@ export interface OrderServiceController {
     setCrmOrderId(request: SetCrmOrderIdRequest): Promise<OrderResponse> | Observable<OrderResponse> | OrderResponse;
     setOneCOrderRef(request: SetOneCOrderRefRequest): Promise<OrderResponse> | Observable<OrderResponse> | OrderResponse;
     applyOneCStatus(request: ApplyOneCStatusRequest): Promise<OrderResponse> | Observable<OrderResponse> | OrderResponse;
+    /** Врегулювання грошей після перерахунку (доплата / повернення). */
+    listMoneyAdjustments(request: ListMoneyAdjustmentsRequest): Promise<ListMoneyAdjustmentsResponse> | Observable<ListMoneyAdjustmentsResponse> | ListMoneyAdjustmentsResponse;
+    getMoneyAdjustment(request: GetMoneyAdjustmentRequest): Promise<MoneyAdjustmentResponse> | Observable<MoneyAdjustmentResponse> | MoneyAdjustmentResponse;
+    /**
+     * Перевірка ПЕРЕД створенням рахунку: чи можна взагалі виставляти доплату.
+     * Без неї платіжне посилання встигало зʼявитись раніше за відмову.
+     */
+    assertCanIssueSurcharge(request: GetMoneyAdjustmentRequest): Promise<MoneyAdjustmentResponse> | Observable<MoneyAdjustmentResponse> | MoneyAdjustmentResponse;
+    markSurchargeIssued(request: MarkSurchargeIssuedRequest): Promise<MoneyAdjustmentResponse> | Observable<MoneyAdjustmentResponse> | MoneyAdjustmentResponse;
+    settleMoneyAdjustment(request: SettleMoneyAdjustmentRequest): Promise<MoneyAdjustmentResponse> | Observable<MoneyAdjustmentResponse> | MoneyAdjustmentResponse;
+    dismissMoneyAdjustment(request: DismissMoneyAdjustmentRequest): Promise<MoneyAdjustmentResponse> | Observable<MoneyAdjustmentResponse> | MoneyAdjustmentResponse;
+    /**
+     * Розбір заторів у черзі подій: подія, яка вичерпала ретраї, навмисно
+     * блокує всі наступні події свого замовлення (інакше `stock.reserve` поїхав
+     * би без свого `stock.release`). Тому потрібен і вихід із цього стану.
+     */
+    listStuckEvents(request: ListStuckEventsRequest): Promise<ListStuckEventsResponse> | Observable<ListStuckEventsResponse> | ListStuckEventsResponse;
+    retryStuckEvents(request: StuckEventsActionRequest): Promise<StuckEventsActionResponse> | Observable<StuckEventsActionResponse> | StuckEventsActionResponse;
+    dismissStuckEvents(request: StuckEventsActionRequest): Promise<StuckEventsActionResponse> | Observable<StuckEventsActionResponse> | StuckEventsActionResponse;
     confirmPickup(request: ConfirmPickupRequest): Promise<OrderResponse> | Observable<OrderResponse> | OrderResponse;
     reorderOrder(request: ReorderOrderRequest): Promise<ReorderResponse> | Observable<ReorderResponse> | ReorderResponse;
     listHistory(request: ListHistoryRequest): Promise<ListHistoryResponse> | Observable<ListHistoryResponse> | ListHistoryResponse;

package/dist/gen/order.js

@@ -35,6 +35,15 @@ function OrderServiceControllerMethods() {
             "setCrmOrderId",
             "setOneCOrderRef",
             "applyOneCStatus",
+            "listMoneyAdjustments",
+            "getMoneyAdjustment",
+            "assertCanIssueSurcharge",
+            "markSurchargeIssued",
+            "settleMoneyAdjustment",
+            "dismissMoneyAdjustment",
+            "listStuckEvents",
+            "retryStuckEvents",
+            "dismissStuckEvents",
             "confirmPickup",
             "reorderOrder",
             "listHistory",

package/dist/gen/payment.d.ts

@@ -21,6 +21,9 @@ export interface Payment {
     refundedAt: number;
     captureSource: string;
     captureNote: string;
+    /** Тип платежу і врегулювання, яке його породило (див. CreateInvoiceRequest). */
+    kind: string;
+    adjustmentId: string;
 }
 export interface PaymentProviderInfo {
     key: string;
@@ -44,6 +47,14 @@ export interface CreateInvoiceRequest {
     customerEmail: string;
     customerPhone: string;
     items: InvoiceItem[];
+    /**
+     * `primary` (за замовчуванням) — оплата замовлення; `surcharge` — доплата
+     * за перерахунком у 1С. На замовлення може бути один основний платіж і
+     * скільки завгодно доплат.
+     */
+    kind: string;
+    /** Врегулювання, яке породило доплату (`order_money_adjustments`). */
+    adjustmentId: string;
 }
 export interface InvoiceItem {
     name: string;
@@ -57,6 +68,9 @@ export interface GetPaymentRequest {
 export interface GetPaymentByOrderRequest {
     orderId: string;
 }
+export interface GetPaymentByAdjustmentRequest {
+    adjustmentId: string;
+}
 export interface ListPaymentsRequest {
     page: number;
     limit: number;
@@ -167,6 +181,13 @@ export interface PaymentServiceClient {
     createInvoice(request: CreateInvoiceRequest): Observable<PaymentResponse>;
     getPayment(request: GetPaymentRequest): Observable<PaymentResponse>;
     getPaymentByOrder(request: GetPaymentByOrderRequest): Observable<PaymentResponse>;
+    /**
+     * Платіж ДОПЛАТИ за врегулюванням. `GetPaymentByOrder` для цього не
+     * годиться: він завжди віддає основний платіж замовлення.
+     */
+    getPaymentByAdjustment(request: GetPaymentByAdjustmentRequest): Observable<PaymentResponse>;
+    /** Усі платежі замовлення (основний + доплати) — для звірки сум. */
+    listOrderPayments(request: GetPaymentByOrderRequest): Observable<ListPaymentsResponse>;
     listPayments(request: ListPaymentsRequest): Observable<ListPaymentsResponse>;
     capture(request: CaptureRequest): Observable<PaymentResponse>;
     markPaidOffline(request: MarkPaidOfflineRequest): Observable<PaymentResponse>;
@@ -185,6 +206,13 @@ export interface PaymentServiceController {
     createInvoice(request: CreateInvoiceRequest): Promise<PaymentResponse> | Observable<PaymentResponse> | PaymentResponse;
     getPayment(request: GetPaymentRequest): Promise<PaymentResponse> | Observable<PaymentResponse> | PaymentResponse;
     getPaymentByOrder(request: GetPaymentByOrderRequest): Promise<PaymentResponse> | Observable<PaymentResponse> | PaymentResponse;
+    /**
+     * Платіж ДОПЛАТИ за врегулюванням. `GetPaymentByOrder` для цього не
+     * годиться: він завжди віддає основний платіж замовлення.
+     */
+    getPaymentByAdjustment(request: GetPaymentByAdjustmentRequest): Promise<PaymentResponse> | Observable<PaymentResponse> | PaymentResponse;
+    /** Усі платежі замовлення (основний + доплати) — для звірки сум. */
+    listOrderPayments(request: GetPaymentByOrderRequest): Promise<ListPaymentsResponse> | Observable<ListPaymentsResponse> | ListPaymentsResponse;
     listPayments(request: ListPaymentsRequest): Promise<ListPaymentsResponse> | Observable<ListPaymentsResponse> | ListPaymentsResponse;
     capture(request: CaptureRequest): Promise<PaymentResponse> | Observable<PaymentResponse> | PaymentResponse;
     markPaidOffline(request: MarkPaidOfflineRequest): Promise<PaymentResponse> | Observable<PaymentResponse> | PaymentResponse;

package/dist/gen/payment.js

@@ -17,6 +17,8 @@ function PaymentServiceControllerMethods() {
             "createInvoice",
             "getPayment",
             "getPaymentByOrder",
+            "getPaymentByAdjustment",
+            "listOrderPayments",
             "listPayments",
             "capture",
             "markPaidOffline",

package/dist/proto/order.proto

@@ -36,6 +36,24 @@ service OrderService {
 
   rpc ApplyOneCStatus(ApplyOneCStatusRequest) returns (OrderResponse);
 
+
+  // Врегулювання грошей після перерахунку (доплата / повернення).
+  rpc ListMoneyAdjustments(ListMoneyAdjustmentsRequest) returns (ListMoneyAdjustmentsResponse);
+  rpc GetMoneyAdjustment(GetMoneyAdjustmentRequest) returns (MoneyAdjustmentResponse);
+  // Перевірка ПЕРЕД створенням рахунку: чи можна взагалі виставляти доплату.
+  // Без неї платіжне посилання встигало зʼявитись раніше за відмову.
+  rpc AssertCanIssueSurcharge(GetMoneyAdjustmentRequest) returns (MoneyAdjustmentResponse);
+  rpc MarkSurchargeIssued(MarkSurchargeIssuedRequest) returns (MoneyAdjustmentResponse);
+  rpc SettleMoneyAdjustment(SettleMoneyAdjustmentRequest) returns (MoneyAdjustmentResponse);
+  rpc DismissMoneyAdjustment(DismissMoneyAdjustmentRequest) returns (MoneyAdjustmentResponse);
+
+  // Розбір заторів у черзі подій: подія, яка вичерпала ретраї, навмисно
+  // блокує всі наступні події свого замовлення (інакше `stock.reserve` поїхав
+  // би без свого `stock.release`). Тому потрібен і вихід із цього стану.
+  rpc ListStuckEvents(ListStuckEventsRequest) returns (ListStuckEventsResponse);
+  rpc RetryStuckEvents(StuckEventsActionRequest) returns (StuckEventsActionResponse);
+  rpc DismissStuckEvents(StuckEventsActionRequest) returns (StuckEventsActionResponse);
+
   rpc ConfirmPickup(ConfirmPickupRequest) returns (OrderResponse);
 
   rpc ReorderOrder(ReorderOrderRequest) returns (ReorderResponse);
@@ -319,7 +337,11 @@ message OrderItemInput {
   string product_id = 1;
   string variant_id = 2;
   int32 quantity = 3;
+
   double price_override = 4;
+
+  
+  bool price_provided = 5;
 }
 
 message GetOrderRequest {
@@ -393,6 +415,114 @@ message SetCrmOrderIdRequest {
 }
 
 
+
+message MoneyAdjustment {
+  string id       = 1;
+  string order_id = 2;
+
+  
+  string kind = 3;
+
+  
+  string status = 4;
+
+  
+  double amount       = 5;
+  double total_before = 6;
+  double total_after  = 7;
+
+  string source = 8;
+
+  string payment_id  = 9;
+  string payment_url = 10;
+  int64  expires_at  = 11;
+
+  string resolved_by    = 12;
+  int64  resolved_at    = 13;
+  string resolution     = 14;
+  string dismiss_reason = 15;
+
+  int64 created_at = 16;
+  int64 updated_at = 17;
+}
+
+message MoneyAdjustmentResponse {
+  bool ok = 1;
+  MoneyAdjustment adjustment = 2;
+  string error_message = 3;
+}
+
+message ListMoneyAdjustmentsRequest {
+  
+  string order_id = 1;
+  bool only_open  = 2;
+  int32 limit     = 3;
+}
+
+message ListMoneyAdjustmentsResponse {
+  repeated MoneyAdjustment items = 1;
+}
+
+message GetMoneyAdjustmentRequest {
+  string id = 1;
+}
+
+message MarkSurchargeIssuedRequest {
+  string id          = 1;
+  string payment_id  = 2;
+  string payment_url = 3;
+  string actor_id    = 4;
+  string actor_name  = 5;
+}
+
+message SettleMoneyAdjustmentRequest {
+  string id         = 1;
+  string resolution = 2;
+  string actor_id   = 3;
+  string actor_name = 4;
+
+  
+  string payment_id = 5;
+
+
+  double amount     = 6;
+  bool amount_provided = 7;
+}
+
+message DismissMoneyAdjustmentRequest {
+  string id         = 1;
+  string reason     = 2;
+  string actor_id   = 3;
+  string actor_name = 4;
+}
+
+message ListStuckEventsRequest {
+  int32 limit = 1;
+}
+
+message StuckEvent {
+  string id            = 1;
+  string pattern       = 2;
+  string order_key     = 3;
+  int32  attempts      = 4;
+  string last_error    = 5;
+  int64  created_at    = 6;
+  bool   acknowledged  = 7;
+}
+
+message ListStuckEventsResponse {
+  repeated StuckEvent items = 1;
+}
+
+message StuckEventsActionRequest {
+  repeated string ids = 1;
+  string actor_id     = 2;
+}
+
+message StuckEventsActionResponse {
+  int32 affected = 1;
+}
+
 message SetOneCOrderRefRequest {
   string id = 1;
 

package/dist/proto/payment.proto

@@ -8,6 +8,11 @@ service PaymentService {
 
   rpc GetPayment(GetPaymentRequest) returns (PaymentResponse);
   rpc GetPaymentByOrder(GetPaymentByOrderRequest) returns (PaymentResponse);
+  // Платіж ДОПЛАТИ за врегулюванням. `GetPaymentByOrder` для цього не
+  // годиться: він завжди віддає основний платіж замовлення.
+  rpc GetPaymentByAdjustment(GetPaymentByAdjustmentRequest) returns (PaymentResponse);
+  // Усі платежі замовлення (основний + доплати) — для звірки сум.
+  rpc ListOrderPayments(GetPaymentByOrderRequest) returns (ListPaymentsResponse);
   rpc ListPayments(ListPaymentsRequest) returns (ListPaymentsResponse);
 
   
@@ -63,6 +68,10 @@ message Payment {
   
   string capture_source = 19;
   string capture_note = 20;
+
+  // Тип платежу і врегулювання, яке його породило (див. CreateInvoiceRequest).
+  string kind = 21;
+  string adjustment_id = 22;
 }
 
 message PaymentProviderInfo {
@@ -95,6 +104,14 @@ message CreateInvoiceRequest {
   string customer_email  = 8;
   string customer_phone  = 9;
   repeated InvoiceItem items = 10;
+
+  // `primary` (за замовчуванням) — оплата замовлення; `surcharge` — доплата
+  // за перерахунком у 1С. На замовлення може бути один основний платіж і
+  // скільки завгодно доплат.
+  string kind = 11;
+
+  // Врегулювання, яке породило доплату (`order_money_adjustments`).
+  string adjustment_id = 12;
 }
 
 message InvoiceItem {
@@ -112,6 +129,10 @@ message GetPaymentByOrderRequest {
   string order_id = 1;
 }
 
+message GetPaymentByAdjustmentRequest {
+  string adjustment_id = 1;
+}
+
 message ListPaymentsRequest {
   int32  page = 1;
   int32  limit = 2;

package/events/orders/index.ts

@@ -3,4 +3,5 @@ export * from './order-created.interface'
 export * from './order-side-effects.interface'
 export * from './order-status-changed.interface'
 export * from './order-crm.interface'
+export * from './order-money.interface'
 export * from './order-one-c.interface'

package/events/orders/order-money.interface.ts

@@ -0,0 +1,30 @@
+/**
+ * Менеджер виставив клієнту доплату за перерахунком замовлення в 1С.
+ *
+ * Подія йде в notification-service: покупець дізнається про доплату з
+ * повідомлення (SMS / e-mail) і бачить її в кабінеті. Публікується ЛИШЕ після
+ * того, як рахунок реально створено в payment-service — повідомлення
+ * «доплатіть» без робочого посилання гірше за мовчання.
+ */
+export interface OrderSurchargeRequestedEvent {
+	orderId: string
+	orderNumber: string
+	userId?: string
+
+	adjustmentId: string
+
+	/** Сума доплати у гривнях, рядком (`Money.toWire`). */
+	amount: string
+
+	paymentUrl: string
+
+	/** Доки посилання дійсне. */
+	expiresAt: number
+
+	customer: {
+		firstName: string
+		lastName: string
+		email: string
+		phone: string
+	}
+}

package/events/payments/payment-cancelled.interface.ts

@@ -6,4 +6,17 @@ export interface PaymentCancelledEvent {
 	amount: string
 	reason?: string
 	cancelledAt: number
+	/**
+	 * `primary` — оплата замовлення, `surcharge` — доплата за перерахунком
+	 * у 1С (`order_money_adjustments`).
+	 *
+	 * Поле є в КОЖНІЙ платіжній події, а не лише в `captured`: споживачі
+	 * шукають платіж замовлення за `orderId`, і без `kind` подія про доплату
+	 * переписувала б стан ОСНОВНОГО платежу. Наприклад, повернення доплати
+	 * 240 ₴ робило все замовлення на 1200 ₴ «поверненим».
+	 */
+	kind?: string
+
+	/** Врегулювання, яке породило доплату. Порожнє для основного платежу. */
+	adjustmentId?: string
 }

package/events/payments/payment-captured.interface.ts

@@ -7,4 +7,14 @@ export interface PaymentCapturedEvent {
 	capturedAmount: string
 	currency: string
 	capturedAt: number
+
+	/**
+	 * `primary` — оплата замовлення, `surcharge` — доплата за перерахунком
+	 * у 1С. Без цього поля споживач не міг відрізнити їх і переписував статус
+	 * ОСНОВНОГО платежу на подію про доплату.
+	 */
+	kind?: string
+
+	/** Врегулювання, яке породило доплату. Порожнє для основного платежу. */
+	adjustmentId?: string
 }

package/events/payments/payment-failed.interface.ts

@@ -6,4 +6,17 @@ export interface PaymentFailedEvent {
 	amount: string
 	failureReason: string
 	failedAt: number
+	/**
+	 * `primary` — оплата замовлення, `surcharge` — доплата за перерахунком
+	 * у 1С (`order_money_adjustments`).
+	 *
+	 * Поле є в КОЖНІЙ платіжній події, а не лише в `captured`: споживачі
+	 * шукають платіж замовлення за `orderId`, і без `kind` подія про доплату
+	 * переписувала б стан ОСНОВНОГО платежу. Наприклад, повернення доплати
+	 * 240 ₴ робило все замовлення на 1200 ₴ «поверненим».
+	 */
+	kind?: string
+
+	/** Врегулювання, яке породило доплату. Порожнє для основного платежу. */
+	adjustmentId?: string
 }

package/events/payments/payment-held.interface.ts

@@ -6,4 +6,17 @@ export interface PaymentHeldEvent {
 	amount: string
 	currency: string
 	heldAt: number
+	/**
+	 * `primary` — оплата замовлення, `surcharge` — доплата за перерахунком
+	 * у 1С (`order_money_adjustments`).
+	 *
+	 * Поле є в КОЖНІЙ платіжній події, а не лише в `captured`: споживачі
+	 * шукають платіж замовлення за `orderId`, і без `kind` подія про доплату
+	 * переписувала б стан ОСНОВНОГО платежу. Наприклад, повернення доплати
+	 * 240 ₴ робило все замовлення на 1200 ₴ «поверненим».
+	 */
+	kind?: string
+
+	/** Врегулювання, яке породило доплату. Порожнє для основного платежу. */
+	adjustmentId?: string
 }

package/events/payments/payment-refunded.interface.ts

@@ -9,4 +9,17 @@ export interface PaymentRefundedEvent {
 	isPartial: boolean
 	reason?: string
 	refundedAt: number
+	/**
+	 * `primary` — оплата замовлення, `surcharge` — доплата за перерахунком
+	 * у 1С (`order_money_adjustments`).
+	 *
+	 * Поле є в КОЖНІЙ платіжній події, а не лише в `captured`: споживачі
+	 * шукають платіж замовлення за `orderId`, і без `kind` подія про доплату
+	 * переписувала б стан ОСНОВНОГО платежу. Наприклад, повернення доплати
+	 * 240 ₴ робило все замовлення на 1200 ₴ «поверненим».
+	 */
+	kind?: string
+
+	/** Врегулювання, яке породило доплату. Порожнє для основного платежу. */
+	adjustmentId?: string
 }

package/events/stock/stock-restock-requested.interface.ts

@@ -2,6 +2,19 @@ export interface StockRestockRequestedEvent {
 	orderId: string
 	orderNumber: string
 	reason: string
+
+	/**
+	 * Ідентифікатор ОПЕРАЦІЇ повернення. Стабільний для однієї події: RMQ
+	 * доставляє щонайменше один раз, і дубль несе те саме значення.
+	 *
+	 * Саме на ньому тримається ідемпотентність у catalog. Виводити ключ зі
+	 * стану складу не можна в принципі: перше ж виконання цей стан міняє, тож
+	 * повтор отримував би інший ключ і повертав товар удруге. А відрізнити
+	 * дубль від ЗАКОННОГО другого часткового повернення тієї самої позиції
+	 * (1С зняла ще одну штуку) можна тільки за ідентифікатором операції.
+	 */
+	operationId?: string
+
 	items: Array<{
 		productId: string
 		variantId?: string

package/gen/order.ts

@@ -259,6 +259,7 @@ export interface OrderItemInput {
   variantId: string;
   quantity: number;
   priceOverride: number;
+  priceProvided: boolean;
 }
 
 export interface GetOrderRequest {
@@ -326,6 +327,98 @@ export interface SetCrmOrderIdRequest {
   crmOrderId: string;
 }
 
+export interface MoneyAdjustment {
+  id: string;
+  orderId: string;
+  kind: string;
+  status: string;
+  amount: number;
+  totalBefore: number;
+  totalAfter: number;
+  source: string;
+  paymentId: string;
+  paymentUrl: string;
+  expiresAt: number;
+  resolvedBy: string;
+  resolvedAt: number;
+  resolution: string;
+  dismissReason: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface MoneyAdjustmentResponse {
+  ok: boolean;
+  adjustment: MoneyAdjustment | undefined;
+  errorMessage: string;
+}
+
+export interface ListMoneyAdjustmentsRequest {
+  orderId: string;
+  onlyOpen: boolean;
+  limit: number;
+}
+
+export interface ListMoneyAdjustmentsResponse {
+  items: MoneyAdjustment[];
+}
+
+export interface GetMoneyAdjustmentRequest {
+  id: string;
+}
+
+export interface MarkSurchargeIssuedRequest {
+  id: string;
+  paymentId: string;
+  paymentUrl: string;
+  actorId: string;
+  actorName: string;
+}
+
+export interface SettleMoneyAdjustmentRequest {
+  id: string;
+  resolution: string;
+  actorId: string;
+  actorName: string;
+  paymentId: string;
+  amount: number;
+  amountProvided: boolean;
+}
+
+export interface DismissMoneyAdjustmentRequest {
+  id: string;
+  reason: string;
+  actorId: string;
+  actorName: string;
+}
+
+export interface ListStuckEventsRequest {
+  limit: number;
+}
+
+export interface StuckEvent {
+  id: string;
+  pattern: string;
+  orderKey: string;
+  attempts: number;
+  lastError: string;
+  createdAt: number;
+  acknowledged: boolean;
+}
+
+export interface ListStuckEventsResponse {
+  items: StuckEvent[];
+}
+
+export interface StuckEventsActionRequest {
+  ids: string[];
+  actorId: string;
+}
+
+export interface StuckEventsActionResponse {
+  affected: number;
+}
+
 export interface SetOneCOrderRefRequest {
   id: string;
   oneCOrderNumber: string;
@@ -511,6 +604,37 @@ export interface OrderServiceClient {
 
   applyOneCStatus(request: ApplyOneCStatusRequest): Observable<OrderResponse>;
 
+  /** Врегулювання грошей після перерахунку (доплата / повернення). */
+
+  listMoneyAdjustments(request: ListMoneyAdjustmentsRequest): Observable<ListMoneyAdjustmentsResponse>;
+
+  getMoneyAdjustment(request: GetMoneyAdjustmentRequest): Observable<MoneyAdjustmentResponse>;
+
+  /**
+   * Перевірка ПЕРЕД створенням рахунку: чи можна взагалі виставляти доплату.
+   * Без неї платіжне посилання встигало зʼявитись раніше за відмову.
+   */
+
+  assertCanIssueSurcharge(request: GetMoneyAdjustmentRequest): Observable<MoneyAdjustmentResponse>;
+
+  markSurchargeIssued(request: MarkSurchargeIssuedRequest): Observable<MoneyAdjustmentResponse>;
+
+  settleMoneyAdjustment(request: SettleMoneyAdjustmentRequest): Observable<MoneyAdjustmentResponse>;
+
+  dismissMoneyAdjustment(request: DismissMoneyAdjustmentRequest): Observable<MoneyAdjustmentResponse>;
+
+  /**
+   * Розбір заторів у черзі подій: подія, яка вичерпала ретраї, навмисно
+   * блокує всі наступні події свого замовлення (інакше `stock.reserve` поїхав
+   * би без свого `stock.release`). Тому потрібен і вихід із цього стану.
+   */
+
+  listStuckEvents(request: ListStuckEventsRequest): Observable<ListStuckEventsResponse>;
+
+  retryStuckEvents(request: StuckEventsActionRequest): Observable<StuckEventsActionResponse>;
+
+  dismissStuckEvents(request: StuckEventsActionRequest): Observable<StuckEventsActionResponse>;
+
   confirmPickup(request: ConfirmPickupRequest): Observable<OrderResponse>;
 
   reorderOrder(request: ReorderOrderRequest): Observable<ReorderResponse>;
@@ -579,6 +703,55 @@ export interface OrderServiceController {
 
   applyOneCStatus(request: ApplyOneCStatusRequest): Promise<OrderResponse> | Observable<OrderResponse> | OrderResponse;
 
+  /** Врегулювання грошей після перерахунку (доплата / повернення). */
+
+  listMoneyAdjustments(
+    request: ListMoneyAdjustmentsRequest,
+  ): Promise<ListMoneyAdjustmentsResponse> | Observable<ListMoneyAdjustmentsResponse> | ListMoneyAdjustmentsResponse;
+
+  getMoneyAdjustment(
+    request: GetMoneyAdjustmentRequest,
+  ): Promise<MoneyAdjustmentResponse> | Observable<MoneyAdjustmentResponse> | MoneyAdjustmentResponse;
+
+  /**
+   * Перевірка ПЕРЕД створенням рахунку: чи можна взагалі виставляти доплату.
+   * Без неї платіжне посилання встигало зʼявитись раніше за відмову.
+   */
+
+  assertCanIssueSurcharge(
+    request: GetMoneyAdjustmentRequest,
+  ): Promise<MoneyAdjustmentResponse> | Observable<MoneyAdjustmentResponse> | MoneyAdjustmentResponse;
+
+  markSurchargeIssued(
+    request: MarkSurchargeIssuedRequest,
+  ): Promise<MoneyAdjustmentResponse> | Observable<MoneyAdjustmentResponse> | MoneyAdjustmentResponse;
+
+  settleMoneyAdjustment(
+    request: SettleMoneyAdjustmentRequest,
+  ): Promise<MoneyAdjustmentResponse> | Observable<MoneyAdjustmentResponse> | MoneyAdjustmentResponse;
+
+  dismissMoneyAdjustment(
+    request: DismissMoneyAdjustmentRequest,
+  ): Promise<MoneyAdjustmentResponse> | Observable<MoneyAdjustmentResponse> | MoneyAdjustmentResponse;
+
+  /**
+   * Розбір заторів у черзі подій: подія, яка вичерпала ретраї, навмисно
+   * блокує всі наступні події свого замовлення (інакше `stock.reserve` поїхав
+   * би без свого `stock.release`). Тому потрібен і вихід із цього стану.
+   */
+
+  listStuckEvents(
+    request: ListStuckEventsRequest,
+  ): Promise<ListStuckEventsResponse> | Observable<ListStuckEventsResponse> | ListStuckEventsResponse;
+
+  retryStuckEvents(
+    request: StuckEventsActionRequest,
+  ): Promise<StuckEventsActionResponse> | Observable<StuckEventsActionResponse> | StuckEventsActionResponse;
+
+  dismissStuckEvents(
+    request: StuckEventsActionRequest,
+  ): Promise<StuckEventsActionResponse> | Observable<StuckEventsActionResponse> | StuckEventsActionResponse;
+
   confirmPickup(request: ConfirmPickupRequest): Promise<OrderResponse> | Observable<OrderResponse> | OrderResponse;
 
   reorderOrder(request: ReorderOrderRequest): Promise<ReorderResponse> | Observable<ReorderResponse> | ReorderResponse;
@@ -618,6 +791,15 @@ export function OrderServiceControllerMethods() {
       "setCrmOrderId",
       "setOneCOrderRef",
       "applyOneCStatus",
+      "listMoneyAdjustments",
+      "getMoneyAdjustment",
+      "assertCanIssueSurcharge",
+      "markSurchargeIssued",
+      "settleMoneyAdjustment",
+      "dismissMoneyAdjustment",
+      "listStuckEvents",
+      "retryStuckEvents",
+      "dismissStuckEvents",
       "confirmPickup",
       "reorderOrder",
       "listHistory",

package/gen/payment.ts

@@ -31,6 +31,9 @@ export interface Payment {
   refundedAt: number;
   captureSource: string;
   captureNote: string;
+  /** Тип платежу і врегулювання, яке його породило (див. CreateInvoiceRequest). */
+  kind: string;
+  adjustmentId: string;
 }
 
 export interface PaymentProviderInfo {
@@ -56,6 +59,14 @@ export interface CreateInvoiceRequest {
   customerEmail: string;
   customerPhone: string;
   items: InvoiceItem[];
+  /**
+   * `primary` (за замовчуванням) — оплата замовлення; `surcharge` — доплата
+   * за перерахунком у 1С. На замовлення може бути один основний платіж і
+   * скільки завгодно доплат.
+   */
+  kind: string;
+  /** Врегулювання, яке породило доплату (`order_money_adjustments`). */
+  adjustmentId: string;
 }
 
 export interface InvoiceItem {
@@ -73,6 +84,10 @@ export interface GetPaymentByOrderRequest {
   orderId: string;
 }
 
+export interface GetPaymentByAdjustmentRequest {
+  adjustmentId: string;
+}
+
 export interface ListPaymentsRequest {
   page: number;
   limit: number;
@@ -208,6 +223,17 @@ export interface PaymentServiceClient {
 
   getPaymentByOrder(request: GetPaymentByOrderRequest): Observable<PaymentResponse>;
 
+  /**
+   * Платіж ДОПЛАТИ за врегулюванням. `GetPaymentByOrder` для цього не
+   * годиться: він завжди віддає основний платіж замовлення.
+   */
+
+  getPaymentByAdjustment(request: GetPaymentByAdjustmentRequest): Observable<PaymentResponse>;
+
+  /** Усі платежі замовлення (основний + доплати) — для звірки сум. */
+
+  listOrderPayments(request: GetPaymentByOrderRequest): Observable<ListPaymentsResponse>;
+
   listPayments(request: ListPaymentsRequest): Observable<ListPaymentsResponse>;
 
   capture(request: CaptureRequest): Observable<PaymentResponse>;
@@ -246,6 +272,21 @@ export interface PaymentServiceController {
     request: GetPaymentByOrderRequest,
   ): Promise<PaymentResponse> | Observable<PaymentResponse> | PaymentResponse;
 
+  /**
+   * Платіж ДОПЛАТИ за врегулюванням. `GetPaymentByOrder` для цього не
+   * годиться: він завжди віддає основний платіж замовлення.
+   */
+
+  getPaymentByAdjustment(
+    request: GetPaymentByAdjustmentRequest,
+  ): Promise<PaymentResponse> | Observable<PaymentResponse> | PaymentResponse;
+
+  /** Усі платежі замовлення (основний + доплати) — для звірки сум. */
+
+  listOrderPayments(
+    request: GetPaymentByOrderRequest,
+  ): Promise<ListPaymentsResponse> | Observable<ListPaymentsResponse> | ListPaymentsResponse;
+
   listPayments(
     request: ListPaymentsRequest,
   ): Promise<ListPaymentsResponse> | Observable<ListPaymentsResponse> | ListPaymentsResponse;
@@ -297,6 +338,8 @@ export function PaymentServiceControllerMethods() {
       "createInvoice",
       "getPayment",
       "getPaymentByOrder",
+      "getPaymentByAdjustment",
+      "listOrderPayments",
       "listPayments",
       "capture",
       "markPaidOffline",

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@mamindom/contracts",
 	"description": "proto",
-	"version": "1.0.207",
+	"version": "1.0.210",
 	"main": "./dist/src/index.js",
 	"types": "./dist/src/index.d.ts",
 	"exports": {

package/proto/order.proto

@@ -36,6 +36,24 @@ service OrderService {
 
   rpc ApplyOneCStatus(ApplyOneCStatusRequest) returns (OrderResponse);
 
+
+  // Врегулювання грошей після перерахунку (доплата / повернення).
+  rpc ListMoneyAdjustments(ListMoneyAdjustmentsRequest) returns (ListMoneyAdjustmentsResponse);
+  rpc GetMoneyAdjustment(GetMoneyAdjustmentRequest) returns (MoneyAdjustmentResponse);
+  // Перевірка ПЕРЕД створенням рахунку: чи можна взагалі виставляти доплату.
+  // Без неї платіжне посилання встигало зʼявитись раніше за відмову.
+  rpc AssertCanIssueSurcharge(GetMoneyAdjustmentRequest) returns (MoneyAdjustmentResponse);
+  rpc MarkSurchargeIssued(MarkSurchargeIssuedRequest) returns (MoneyAdjustmentResponse);
+  rpc SettleMoneyAdjustment(SettleMoneyAdjustmentRequest) returns (MoneyAdjustmentResponse);
+  rpc DismissMoneyAdjustment(DismissMoneyAdjustmentRequest) returns (MoneyAdjustmentResponse);
+
+  // Розбір заторів у черзі подій: подія, яка вичерпала ретраї, навмисно
+  // блокує всі наступні події свого замовлення (інакше `stock.reserve` поїхав
+  // би без свого `stock.release`). Тому потрібен і вихід із цього стану.
+  rpc ListStuckEvents(ListStuckEventsRequest) returns (ListStuckEventsResponse);
+  rpc RetryStuckEvents(StuckEventsActionRequest) returns (StuckEventsActionResponse);
+  rpc DismissStuckEvents(StuckEventsActionRequest) returns (StuckEventsActionResponse);
+
   rpc ConfirmPickup(ConfirmPickupRequest) returns (OrderResponse);
 
   rpc ReorderOrder(ReorderOrderRequest) returns (ReorderResponse);
@@ -319,7 +337,11 @@ message OrderItemInput {
   string product_id = 1;
   string variant_id = 2;
   int32 quantity = 3;
+
   double price_override = 4;
+
+  
+  bool price_provided = 5;
 }
 
 message GetOrderRequest {
@@ -393,6 +415,114 @@ message SetCrmOrderIdRequest {
 }
 
 
+
+message MoneyAdjustment {
+  string id       = 1;
+  string order_id = 2;
+
+  
+  string kind = 3;
+
+  
+  string status = 4;
+
+  
+  double amount       = 5;
+  double total_before = 6;
+  double total_after  = 7;
+
+  string source = 8;
+
+  string payment_id  = 9;
+  string payment_url = 10;
+  int64  expires_at  = 11;
+
+  string resolved_by    = 12;
+  int64  resolved_at    = 13;
+  string resolution     = 14;
+  string dismiss_reason = 15;
+
+  int64 created_at = 16;
+  int64 updated_at = 17;
+}
+
+message MoneyAdjustmentResponse {
+  bool ok = 1;
+  MoneyAdjustment adjustment = 2;
+  string error_message = 3;
+}
+
+message ListMoneyAdjustmentsRequest {
+  
+  string order_id = 1;
+  bool only_open  = 2;
+  int32 limit     = 3;
+}
+
+message ListMoneyAdjustmentsResponse {
+  repeated MoneyAdjustment items = 1;
+}
+
+message GetMoneyAdjustmentRequest {
+  string id = 1;
+}
+
+message MarkSurchargeIssuedRequest {
+  string id          = 1;
+  string payment_id  = 2;
+  string payment_url = 3;
+  string actor_id    = 4;
+  string actor_name  = 5;
+}
+
+message SettleMoneyAdjustmentRequest {
+  string id         = 1;
+  string resolution = 2;
+  string actor_id   = 3;
+  string actor_name = 4;
+
+  
+  string payment_id = 5;
+
+
+  double amount     = 6;
+  bool amount_provided = 7;
+}
+
+message DismissMoneyAdjustmentRequest {
+  string id         = 1;
+  string reason     = 2;
+  string actor_id   = 3;
+  string actor_name = 4;
+}
+
+message ListStuckEventsRequest {
+  int32 limit = 1;
+}
+
+message StuckEvent {
+  string id            = 1;
+  string pattern       = 2;
+  string order_key     = 3;
+  int32  attempts      = 4;
+  string last_error    = 5;
+  int64  created_at    = 6;
+  bool   acknowledged  = 7;
+}
+
+message ListStuckEventsResponse {
+  repeated StuckEvent items = 1;
+}
+
+message StuckEventsActionRequest {
+  repeated string ids = 1;
+  string actor_id     = 2;
+}
+
+message StuckEventsActionResponse {
+  int32 affected = 1;
+}
+
 message SetOneCOrderRefRequest {
   string id = 1;
 

package/proto/payment.proto

@@ -8,6 +8,11 @@ service PaymentService {
 
   rpc GetPayment(GetPaymentRequest) returns (PaymentResponse);
   rpc GetPaymentByOrder(GetPaymentByOrderRequest) returns (PaymentResponse);
+  // Платіж ДОПЛАТИ за врегулюванням. `GetPaymentByOrder` для цього не
+  // годиться: він завжди віддає основний платіж замовлення.
+  rpc GetPaymentByAdjustment(GetPaymentByAdjustmentRequest) returns (PaymentResponse);
+  // Усі платежі замовлення (основний + доплати) — для звірки сум.
+  rpc ListOrderPayments(GetPaymentByOrderRequest) returns (ListPaymentsResponse);
   rpc ListPayments(ListPaymentsRequest) returns (ListPaymentsResponse);
 
   
@@ -63,6 +68,10 @@ message Payment {
   
   string capture_source = 19;
   string capture_note = 20;
+
+  // Тип платежу і врегулювання, яке його породило (див. CreateInvoiceRequest).
+  string kind = 21;
+  string adjustment_id = 22;
 }
 
 message PaymentProviderInfo {
@@ -95,6 +104,14 @@ message CreateInvoiceRequest {
   string customer_email  = 8;
   string customer_phone  = 9;
   repeated InvoiceItem items = 10;
+
+  // `primary` (за замовчуванням) — оплата замовлення; `surcharge` — доплата
+  // за перерахунком у 1С. На замовлення може бути один основний платіж і
+  // скільки завгодно доплат.
+  string kind = 11;
+
+  // Врегулювання, яке породило доплату (`order_money_adjustments`).
+  string adjustment_id = 12;
 }
 
 message InvoiceItem {
@@ -112,6 +129,10 @@ message GetPaymentByOrderRequest {
   string order_id = 1;
 }
 
+message GetPaymentByAdjustmentRequest {
+  string adjustment_id = 1;
+}
+
 message ListPaymentsRequest {
   int32  page = 1;
   int32  limit = 2;