1. Створіть вхідну точку
Відкрийте «Підключення → REST API» та виберіть «Приймання даних у Data Bridge». Задайте назву, версію API v1 та ідентифікатор, наприклад orders. Ідентифікатор містить 3–64 малі латинські літери, цифри або дефіси й має бути унікальним серед точок цієї версії у вашому розділі.
Оберіть відповідь «Одразу після приймання» або «Після обробки потоком». У другому випадку задайте час очікування: довший запуск усе одно поверне 202. Для захисту від повторної передачі замовлень зробіть Idempotency-Key обов’язковим. На вкладці «Ліміти API» перевизначайте лише потрібні обмеження; без позначки діють поточні загальні значення.
2. Опишіть дані в блоці
Додайте «Вхідні дані API» з цією точкою. Для таблиці виберіть режим «Приймання даних» та формат JSON, JSON Lines, CSV/TSV, XML або визначення за Content-Type. JSON підтримує масив об’єктів і шлях на кшталт data.items; вкладені об’єкти стають полями a.b.
У тестових даних задайте невеликий приклад і його власний формат. Натисніть «Оновити поля», перевірте запропоновані типи та позначте обов’язкові значення. Для замовлення можна вимагати orderId, числове amount і дату orderDate. Додайте унікальний ключ orderId або потрібну комбінацію полів. Формат перевіряється, але не перетворює значення: нормалізацію робіть окремими блоками.
Повний перелік властивостей, поведінка без доставки та правила моків описані в довіднику блоку «Вхідні дані API».
3. Якщо надсилаються файли
У режимі «Приймання файлів» налаштуйте дозволені розширення, кількість файлів і правила читання. Підтримуються Excel XLSX/XLSM, CSV, TXT із роздільниками, JSON та XML. Для Excel виберіть аркуш і діапазон; для CSV — роздільник і заголовок; для JSON-файла — JSON Pointer. Рядки всіх файлів одного запиту об’єднуються в таблицю; за потреби додайте колонку імені файла.
Передавайте файли як multipart/form-data або один файл тілом запиту з іменем у X-File-Name чи Content-Disposition. Для HMAC підписуйте фактичні байти переданого тіла. Тестові дані призначені для перегляду й симуляції та не підставляються в робочий запит.
4. Опублікуйте й надішліть запит
З’єднайте джерело з перевірками й отримувачем, виконайте симуляцію та опублікуйте Production. Видайте API-клієнту право «Запис» цього потоку; його власник повинен мати право запуску. Копіюйте повний URL із форми. Нижче — структура запиту: API_KEY, час і підпис замінюються значеннями вашого клієнта за правилом HMAC.
POST /api/v1/inbound/orders?p.Period=2026-10 HTTP/1.1
Host: databridge.example.com
Authorization: Bearer API_KEY
Content-Type: application/json
Idempotency-Key: orders-2026-10-28-batch-001
X-UBC-Timestamp: UNIX_SECONDS
X-UBC-Signature: v1=HMAC_HEX
[{"orderId":"ORD-1042","amount":1250,"orderDate":"2026-10-28"}]p.Period використовуйте лише якщо потік має такий параметр. Якщо точку читають кілька доступних потоків, задайте flow=ідентифікатор. Невідомі параметри відхиляються.
5. Відстежуйте доставку й повтори
Збережіть номер доставки й Location. Опитуйте GET /api/v1/deliveries/{id} з тим самим клієнтом; для деталей запуску використовуйте отримане посилання або GET /api/v1/runs/{run_id}. Код 202 означає приймання, а не завершений запис. HTTP 200 та стан доставки completed також не гарантують бізнес-успіху: запуск міг завершитися зі станом failed, partial, uncertain або cancelled. Перевірте run.status, run.code, run.message і run.written, потім звірте цільові дані. Стан доставки failed означає помилку до створення запуску; причина міститься в error, а первинний POST повертає HTTP 409. Окремий GET доставки та ідемпотентний повтор можуть повернути HTTP 200 за різних поточних станів, тому завжди читайте тіло відповіді.
Повтор однакового тіла з тим самим ключем ідемпотентності повертає першу доставку й заголовок Idempotent-Replayed: true. Інші дані чи інший потік із цим ключем дають 409 IDEMPOTENCY_CONFLICT. Якщо підпис увімкнений для клієнта, для повторного HTTP-запиту обчислюйте новий HMAC: той самий підпис не можна використати вдруге. Ідемпотентність доставки не є загальною транзакцією всіх зовнішніх записів.
6. Зворотний виклик і діагностика
За потреби задайте адресу callback і окремий секрет щонайменше 32 символи. Data Bridge надсилає POST із JSON доставки, X-UBC-Delivery, подією delivery.completed або delivery.failed, часом і HMAC. Перевіряйте час та підпис за постійний час; повторні події обробляйте за номером доставки. Подія delivery.completed означає завершення запуску, а його результат визначайте за run.status, кодом, повідомленням і кількістю записаного. Відсутність відповіді або не-2xx запускає налаштовані повтори з подвоєнням паузи; перенаправлення не виконуються.
Перевірте навмисно неправильний тип і повтор унікального ключа: 422 API_INBOUND_INVALID містить причини в errors. Відсутня колонка може дати API_INBOUND_FIELDS; завелике тіло — 413; черга — 429 API_INBOUND_QUEUE_FULL. Дані доставки видаляються після завершення, але стан та окремий аудит мають власний життєвий цикл. Дивіться довідник точки й журнал запиту.