Онбординг клієнта в EDIN Акциз

Огляд

Документація описує процес підключення нового клієнта (економічного оператора) до EDIN Акциз: реєстрацію в Client Service та наповнення базових довідників у MasterData. Порядок кроків важливий — частина довідників посилається на записи, створені на попередніх кроках (юридична особа → бізнес-одиниця → об’єкт Клієнта (економічного оператора) → мапінг об’єкта тощо).

Передумови

Необхідно згенерувати API ключ в державному кабінеті єАкциз.

Ключові можливості

• Отримання даних оператора з держреєстру за apiKey (єАкциз) без ручного введення реквізитів
• Реєстрація клієнта в EDIN Акциз на основі отриманого попереднього перегляду
• Повний набір довідників MasterData — юридичні особи, бізнес-одиниці, товари, одиниці виміру, штрихкоди продажу, об’єкти клієнта, мапінги об’єктів, контрагенти, типи протоколів
• Для кожного довідника доступні однакові чотири операції — створити один запис, отримати всі, отримати за id, створити пакетно (batch)

---

Happy path

#	Метод	Ендпоінт	Призначення
1	POST	{{DES_CLIENT_BASE_URL}}/api/des-client/onboarding/preview	Попередній перегляд даних клієнта (економічного оператора) в еАкциз за apiKey
2	POST	{{DES_CLIENT_BASE_URL}}/api/des-client/onboarding/register-client	Реєстрація клієнта (економічного оператора) в EDIN Акциз
3	POST	{{MASTERDATA_BASE_URL}}/legal-units	Створити юридичну особу клієнта
4	POST	{{MASTERDATA_BASE_URL}}/business-units	Створити бізнес-одиницю (філія / РЦ / магазин/ інше)
5	POST	{{MASTERDATA_BASE_URL}}/articles	Створити товар
6	POST	{{MASTERDATA_BASE_URL}}/sale-codes	Створити прив’язку штрихкоду до товару
7	POST	{{MASTERDATA_BASE_URL}}/des-objects	Об’єкт клієнта (економічного оператора) що завантажуються із єАкциз
8	POST	{{MASTERDATA_BASE_URL}}/des-object-mappings	Прив’язати об’єкт клієнта (економічного оператора) із єАкциз до бізнес-одиниці
9	POST	{{MASTERDATA_BASE_URL}}/des-protocol-types (уточнюйте в команди розробки)	Налаштувати мапінг типів протоколів

1. Попередній перегляд оператора — POST {{DES_CLIENT_BASE_URL}}/api/des-client/onboarding/preview

Отримує дані оператора з держреєстру (єАкциз) за apiKey. Результат автоматично зберігається у змінні колекції для наступного кроку реєстрації.

{
  "apiKey": "{{ApiToken}}"
}

apiKey — ключ, згенерований на xtrace.gov.ua.

2. Реєстрація клієнта (економічного оператора) — POST {{DES_CLIENT_BASE_URL}}/api/des-client/onboarding/register-client

Реєструє клієнта (економічного оператора) в EDIN Акциз на основі даних, отриманих на кроці 1. Обов’язково виконати preview перед цим запитом.

{
  "id": "{{PreviewClientId}}",
  "code": "{{PreviewClientCode}}",
  "organizationId": "{{PreviewClientOrganizationId}}",
  "type": "{{PreviewClientType}}",
  "name": "{{PreviewClientName}}",
  "taxId": "{{PreviewClientTaxId}}"
}

Усі поля підставляються зі значень, збережених на кроці preview. Отриманий ідентифікатор оператора (RegisteredDesClientId) знадобиться для довідників des-objects, des-counterparties, des-protocol-types.

3. Юридична особа — POST {{MASTERDATA_BASE_URL}}/legal-units

Додавання юридичної особи клієнта

{
  "item": {
    "tenant": "edin",
    "legalUnitId": "1",
    "name": "ТОВ \"ЄДІН\"",
    "countryId": "",
    "currencyId": "",
    "externalIds": { "sapId": "" }
  }
}

countryId, currencyId, externalIds.sapId можна залишати порожніми.

4. Бізнес-одиниця — POST {{MASTERDATA_BASE_URL}}/business-units

Бізнес-одиниця — це філія, РЦ, магазин або інша одиниця що використовується клієнтом для ідентифікації власних об’єктів

{
  "item": {
    "tenant": "edin",
    "businessUnitId": "4456606",
    "name": "Назва вашого РЦ або магазину",
    "businessId": "1",
    "legalUnitId": "{{LegalUnitId}}",
    "externalIds": { "sapId": "", "counterPartyId": "" }
  }
}

legalUnitId — ідентифікатор юридичної особи, створеної на кроці 3. businessId завжди "1". externalIds.sapId / counterPartyId обов’язкові за контрактом, але можуть бути порожніми.

5. Товар — POST {{MASTERDATA_BASE_URL}}/articles

Створює товар у довіднику MasterData. Товар має бути створений перед прив’язкою штрихкоду продажу (крок 6) — articleId у sale-codes посилається саме на цей товар.

6. Штрихкод продажу — POST {{MASTERDATA_BASE_URL}}/sale-codes

Прив’язує штрихкод продажу (той, що сканується на касі) до товару та одиниці продажу. Виконується після створення товару (крок 5) — articleId має посилатися на вже існуючий товар.

