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. Сұрауда файлдар болғанда
«Файлдар қабылдау» режимінде рұқсат етілген кеңейтімдерді, файл санын және оқу ережелерін баптаңыз. XLSX/XLSM Excel, 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=identifier. Белгісіз параметрлер қабылданбайды.
5. Жеткізілім мен қайталауды бақылаңыз
Жеткізілім ID және мына мәнді сақтаңыз: 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. Кері хабарлау және диагностика
Қажет болса, кері хабарлау мекенжайын және кемінде 32 таңбалық бөлек құпияны баптаңыз. Data Bridge жеткізілім JSON деректерімен POST жібереді: X-UBC-Delivery, оқиға delivery.completed немесе delivery.failed, уақыт белгісі және HMAC. Уақыт белгісін тексеріп, қолтаңбаларды тұрақты уақытта салыстырыңыз; қайталанған оқиғаларды жеткізілім ID бойынша өңдеңіз. Мына delivery.completed оқиға орындаудың аяқталғанын білдіреді; нәтижесін мынадан анықтаңыз: run.status, код, хабар және жазылғандар саны. Жауап болмаса немесе жауап 2xx болмаса, кідірісі екі еселенетін бапталған қайталаулар орындалады; қайта бағыттауларға өту жасалмайды.
Жарамсыз түрді және қайталанатын бірегей кілтті әдейі сынаңыз: 422 API_INBOUND_INVALID себептерді мынада береді: errors. Жетіспейтін баған мына қатеге әкелуі мүмкін: API_INBOUND_FIELDS; тым үлкен дене — 413; толған кезек — 429 API_INBOUND_QUEUE_FULL. Жеткізілім деректері аяқталғаннан кейін жойылады, ал күй мен жеке аудит жазбаларының өз сақтау циклі бар. Мынаны қараңыз: түпкі нүкте анықтамасы және сұраулар журналы.