Готова обробка обміну

Для облікових систем на платформі BAS і сумісних є універсальна обробка обміну з ApexSFA (бета-версія 0.1) — зовнішня обробка, яка реалізує весь протокол обміну без програмування: підпис запитів, передачу довідників і документів, забір заявок.

8.1. Що вона робить

• Універсальний обмін за картою відповідностей. Ви самі обираєте, з яких обʼєктів вашої бази брати дані: довідник товарів, контрагентів, точок, регістри залишків і боргів, документи продажів. Для кожного поля ApexSFA вказується реквізит, табличну частину, вимір або ресурс регістру — або константа.
• Шаблони карт для поширених конфігурацій: заповнюють карту одним кліком, далі її можна підправити під доопрацювання вашої бази.
• «Перевірити карту» — звірка кожного шляху з метаданими бази й тестова вибірка по 5 записів кожного розділу без відправки: видно, що саме піде в ApexSFA, і де карта посилається на неіснуючі реквізити.
• Вивантаження в ApexSFA: довідники, ціни, залишки, продажі, борги — пакетами, з повтором при перевищенні ліміту чи збоях звʼязку.
• Прийом з ApexSFA: заявки торгових — у документ вашої бази, з підтвердженням кожного документа й без дублів при повторах.
• Журнал обміну в самій обробці та на порталі ApexSFA.

8.2. Як встановити

1. Завантажте й підключіть обробку. Файл — на apexsfa.com/developers/ready-exchange. Підключіть його через «Додаткові звіти та обробки» (у конфігураціях з БСП — BAS, УТ 11) або відкрийте як зовнішню через «Файл → Відкрити».
2. Налаштування підключення: адреса API https://api.apexsfa.com/api/v1, Tenant Id і ключ обміну — їх видає команда ApexSFA при підключенні точки синхронізації. Кнопка перевірки звʼязку робить підписаний тестовий запит.
3. Шаблон карти: оберіть шаблон своєї конфігурації — розділи обміну заповняться автоматично; заповніть параметри (наприклад, перелік виробників в обміні).
4. «Перевірити карту»: обробка звіряє кожен шлях карти з метаданими вашої бази й робить тестову вибірку по 5 записів у кожному розділі. Виправте поля, позначені помилкою. Перший обмін запускайте на копії бази, а не на робочій; якщо потрібна допомога з налаштуванням карти під вашу конфігурацію — запросіть її.
5. Розклад: додайте команди «Повний обмін», «Вивантаження», «Завантаження» в розклад «Додаткових звітів та обробок» (рекомендовано: довідники й залишки — кожні 15–30 хв, продажі, борги й забір заявок — кожні 5–15 хв) або запускайте обмін вручну.

8.3. Вимоги

• Платформа 8.3, керовані форми (тонкий клієнт або веб-клієнт).
• Право на підключення зовнішніх обробок; для розкладу — підсистема «Додаткові звіти та обробки» (БСП) або регламентне завдання конфігурації.
• Вихідний HTTPS-доступ до api.apexsfa.com (порт 443), кореневі сертифікати операційної системи.
• Окремий ключ обміну на кожну базу (точку синхронізації).

8.4. Що вміє перша версія

Далі в планах: оплати, каса, постачальники, водії й рейси, коди мереж.

Захист даних: обробка нічого не записує в облік, крім документів із розділів завантаження; якщо джерело залишків чи боргів не прочиталося — нічого не відправляє (щоб не обнулити дані в ApexSFA); карта не може виконати довільний код — лише звірені з метаданими імена й параметри.

8.5. Формат карти відповідностей

Карта зберігається в налаштуваннях обробки й експортується файлом JSON (без ключа обміну) — так її зручно переносити між базами й передавати нашій підтримці.

{
  "format": "apexsfa.map/1",
  "name": "Моя конфігурація",
  "params": [
    {"name": "Производители", "type": "Справочник.Производители", "list": true, "title": "Виробники в обміні"}
  ],
  "sections": [
    {
      "id": "products", "entity": "product", "title": "Номенклатура", "enabled": true,
      "sources": [{
        "table": "Справочник.Номенклатура",
        "filters": [
          {"field": "ЭтоГруппа", "op": "=", "value": false},
          {"field": "Производитель", "op": "В", "param": "Производители", "skip_if_empty": true}
        ],
        "fields": {
          "external_id": {"path": "Ссылка", "as": "guid"},
          "name": {"path": "НаименованиеПолное", "fallback": "Наименование"},
          "sku": {"path": "Артикул"},
          "manufacturer_external_id": {"path": "Производитель.Код", "as": "string"},
          "vat_rate": {"const": 20}
        }
      }]
    },
    {
      "id": "stock", "entity": "product_stock", "title": "Залишки", "enabled": true,
      "sources": [{
        "table": "РегистрНакопления.ТоварыНаСкладах", "virtual": "Остатки",
        "fields": {
          "warehouse_code_1c": {"path": "Склад", "as": "guid"},
          "product_code_1c": {"path": "Номенклатура", "as": "guid"},
          "qty": {"path": "КоличествоОстаток", "agg": "sum"}
        }
      }]
    }
  ],
  "imports": [
    {
      "id": "orders", "entity": "order", "order_type": "sale",
      "document": "Документ.РеализацияТоваров", "write_mode": "write",
      "dedupe": {"attribute": "НомерВходящего", "payload": "order_number", "days": 180},
      "lookups": {
        "client": {"table": "Справочник.Контрагенты", "payload": "client_code_1c", "by": "guid", "required": true},
        "product": {"table": "Справочник.Номенклатура", "payload": "product_code_1c", "by": "guid", "level": "line", "required": true}
      },
      "header": {"Контрагент": {"lookup": "client"}},
      "lines": {"table": "Товары", "fields": {
        "Номенклатура": {"lookup": "product"},
        "Количество": {"line": "quantity", "as": "number"},
        "Цена": {"line": "unit_price", "as": "number"}
      }}
    }
  ]
}

Розділ вивантаження (sections[]): entity — тип сутності ApexSFA з розділу 3a; sources[] — одне або кілька джерел (кожне — простий запит до однієї таблиці); table — обʼєкт метаданих (Справочник.…, Документ.…[.ТабличнаЧастина], РегистрСведений.…, РегистрНакопления.…); virtual — віртуальна таблиця (СрезПоследних, Остатки, Обороты); filters[] — відбори.

Способи заповнення поля (fields.<поле ApexSFA>):

Відбір (filters[]): field — шлях; op — =, <>, >, >=, <, <=, В, НЕ В, В ИЕРАРХИИ, ЗАПОЛНЕНО, НЕ ЗАПОЛНЕНО, ССЫЛКА; значення — value або param (+ skip_if_empty).

Розділ завантаження (imports[]): документ обліку, режим write/post, захист від дублів dedupe (реквізит документа ↔ номер заявки), пошук посилань lookups (за GUID, кодом або реквізитом), заповнення шапки header і рядків lines з полів заявки (payload, line, lookup, const, param).