{
  "item": {
    "tenant": "edin",
    "saleCodeId": "SC-001",
    "articleId": "{{ArticleId}}",
    "saleUnitId": "{{SaleUnitId}}",
    "barcodeTypeId": 1,
    "barcode": "4820000000001",
    "startDate": "2024-01-01T00:00:00.000Z",
    "endDate": null,
    "isDefault": true
  }
}

Поле	Тип	Опис
tenant	string	Ідентифікатор тенанта — "edin"
saleCodeId	string	Ідентифікатор запису штрихкоду продажу (задає клієнт)
articleId	string	Товар, до якого прив’язується штрихкод. Має відповідати вже створеному товару (крок 5)
saleUnitId	string	Одиниця продажу товару
barcodeTypeId	number	Тип штрихкоду
barcode	string	Значення штрихкоду продажу
startDate	datetime	Дата початку дії штрихкоду
endDate	datetime | null	Дата завершення дії; null — безстроково
isDefault	boolean	Чи це основний штрихкод товару

7. Об’єкт EDIN Акциз — POST {{MASTERDATA_BASE_URL}}/des-objects

Описує фізичну або логічну локацію оператора (магазин, РЦ, склад).

{
  "item": {
    "desObjectId": "{{DesObjectId}}",
    "operatorId": "{{RegisteredDesClientId}}",
    "objectId": "{{BusinessUnitId}}",
    "objectCode": "OBJ-{{BusinessUnitId}}"
  }
}

operatorId — GUID оператора, отриманий після реєстрації клієнта (крок 2).

У чому різниця між business-units і des-objects:

• business-units — це представлення філії/РЦ/магазину на стороні клієнта, у його власній обліковій структурі. Прив’язується до legalUnitId (юридичної особи клієнта). Ідентифікатор і назва задаються клієнтом — це, по суті, копія його внутрішнього довідника об’єктів в MasterData.
• des-objects — це представлення тієї самої локації на стороні EDIN Акциз, у межах зареєстрованого в EDIN Акциз оператора (operatorId, отриманий після register-client). Дані для нього надходять із xTrace — тобто це об’єкт, який EDIN Акциз уже знає з держреєстру, а не той, що довільно створює клієнт.

Оскільки це два незалежні записи в різних доменах (клієнтський і державний/EDIN Акциз), їх потрібно явно зв’язати між собою — для цього й існує наступний крок, “Мапінг об’єкта EDIN Акциз”: він з’єднує desObjectId з відповідним businessUnitId, щоб сервіси EDIN Акциз знали, якому об’єкту клієнта відповідає який об’єкт EDIN Акциз.

8. Мапінг об’єкта EDIN Акциз — POST {{MASTERDATA_BASE_URL}}/des-object-mappings

Прив’язує des-object до цілі — найчастіше до бізнес-одиниці.

{
  "item": {
    "desObjectMappingId": "{{DesObjectMappingId}}",
    "desObjectId": "{{DesObjectId}}",
    "targetType": "BusinessUnit",
    "targetId": "{{BusinessUnitId}}"
  }
}

Створюється після відповідних des-objects і business-units. Дозволяє сервісам EDIN Акциз знаходити об’єкти за фільтром на business unit

9. Тип протоколу — POST {{MASTERDATA_BASE_URL}}/des-protocol-types (уточнюйте в команди розробки)

Мапить protocolType / operationType / operationDocumentType на businessProcessType для фільтрів списку протоколів (наприклад, protocolType: "receiving", operationType: "receiving").

{
  "item": {
    "id": "{{DesProtocolTypeId}}",
    "operatorCode": "{{PreviewClientCode}}",
    "protocolType": "receiving",
    "operationType": "receiving"
  }
}

operatorCode має вже існувати в des-clients (тобто після кроків 1–2).

---

Діаграма процесу

sequenceDiagram
    actor Integrator as Інтегратор
    participant Client as des-client
    participant MD as MasterData

    Integrator->>Client: POST /onboarding/preview (apiKey)
    Client-->>Integrator: дані оператора з реєстру

    Integrator->>Client: POST /onboarding/register-client
    Client-->>Integrator: RegisteredDesClientId

    Integrator->>MD: POST /legal-units
    MD-->>Integrator: LegalUnitId

    Integrator->>MD: POST /business-units (legalUnitId)
    MD-->>Integrator: BusinessUnitId

    Integrator->>MD: POST /articles
    MD-->>Integrator: ArticleId
    Integrator->>MD: POST /sale-codes (articleId)

    Integrator->>MD: POST /des-objects (operatorId, businessUnitId)
    MD-->>Integrator: DesObjectId

    Integrator->>MD: POST /des-object-mappings (desObjectId, targetId=BusinessUnitId)

    Integrator->>MD: POST /des-counterparties (operatorId, operatorCode)

    Integrator->>MD: POST /des-protocol-types (operatorCode)

---

Найкращі практики

Порядок кроків

1. Завжди виконуйте preview перед register-client — реєстрація залежить від щойно отриманих даних
2. Створюйте legal-units перед business-units, business-units і des-objects перед des-object-mappings, articles перед sale-codes
3. des-objects, des-counterparties і des-protocol-types вимагають, щоб реєстрація оператора (крок 2) вже відбулася — саме звідти беруться operatorId/operatorCode

Наповнення довідників

1. Для масового завантаження використовуйте batch-ендпоінти замість циклу поодиноких запитів
2. Не змінюйте структуру JSON. Якщо даних немає - передавайте пустий рядок “”
3. Узгодьте власну систему первинних ключів (legalUnitId, businessUnitId, desObjectId тощо) заздалегідь — вони входять до складених первинних ключів разом з tenant