ТЗ: імпорт замовлень у 1С із хмарного проксі

Технічне завдання · інтеграція замовлень із 1С

Статусузгоджено із замовником, готується до передачі розробникам 1С

Конфігурація 1СУТП (Управління торговельним підприємством)

Напрямокхмарний проксі (Cloud Run) → вебсервіс 1С, метод POST, тіло JSON

Версія контракту1.0

1. Загальна схема

Замовлення із сайту kohani.com.ua (Horoshop), із CRM KeyCRM і в майбутньому з бота спочатку

потрапляють у хмарний проксі. Проксі приводить їх до єдиного вигляду й одним запитом надсилає

в 1С. 1С не знає про особливості систем-джерел — він отримує один нормалізований контракт.

Що 1С робить із замовленням:

• створює «Замовлення покупця» від імені поточного активного ФОПа;
• завжди проводить замовлення → товар резервується (резерв безумовний, від оплати не залежить);
• склад резерву обирає сама 1С за наявністю;
• повертає проксі номер, дату та GUID створеного замовлення;
• реалізацію НЕ створює автоматично — це окреме завдання на майбутнє.

2. Транспорт і авторизація

1С зобовʼязаний повернути JSON-відповідь за §6 (і при успіху, і при помилці).

3. Ідемпотентність і дедуплікація замовлень

Проксі може надіслати одне й те саме замовлення повторно (повтор при таймауті/обриві звʼязку).

Дублі неприпустимі.

• 1С нумерує замовлення своєю нумерацією; source + external_number для неї — довідкові

поля (зберігає в замовленні, може знадобитися для майбутніх оновлень оплати).

• Але саме за парою `source` + `external_number` 1С перевіряє дубль: перед створенням дивиться,

чи немає вже замовлення з такою парою. Є → не створює нове, повертає наявне (номер, дату,

GUID) зі status: duplicate.

4. Бізнес-правила на боці 1С

1. Дедуплікація замовлення — за source + external_number (§3).
2. Дедуплікація контрагента — за нормалізованим телефоном (основний ключ; 1С нормалізує

сама, ми надсилаємо міжнародний формат). Email — вторинна підказка для збагачення картки.

**Перед запуском автоматизації розробники 1С проводять разову процедуру дедуплікації наявних

контрагентів**, щоб автостворення не плодило дублі поверх «брудної» бази.

1. Резерв — замовлення завжди проводиться, товар резервується. Склад резерву обирає 1С за

наявністю (уточнюється при узгодженні контракту; проксі за потреби може запитати в 1С наявність

перед створенням замовлення).

1. Суми — 1С приймає price / sum / total як є, не перераховує (джерело істини щодо

грошей — проксі: клієнт стільки заплатив). При розбіжності total і суми рядків — повертає

warning, але замовлення створює.

1. Реалізація — не створюється автоматично (окреме завдання).

5. Структура вхідного JSON

Повний приклад — §7. Обовʼязковість: О — обовʼязково, Н — необовʼязково.

5.1. Шапка

5.2. Контрагент (customer) — замовник/платник

Лише фізособи. Надсилаємо завжди.

5.3. Отримувач (recipient)

Надсилаємо завжди повним блоком, навіть якщо збігається з контрагентом (1С не розгалужується).

5.4. Доставка (delivery)

Отримувач НП — завжди «Приватна особа». Міста/відділення/вулиці НП передаємо парою `ref` + назва

(API НП вимагає звʼязку). Підтримуються всі види доставки з довідника 1С.

5.5. Оплата (payment)

5.6. Відвантаження (shipping)

5.7. Товари (items[])

Мінімум один рядок.

5.8. Послуги (services[])

Окрема вкладка «Послуги» в «Замовленні покупця». Наразі єдиний кейс — **доставка, якщо її сплатив

клієнт наперед**. Якщо доставку платить отримувач на НП — секція порожня.

5.9. Підсумки (totals)

Контрольні суми для звірки.

6. Контракт відповіді 1С

HTTP-коди й логіка повторів проксі:

Успіх (200)

{
  "ok": true,
  "order_number": "Ц0000008337",
  "order_date": "2026-06-12T14:05:00",
  "order_guid": "a1b2c3d4-0000-0000-0000-000000000000",
  "status": "created",
  "reservation": {
    "status": "partial",
    "shortages": [
      { "article": "Ц00002556", "requested": 2, "reserved": 1 }
    ]
  }
}

• status: created | duplicate.
• reservation.status: full | partial | none. За partial/none замовлення створене, але не проведене — резерв не відбувся; проксі надсилає менеджерам сповіщення в Telegram зі списком shortages для ручного втручання.

Помилка (400/401/500)

{
  "ok": false,
  "errors": [
    { "code": "ARTICLE_NOT_FOUND", "field": "items[2].article", "value": "X999", "message": "Номенклатура не знайдена" }
  ]
}

Коди (пропозиція): AUTH_FAILED, VALIDATION_ERROR, ARTICLE_NOT_FOUND, INTERNAL_ERROR.

7. Повний приклад запиту (накладений платіж, відділення НП)

{
  "source": "keycrm",
  "external_number": "12345",
  "external_created_at": "2026-06-12T10:30:00Z",
  "fop": "Ц00000005",
  "price_type": "000000001",
  "comment": "Прошу зателефонувати за годину до доставки",

  "customer": {
    "full_name": "Іваненко Іван Іванович",
    "phone": "+380501234567",
    "email": "ivan@example.com"
  },
  "recipient": {
    "full_name": "Петренко Петро Петрович",
    "phone": "+380671112233"
  },

  "delivery": {
    "carrier": "nova_poshta",
    "type": "00000000123",
    "city_ref": "8d5a980d-391c-11dd-90d9-001a92567626",
    "city_name": "Київ",
    "warehouse_ref": "1ec09d2e-e1c2-11e3-8c4a-0050568002cf",
    "warehouse_name": "Відділення №5: вул. Хрещатик, 22",
    "street_ref": null,
    "street_name": null,
    "building": null,
    "flat": null,
    "declared_value": 4400,
    "cod_amount": 4400,
    "cargo_description": "взуття"
  },

  "payment": {
    "method": "00000000045",
    "channel": "novapay",
    "status": "unpaid",
    "paid_amount": 0,
    "paid_at": null
  },

  "shipping": {
    "desired_date": "2026-06-13"
  },

  "items": [
    {
      "article": "Ц00002556",
      "name": "Лофери Лоретто блакитний замш, 38",
      "quantity": 1,
      "unit": "пар",
      "price": 4400,
      "price_without_discount": 4900,
      "discount_percent": 10.2,
      "discount_amount": 500,
      "vat_rate": 0,
      "vat_amount": 0,
      "sum": 4400
    }
  ],

  "services": [],

  "totals": {
    "items_sum": 4400,
    "discount_total": 500,
    "services_sum": 0,
    "total": 4400
  }
}

8. Поза межами цього ТЗ (окремими завданнями)

• Створення реалізації (автоматично чи інакше).
• Повернення, обміни, компенсації доставки, брак — окремі документи/процеси 1С.
• Юрособи / B2B — поки лише фізособи.
• ПДВ — поки працюємо без ПДВ (vat_* = 0).