Інтеграція Хорошоп

Так, тут справді є суттєва зміна, і клієнт правильно звернув на неї увагу.

В актуальній документації catalog/import Хорошоп розділяє два режими обліку залишків.

Якщо «Облік залишків на складах» вимкнений, працює звичайний:

"presence": "В наявності"

Причому документація прямо зазначає, що products[i].presence можна передавати лише коли складський облік вимкнений. Notion

А якщо «Облік залишків на складах» увімкнений, Хорошоп очікує вже не quantity, а масив:

"residues": [
  {
    "warehouse": "Основний склад",
    "quantity": 15
  }
]

де:

• products[i].residues — залишки по складах;
• products[i].residues[n].warehouse — саме «Назва для синхронізації» складу в Хорошопі;
• products[i].residues[n].quantity — кількість на цьому складі. Notion

І це в документації винесено як «Нові параметри з версії 3.15.15». Notion

Що це означає для нашого коду

Зараз ми робимо:

Quantity = link.TotalQuantity,
Presence = link.IsAvailable ? "В наявності" : "Немає в наявності",

Для сайту, де клієнт увімкнув складський облік Хорошопа, це вже не та модель. Його слова:

залишки не підтягнулись

цілком пояснюються цим.

Ба більше, в актуальному переліку параметрів catalog/import, який я зараз переглянув, я взагалі не бачу старого products[i].quantity як рекомендованого поля залишку. Для складського режиму Хорошоп чітко описує residues. Notion

Нам треба вирішити, як представити склад Хорошопа

На першому етапі я б не будував складне зіставлення кількох складів Shopserver ↔ кілька складів Хорошопа.

У нас уже є:

link.TotalQuantity

тобто сумарний доступний залишок по підрозділах, які працюють із цим сайтом.

Тому я б додав до WebSite ще одне налаштування, наприклад:

public string? WarehouseSynchronizationName { get; private set; }

У UI:

Назва складу для синхронізації

Клієнт бере цю назву з налаштувань складу Хорошопа, з поля «Назва для синхронізації».

І тоді формуємо:

"residues": [
  {
    "warehouse": "Shopserver",
    "quantity": 18
  }
]

де 18 — наш link.TotalQuantity.

DTO приблизно такий

public sealed class HoroshopProductResidue
{
    [JsonPropertyName("warehouse")]
    public string Warehouse { get; set; }

    [JsonPropertyName("quantity")]
    public double Quantity { get; set; }
}

і:

[JsonPropertyName("residues")]
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public HoroshopProductResidue[]? Residues { get; set; }

А в CreateActiveProduct:

Residues = new[]
{
    new HoroshopProductResidue
    {
        Warehouse = changes.WarehouseSynchronizationName,
        Quantity = link.TotalQuantity
    }
},

При цьому Presence для такого режиму взагалі не треба передавати, бо документація прямо каже, що воно для режиму без складського обліку. Notion

Тобто клієнт фактично знайшов нам важливий нюанс API. І я думаю, тепер стає зрозуміло, чому після ввімкнення «Обліку залишків» у нього описи синхронізувалися, а кількість — ні: Хорошоп переключився на іншу модель залишків, а ми продовжили відправляти стару.

Я б наступним кроком саме це й виправив: додав назву складу синхронізації й перейшов для складського режиму на products[i].residues.

Так, це зараз ключова проблема нашої моделі, і твій GetPrimaryDepartment() фактично її маскує: ми агрегуємо залишки по кількох Department, а при поверненні замовлення довільно кладемо всю накладну на один перший склад.

І я перевірив актуальну документацію Хорошопа. В catalog/import дійсно можна передавати залишки по кількох складах через products[i].residues[n].warehouse + quantity. Notion Але в orders/get я не бачу поля, яке б повертало розподіл кожної товарної позиції замовлення по складах. Є additionalData, де можуть бути дані про склад відправника/одержувача доставки, але це не те саме, що «цей товар 2 шт зі складу A і 1 шт зі складу B». Notion

Тому поки що я б виходив із того, що Хорошоп сам для нас потрібний розподіл назад не повертає.

Тоді при імпорті чека Shopserver має сам виконати allocation.

Наприклад, сайт агрегує два підрозділи:

Склад A:
товар X = 2
товар Y = 5

Склад B:
товар X = 4
товар Z = 3

Покупець замовив:

X = 5
Y = 1
Z = 2

Shopserver може розкласти це так:

SalesInvoice #1, Department A
X = 2
Y = 1

SalesInvoice #2, Department B
X = 3
Z = 2

Обидві накладні лежать в одному контейнері одного чека Хорошопа.

Це дуже добре лягає на нашу модель ContainerDto, бо контейнер і так може містити кілька документів.

Але алгоритм розподілу треба визначити детерміновано. Я б для першої версії зробив максимально простий:

1. Беремо всі активні WebSiteDepartmentLink цього сайту.
2. Для кожної позиції дивимося поточні InventoryRecord.
3. Йдемо по складах у стабільному порядку.
4. Забираємо товар із першого складу, де він є, до вичерпання залишку.
5. Якщо треба — продовжуємо з наступного складу.
6. Потім групуємо отримані рядки за DepartmentId і формуємо по одній SalesInvoice на кожний склад.

Наприклад:

потрібно X = 7

A має 3 → беремо 3
B має 10 → беремо 4

Далі дві накладні.

Але тут є одна дуже важлива проблема: наш поточний InventoryRecord.Quantity може вже не відповідати тому залишку, який був у момент оформлення замовлення Хорошопа. Між замовленням і статусом 6/3 товар могли продати локально.

Тому розкладати заднім числом по поточних залишках — це best effort, а не абсолютна істина.

Саме тому я б поки не передавав у Хорошоп фізичні склади Shopserver окремо. Якщо Хорошоп не повертає складову позиції замовлення назад, ми створимо собі складну задачу без інформації для її точного розв'язання.

Практичніший варіант для першої версії:

в Хорошопі один логічний склад "Shopserver"
quantity = TotalQuantity по всіх WebSiteDepartmentLinks

А при імпорті Shopserver сам розкладає чек по своїх складах за поточними доступними залишками.

Тобто warehouse в Хорошопі — це не фізичний Department, а агрегований канал доступності товару.

Саме тому я б зараз не міняв catalog/import на передачу кожного Department окремо. Спершу варто або отримати від підтримки Хорошопа підтвердження, що orders/get повертає розподіл позицій по складах, або прийняти модель одного логічного складу. За поточною документацією такого розподілу я не бачу.