ERP နှင့် စနစ်များ ပေါင်းစပ်ချိတ်ဆက်ရေး လမ်းညွှန်

ဤလမ်းညွှန်သည် FreeMaint နှင့် အခြားစနစ်တစ်ခု — ERP၊ SCADA historian၊ ဂိုဒေါင်စနစ် သို့မဟုတ် စာရင်းကိုင်ဆော့ဖ်ဝဲ — အကြား ပေါင်းစပ်မှုနယ်ပယ်ကို သတ်မှတ်နေသည့် developer အတွက် ဖြစ်သည်။ ဤကဏ္ဍရှိ အခြားဆောင်းပါးများက မည်သို့ ခေါ်ယူရမည်ကို ရှင်းပြသည်။ ဤဆောင်းပါးကမူ နယ်နိမိတ်များအကြောင်းကို တမင်တကာ ပြောသည်။ ကုန်ကျစရိတ်အများဆုံး အမှားသည် header မှားခြင်း မဟုတ်ဘဲ၊ ရှိမည်ဟု ယူဆထားသော စွမ်းဆောင်ရည်တစ်ခု အမှန်တကယ် မရှိကြောင်းကို တည်ဆောက်မှု တစ်ဝက်ရောက်မှ တွေ့ရှိခြင်း ဖြစ်သည်။ အောက်ပါ ကန့်သတ်ချက်တိုင်းကို ရည်ရွယ်ချက်ရှိရှိ ဖော်ပြထားသည်။

key တစ်ခု၊ တံခါးသုံးပေါက်

API ကီး (fmk_ ဖြင့် စတင်သည်) ကို စီမံခန့်ခွဲသူတစ်ဦးက ကုမ္ပဏီဆက်တင်များ > API (/company-settings/api) တွင်၊ သို့မဟုတ် လူတစ်ဦးက မိမိအတွက် ကိုယ်ရေးအချက်အလက် > လုံခြုံရေး > API ကီးများ တွင် ဖန်တီးပြီး Authorization: Bearer fmk_... အဖြစ် ပေးပို့သည်။ ၎င်းသည် အရာသုံးခုကိုသာ အတိအကျ အထောက်အထားစိစစ်ပေးသည်- POST /api/v1/graphql ရှိ GraphQL အဆုံးမှတ်၊ စွမ်းအင်ဒေတာသွင်းသည့် အဆုံးမှတ်၊ နှင့် /public-api/whoami နှင့် /public-api/ping တို့ဖြစ်သည်။ ၎င်းသည် /api/v1/{resource} အောက်ရှိ REST လမ်းကြောင်းများကို အထောက်အထားစိစစ်ပေးခြင်း မရှိပါ — ထိုလမ်းကြောင်းများသည် အက်ပလီကေးရှင်း၏ ကိုယ်ပိုင်အတွင်းပိုင်း API ဖြစ်ပြီး အသုံးပြုသူ ဆက်ရှင် (JWT) လိုအပ်သည်။ သင့်ပေါင်းစပ်မှုကို GraphQL ပေါ်တွင် တည်ဆောက်ပါ- ကီးတစ်ခု လှမ်းမီနိုင်သည့် မျက်နှာပြင်မှာ ထိုအရာဖြစ်သည်။

API key က သင့်အား ပေးသည့်အရာများ

key အကြမ်းကို ဖန်တီးချိန်တွင် တစ်ကြိမ်တည်းသာ ပြသပြီး နောက်ပိုင်းတွင် ဘယ်တော့မှ ပြန်လည်ရယူ၍ မရတော့ပါ- SHA-256 hash တစ်ခုသာ သိမ်းဆည်းထားပြီး၊ စာရင်းထဲတွင် key ကို မျက်နှာပြင်ပေါ်မှ ခွဲခြားသိနိုင်ရန် fmk_ နောက်ရှိ စာလုံး ၆ လုံးကိုပါ သိမ်းထားသည်။

API key က သင့်အား မပေးသည့်အရာများ

ဤအချက်များသည် လက်ရှိအကောင်အထည်ဖော်မှု၏ အမှန်တကယ် ကန့်သတ်ချက်များဖြစ်ပြီး ဤစာမျက်နှာမှ ကျန်ခဲ့သည့် အချက်များ မဟုတ်ပါ။ သင့်လုံခြုံရေးသုံးသပ်ချက်သည် ၎င်းတို့ထဲမှ တစ်ခုခုအပေါ် မူတည်နေပါက တည်ဆောက်ပြီးမှ မဟုတ်ဘဲ ယခုပင် ၎င်းတို့ကို ရှောင်လွှဲနိုင်အောင် ဒီဇိုင်းဆွဲပါ။

• ကီးတစ်ခုချင်းစီအလိုက် မော်ဂျူးစာရင်း မရှိပါ။ ကီးသည် ၎င်း၏ပိုင်ရှင်၏ အခန်းကဏ္ဍက ခွင့်ပြုသမျှကို ဖတ်ပြီး ရေးသည် — ကျဉ်းမြောင်းစေလိုပါက အခန်းကဏ္ဍ ပိုကျဉ်းသော ပိုင်ရှင်ထံ ပေးပါ။ ထို့အပြင် ဝင်ရောက်ခွင့်အဆင့် သုံးခုသာ သက်ရောက်သည် — ကီးကိုယ်တိုင်တွင် ၎င်းအသုံးပြုနိုင်သည့် မော်ဂျူးများကို စာရင်းပြု၍ မရပါ။
• IP ခွင့်ပြုစာရင်း မရှိပါ။ key တစ်ခုသည် အင်တာနက်ပေါ်ရှိ မည်သည့်နေရာမှမဆို အသုံးဝင်သည်။ ၎င်းကို လျှို့ဝှက်ချက်တစ်ခုအဖြစ် သဘောထားပါ- vault သို့မဟုတ် သင့်ပလက်ဖောင်း၏ secret store တွင်သာ ထားပါ၊ code repository၊ မျှဝေထားသော drive သို့မဟုတ် ပံ့ပိုးမှုလက်မှတ်တွင် ဘယ်တော့မှ မထားပါနှင့်။
• key တစ်ခုချင်းစီအလိုက် အသုံးပြုမှုမှတ်တမ်း မရှိပါ။ lastUsedAt တစ်ခုသာ သိမ်းထားသည်။ key အလိုက် ခေါ်ဆိုမှုမှတ်တမ်းလည်း မရှိ၊ key အလိုက် ခွဲတမ်းလည်း မရှိ၊ မည်သည့် key က မည်သည့်လုပ်ဆောင်ချက်ကို ပြုလုပ်ခဲ့သည်ဆိုသည့် မှတ်တမ်းလည်း မရှိပါ။ နေ့စဉ်ခွဲတမ်း ရေတွက်မှုသည် ကုမ္ပဏီအလိုက်ဖြစ်ပြီး key အားလုံးက မျှဝေသုံးစွဲသည် — ထို့ကြောင့် ထိန်းမနိုင်သိမ်းမရဖြစ်နေသော ပေါင်းစပ်မှုတစ်ခုက ကျန်အားလုံး၏ ခွဲတမ်းကို ကုန်ခန်းစေနိုင်သည်။
• အခြားသူကိုယ်စား အတည်ပြုခြင်း မရှိပါ။ ပိုင်ရှင်ကိုယ်တိုင် အတည်ပြုနိုင်သော်လည်း ကီးသည် လုပ်ငန်းစဉ်အဆင့်ကို ဘယ်တော့မှ အတည်မပြုပါ — အတည်ပြုခြင်းသည် အက်ပ်အတွင်း လူကိုယ်တိုင် လုပ်ဆောင်ရသည့် အရာအဖြစ် ဆက်ရှိနေသည်။
• ကီးတစ်ခုလျှင် ကုမ္ပဏီတစ်ခု။ ကီးသည် ၎င်းကို ဖန်တီးခဲ့သော ကုမ္ပဏီနှင့် ချည်နှောင်ထားပြီး အခြားကုမ္ပဏီ၏ ဒေတာကို မရောက်နိုင်ပါ- အခြားကုမ္ပဏီ၏ မှတ်တမ်းကို မတွေ့ပါ ဟုသာ ပြသည်။

သင် ဖတ်ရှုနိုင်သည့်အရာများ

GraphQL သည် ဖတ်ရှုမှု query 16 ခုကို ဖွင့်ပေးထားသည် — whoami, workOrders, workOrder(id), assets, asset(id), assetDowntimes, meters(assetId), parts, part (id သို့မဟုတ် ဘားကုဒ်ဖြင့်), stockMovements, locations, vendors, customers, purchaseOrders, purchaseOrder(id | reference | erpReference) နှင့် floorPlans(locationId) တို့ဖြစ်သည်။ စာရင်းတိုင်းကို အဆုံးထိ စာမျက်နှာခွဲ၍ ဖတ်နိုင်သည်- workOrders, assets, assetDowntimes, meters, parts, purchaseOrders, locations, vendors နှင့် customers အားလုံးသည် limit (1 မှ 200) နှင့် offset ကို လက်ခံပြီး၊ workOrders, assets, parts, purchaseOrders, locations, vendors နှင့် customers တို့သည် တိုးမြှင့်ချိန်ကိုက်မှုအတွက် updatedSince ကိုလည်း လက်ခံသည်။ မူလစာမျက်နှာအရွယ်အစားမှာ အတန်း 50 ဖြစ်ပြီး၊ locations, vendors နှင့် customers တို့သာ ၎င်းတို့၏ ယခင်မူလတန်ဖိုး 200 ကို ဆက်ထားသည်။ စာရင်းတိုင်းတွင် တူညီသောတန်ဖိုးရှိသည့် အတန်းများကို id ဖြင့် ထပ်မံစီထားသဖြင့် စာမျက်နှာနယ်နိမိတ်တွင် အတန်းတစ်ခုကို ဘယ်တော့မှ ကျော်မသွား၊ ထပ်မပြပါ။ stockMovements သည် သင် စာရင်းညှိရာတွင် အခြေခံရမည့် စတော့ရွှေ့ပြောင်းမှု စာရင်းဇယားဖြစ်သည်- ၎င်းကို အဟောင်းဆုံးမှ စ၍ ဖတ်ပြီး afterId ဖြင့် စာမျက်နှာခွဲသည် — သင်နောက်ဆုံး လက်ခံရရှိခဲ့သော ရွှေ့ပြောင်းမှု၏ id ကို ပေးပါ — ထိုနည်းသည် ရွှေ့ပြောင်းမှုအသစ်များ ရေးသွင်းနေစဉ်တွင်ပင် တိကျမှန်ကန်နေဆဲဖြစ်ပြီး၊ since ဖြင့် ရက်စွဲတစ်ခုမှ စ၍ ယခင်ဒေတာများကို ပြန်ဖြည့်ယူခြင်းကို စတင်နိုင်သည်။ အမှိုက်ပုံးထဲရှိ လုပ်ငန်းအမိန့်များကို ဘယ်တော့မှ ပြန်မပေးပါ။ purchaseOrders ကို status နှင့် vendorId ဖြင့်လည်း စစ်ထုတ်နိုင်သည်။ ငွေပမာဏများသည် ကုမ္ပဏီ၏ ငွေကြေးဖြင့်ဖြစ်ပြီး အမိန့်တိုင်းက currency အကွက်တွင် ပါရှိသည်။

ခေါ်ဆိုမှုတစ်ကြိမ်တည်းဖြင့် key ကို အတည်ပြုပြီး လုပ်ငန်းအမိန့်များကို ဖတ်ရန်- curl -X POST https://freemaint.com/api/v1/graphql -H "Authorization: Bearer $FMK" -H "Content-Type: application/json" -d '{"query":"{ whoami { companyId tier } workOrders(limit: 5, status: \"OPEN\") { id reference title status priority dueDate } }"}'

သင် ရေးသားနိုင်သည့်အရာများ

mutation ဆယ့်နှစ်ခု- လုပ်ငန်းအမိန့်၊ ပိုင်ဆိုင်မှုနှင့် အပိုပစ္စည်းများပေါ်တွင် ဖန်တီးခြင်း၊ ပြင်ဆင်ခြင်းနှင့် ဖျက်ခြင်း၊ ထို့အပြင် အမှတ်အသားပါ ကုန်လက်ကျန်လှုပ်ရှားမှုအတွက် adjustStock တို့ဖြစ်သည်။ ၎င်းတို့သည် အက်ပလီကေးရှင်းကိုယ်တိုင် သုံးသည့် service များအတိုင်းပင် ဖြတ်သန်းသဖြင့် reference များ (WO-…၊ ASS-…၊ PART-…)၊ စစ်ဆေးမှုမှတ်တမ်းအတန်းများနှင့် အသိပေးချက်များသည် interface ထဲကအတိုင်း အတိအကျ လုပ်ဆောင်သည်။ ကုန်လက်ကျန်အတွက် adjustStock ကို ဦးစားပေးပါ- ၎င်းသည် တူညီသော transaction အတွင်း StockMovement စစ်ဆေးမှုအတန်းတစ်ခု ရေးသွင်းပြီး quantity ကို သုညအောက် ကျဆင်းစေရန် ငြင်းပယ်သည်။ updatePart(quantity) မူ ပကတိတန်ဖိုးတစ်ခုကို သတ်မှတ်ပြီး ကွာခြားချက်ကို ချိန်ညှိမှုတစ်ခုအဖြစ် မှတ်တမ်းတင်သည်။ တည်နေရာအလိုက် လက်ကျန်ကို ခြေရာခံထားသော အပိုပစ္စည်းတွင် adjustStock သို့ locationId ကို ပေးပါ။ ထိုနေရာတွင် updatePart(quantity) ကို ငြင်းပယ်သည်။ ဆယ့်တစ်ခုမြောက် addMeterReading သည် မီတာမျက်နှာပြင်နှင့် တူညီသော service မှတစ်ဆင့် မီတာဖတ်ချက်ကို မှတ်တမ်းတင်သဖြင့် မီတာ trigger များနှင့် မီတာအခြေပြု ကြိုတင်ကာကွယ်ထိန်းသိမ်းမှုသည် အက်ပ်တွင် ရိုက်ထည့်သော ဖတ်ချက်အတိုင်း အတိအကျ တုံ့ပြန်သည်။ ဆယ့်နှစ်ခုမြောက် setPurchaseOrderErpReference သည် သင့် ERP ၏ စာရွက်စာတမ်းနံပါတ်ကို ဝယ်ယူမှုအမိန့်တွင် သိမ်းဆည်းပေးသဖြင့် နောက်ပိုင်းတွင် purchaseOrder(erpReference: …) ဖြင့် မှတ်တမ်းနှစ်ခုကို တိုက်ဆိုင်နိုင်သည်။ FULL access key လိုအပ်ပြီး ရည်ရွယ်ချက်ရှိရှိ webhook မဖြစ်ပေါ်စေပါ- သင့် ERP သည် မိမိရေးသွင်းမှုကို event အဖြစ် ဘယ်တော့မှ မရပါ။

API က လုံးဝ မလွှမ်းခြုံသည့်အရာများ

GraphQL schema တွင် လုပ်ငန်းအမိန့်များ၊ ပိုင်ဆိုင်မှုများ၊ စက်ရပ်နားမှုများ၊ အပိုပစ္စည်းများနှင့် ၎င်းတို့၏ စတော့ရွှေ့ပြောင်းမှုများ၊ မီတာများ၊ ဝယ်ယူမှုအမိန့်များ၊ တည်နေရာများ၊ ပေးသွင်းသူများ၊ ဖောက်သည်များနှင့် အဆောက်အအုံပုံစံများ ပါဝင်သည်။ အခြားမည်သည့်အရာမျှ မပါပါ။ အောက်ပါတို့သည် FreeMaint တွင် အပြည့်အဝ အလုပ်လုပ်နေသော်လည်း ယနေ့ API မျက်နှာပြင် လုံးဝမရှိသေးသည့် အစိတ်အပိုင်းများဖြစ်သည် — ပေါင်းစပ်မှုတစ်ခုမှ ဖတ်၍မရ၊ ရေး၍မရ၊ စာရင်းသွင်း၍မရဘဲ၊ လက်ရှိ query များ မည်သို့ပေါင်းစပ်သည်ဖြစ်စေ မရောက်ရှိနိုင်ပါ။

• စစ်ဆေးမှုများ — ပုံစံခွက်များ၊ အချိန်ဇယားဆွဲထားသော လုပ်ဆောင်မှုများ၊ မှတ်တမ်းတင်ထားသော ရလဒ်များ သို့မဟုတ် action code များ မည်သည့်အရာမျှ မပါဝင်ပါ။ inspection query မရှိ၊ inspection mutation မရှိ၊ inspection webhook ဖြစ်ရပ်လည်း မရှိပါ။
• အသုံးပြုသူများ၊ အခန်းကဏ္ဍများနှင့် အဖွဲ့များ — ဤ API မှတစ်ဆင့် အသုံးပြုသူကို စာရင်းပြု၊ ဖန်တီး သို့မဟုတ် ပိတ်၍ မရပါ။ အသုံးပြုသူ စီမံပေးခြင်းကို အက်ပ်ထဲတွင် ပြုလုပ်သည်၊ Enterprise အစီအစဉ်တွင် ၎င်းကို SCIM ဖြင့် အလိုအလျောက် လုပ်ဆောင်နိုင်ပြီး ၎င်းသည် သီးခြား ယန္တရား ဖြစ်ကာ ဤ API ၏ အစိတ်အပိုင်း မဟုတ်ပါ။
• စီမံကိန်းများ — query လည်းမရှိ၊ mutation လည်း မရှိပါ။
• ဝယ်ယူမှုတောင်းဆိုချက်များ — query လည်းမရှိ၊ mutation လည်း မရှိပါ။ ဝယ်ယူမှုအမိန့်များကို ဖတ်ရှုနိုင်သည် (purchaseOrders၊ purchaseOrder)၊ သင့် ERP က ၎င်း၏ reference ကို ပြန်ရေးနိုင်သည် (setPurchaseOrderErpReference)၊ purchase_order.* webhook များကလည်း အသိပေးသည်။ သို့သော် API မှတစ်ဆင့် အမိန့်ကို ဖန်တီး၊ ပြင်ဆင် သို့မဟုတ် လက်ခံခြင်း မပြုနိုင်ပါ- ၎င်းတို့ကို အက်ပ်တွင်သာ ပြုလုပ်ရသည်။
• ဖိုင်များ၊ ဓာတ်ပုံများနှင့် ပူးတွဲပါဖိုင်များ — စာရွက်စာတမ်း သို့မဟုတ် ဓာတ်ပုံ တင်၍ မရသလို ပြန်ဖတ်၍လည်း မရပါ။ လုပ်ငန်းအမိန့်ဓာတ်ပုံများ၊ အပိုပစ္စည်းပုံများနှင့် စစ်ဆေးမှုအထောက်အထားများ အားလုံး API ပြင်ပတွင် ရှိသည်။ တုံ့ပြန်ချက်တစ်ခုတွင် ပေါ်လာသော URL — ဥပမာ အပိုပစ္စည်းတစ်ခု၏ imageUrl — သည် ဖိုင်တင်ရန် လမ်းကြောင်း မဟုတ်ပါ။
• ကြိုတင်ကာကွယ်ထိန်းသိမ်းမှု အချိန်ဇယားများ၊ အချိန်မှတ်တမ်းများ၊ လုပ်ငန်းစဉ်များနှင့် စစ်ဆေးစာရင်းများ — ဖော်ပြထားခြင်း မရှိပါ။

Webhook — ဖြစ်ရပ် ကတ်တလောက်

Webhook သည် ပေါင်းစပ်မှု၏ တွန်းပို့သည့် ဘက်ခြမ်းဖြစ်သည်- ထပ်ခါထပ်ခါ မေးမြန်းရမည့်အစား တစ်စုံတစ်ရာ ဖြစ်ပေါ်သည်နှင့် FreeMaint မှ သင့် URL သို့ POST ပို့ပေးသည်။ ကုမ္ပဏီဆက်တင်များ > Webhook (/company-settings/webhooks) တွင် ပြင်ဆင်ပြီး webhook တစ်ခုစီကို သင်လိုအပ်သည့် ဖြစ်ရပ်များတွင် စာရင်းသွင်းပါ။ ကတ်တလောက်မှာ သတ်မှတ်ပြီးသား စာရင်းတစ်ခုဖြစ်သည်။

• work_order.created — လုပ်ငန်းအမိန့်တစ်ခု ဖန်တီးပြီးပြီ
• work_order.completed — လုပ်ငန်းအမိန့်တစ်ခု «ပြီးဆုံး» အဆင့်သို့ ရောက်ပြီ
• work_order.status_changed — လုပ်ငန်းအမိန့်တစ်ခု အခြေအနေတစ်ခုခုသို့ ပြောင်းသွားပြီ။ payload တွင် new_status ပါဝင်သည်။ မပြောင်းလဲသော work_order.completed နှင့်အတူ တွဲ၍ ထွက်သည်
• request.created — ပြုပြင်ထိန်းသိမ်းရေး တောင်းဆိုချက်တစ်ခု တင်သွင်းပြီးပြီ
• request.status_changed — တောင်းဆိုချက်တစ်ခုကို အတည်ပြု၊ ငြင်းပယ် သို့မဟုတ် ပယ်ဖျက်ပြီးပြီ
• part.low_stock — အပိုပစ္စည်းတစ်ခု ၎င်း၏ အနည်းဆုံးပမာဏသို့ သို့မဟုတ် ၎င်းအောက်သို့ ကျဆင်းသွားပြီ
• part.out_of_stock — အပိုပစ္စည်းတစ်ခု သုည ရောက်သွားပြီ။ ၎င်းသည် သီးခြားဖြစ်ရပ်တစ်ခုဖြစ်ပြီး low_stock ၏ အမျိုးအစားခွဲ မဟုတ်ပါ
• part.low_stock_summary — ကုမ္ပဏီတစ်ခုလျှင် တစ်ရက်တစ်ကြိမ် အကျဉ်းချုပ်။ ပြန်လည်မှာယူမည့်အဆင့် သို့မဟုတ် အောက်တွင်ရှိသော အပိုပစ္စည်းများကို — တစ်ခါမျှ မလှုပ်ရှားခဲ့သည်များပါ — စာရင်းပြုစုသည်
• part.out_of_stock_summary — သုညတွင်ရှိနေသော အပိုပစ္စည်းများအတွက် ထိုနေ့စဉ်အကျဉ်းချုပ်အတိုင်းပင်
• part.consumed — အပိုပစ္စည်းတစ်ခုကို လုပ်ငန်းအမိန့်တစ်ခုတွင် သုံးစွဲခဲ့သည် သို့မဟုတ် ထိုမှ ပြန်လည်အပ်နှံခဲ့သည်။ quantity တွင် အမှတ်အသားပါသည်
• compliance.chain_divergence — စစ်ဆေးမှု hash-chain ပြတ်တောက်သွားပြီ (Enterprise)
• asset.downtime_started — စက်ရပ်နားမှုတစ်ခု စတင်မှတ်တမ်းတင်ပြီ
• asset.downtime_ended — စက်ရပ်နားမှုတစ်ခု ပိတ်သိမ်းပြီ။ ကြာချိန်ကို ယခု တွက်ချက်နိုင်ပြီ
• report.daily_summary — ထိုနေ့၏ ပြီးစီးခဲ့သော လုပ်ငန်းများကို သင်ရွေးချယ်ထားသည့် အချိန်တွင် တစ်ရက်တစ်ကြိမ်
• purchase_order.created — ဝယ်ယူမှုအမိန့်တစ်ခု ဖန်တီးလိုက်သည်။ payload တွင် အမိန့် (reference၊ status၊ total_cost၊ currency၊ expected_date၊ erp_reference) နှင့် ၎င်း၏ ပေးသွင်းသူ ပါဝင်သည်
• purchase_order.status_changed — ဝယ်ယူမှုအမိန့်တစ်ခု၏ status ပြောင်းသွားသည် (အတည်ပြု၊ မှာယူပြီး၊ ပယ်ဖျက်…)။ payload တွင် previous_status နှင့် new_status ပါဝင်သည်
• purchase_order.received — ဝယ်ယူမှုအမိန့်တစ်ခုအတွက် ပို့ဆောင်မှုတစ်ခုကို လက်ခံရရှိပြီး (တစ်စိတ်တစ်ပိုင်းအပါအဝင် ပို့ဆောင်မှုတိုင်းတွင် ပို့သည်)။ payload တွင် စာကြောင်းတိုင်းကို quantity_ordered၊ quantity_received (ဤပို့ဆောင်မှု)၊ quantity_received_total နှင့် quantity_remaining ဖြင့် စာရင်းပြုစုထားပြီး receipt_id၊ fully_received နှင့် closed_short လည်း ပါဝင်သည်။ ကုန်ပစ္စည်း မျှော်လင့်နေဆဲ ကာလတွင် new_status သည် PARTIALLY_RECEIVED ဖြစ်ပြီး ပြည့်စုံသည် သို့မဟုတ် ပိတ်လိုက်သည့်အခါ RECEIVED ဖြစ်သည်

ပေးပို့မှု စာအိတ်

GENERIC ပေးပို့မှုတိုင်းသည် POST တစ်ခုဖြစ်ပြီး ၎င်း၏ body သည် တူညီသော key သုံးခုပါ စာအိတ်ပုံစံဖြစ်သည်- event၊ timestamp နှင့် data တို့ဖြစ်ကာ data ကို entity အလိုက် စီစဉ်ထားသည်။ ၎င်းနှင့်အတူ header သုံးခု ပါလာသည်။ X-FreeMaint-Signature ၏ ပုံစံမှာ t=<unix စက္ကန့်>,v1=<hex> ဖြစ်ပြီး၊ v1 သည် ထို webhook ၏ လျှို့ဝှက်ကီးဖြင့် လက်မှတ်ထိုးထားသော "<t>.<body အကြမ်း>" စာသားအတိအကျ၏ HMAC-SHA256 ဖြစ်သည်။ X-FreeMaint-Event သည် ဖြစ်ရပ်အမည်ကို ထပ်ဖော်ပြပြီး၊ X-FreeMaint-Delivery-Id သည် ပေးပို့မှုကို ခွဲခြားသတ်မှတ်ပေးသည်။ လက်မှတ်ကို parse မလုပ်မီ body အကြမ်းနှင့် တိုက်ဆိုင်စစ်ဆေးပါ — JSON ကို ပြန်လည် serialize လုပ်လျှင် byte များ ပြောင်းသွားပြီး လက်မှတ် ကိုက်ညီတော့မည် မဟုတ်ပါ။

{ "event": "work_order.created", "timestamp": "2026-09-05T08:14:02.371Z", "data": { "work_order": { "id": 5521, "title": "ပန့် အမှတ် ၃ ယိုစိမ့်မှု", "status": "OPEN", "priority": "HIGH", "dueDate": "2026-09-08T00:00:00.000Z" } } }

ယုံကြည်စိတ်ချရမှုနှင့် စောင့်ကြည့်ခြင်း

ပေးပို့မှုတစ်ခုကို ၂ စက္ကန့်အခြေခံ exponential backoff ဖြင့် ၃ ကြိမ် ကြိုးစားသည် — ခန့်မှန်းခြေ ၂ စက္ကန့်၊ ထို့နောက် ၄ စက္ကန့်၊ ထို့နောက် ၈ စက္ကန့် — ပြီးလျှင် ကြိုးစားမှုတစ်ခုစီသည် ၁၀ စက္ကန့်အကြာတွင် အချိန်ကုန်သွားသည်။ 2xx တုံ့ပြန်ချက်က ၎င်းကို ပေးပို့ပြီးအဖြစ် မှတ်သားသည်။ 5xx တုံ့ပြန်ချက်များနှင့် ကွန်ရက်အမှားများကို ပြန်လည်ကြိုးစားသည်။ 4xx ကိုမူ အပြီးအပိုင် ငြင်းပယ်မှုအဖြစ် သတ်မှတ်ပြီး လုံးဝ ပြန်မကြိုးစားပါ- သင့်ဘက်မှ ချွတ်ယွင်းချက်ကြောင့် သင့် endpoint က 400 သို့မဟုတ် 401 ပြန်ဖြေပါက ထိုပေးပို့မှုသည် ထိုနေရာတွင်ပင် ရပ်တန့်သွားပြီး လက်ဖြင့် ပြန်လည်ပေးပို့မှသာ ပြန်လည်ရရှိနိုင်မည် ဖြစ်သည်။

• ပေးပို့မှုတိုင်းကို သိမ်းဆည်းထားသည်- ဖြစ်ရပ်၊ ပေးပို့လိုက်သည့် payload အတိအကျ၊ အခြေအနေ၊ သင်ပြန်ပေးလိုက်သည့် HTTP code၊ သင့်တုံ့ပြန်ချက် body ၏ ပထမဆုံး စာလုံး ~၅၀၀၊ ကြိုးစားမှုအရေအတွက်နှင့် အမှားစာသား တို့ဖြစ်သည်။
• အခြေအနေများမှာ PENDING၊ DELIVERED၊ FAILED၊ RATE_LIMITED (တစ်နေ့လျှင် ပေးပို့မှု ၁၀၀ ဟူသော Starter ကန့်သတ်ချက် ပြည့်သွားပြီ) နှင့် SKIPPED_TIER (အစီအစဉ်က ထိုဦးတည်ရာကို ခွင့်မပြုတော့ပါ) တို့ဖြစ်သည်။
• သိမ်းဆည်းထားသော ပေးပို့မှုတစ်ခုကို webhook ၏ မှတ်တမ်းမှ ပြန်လည်ပေးပို့နိုင်သည်။ သိမ်းထားသည့် payload ကို မပြောင်းလဲဘဲ ပြန်ပို့သဖြင့် ၎င်းအတွင်းရှိ လုပ်ငန်းဆိုင်ရာ key များ တူညီနေမည်ဖြစ်ပြီး၊ ထပ်နေမှုကို မှန်ကန်စွာ ဖယ်ရှားသည့် လက်ခံစနစ်တစ်ခုသည် နှစ်ကြိမ် မှတ်တမ်းတင်မည် မဟုတ်ပါ။
• webhook တစ်ခုစီတွင် lastTriggeredAt၊ lastSuccessAt၊ lastFailureAt နှင့် failureCount တစ်ခု ပါဝင်သည် — မှတ်တမ်းအပြည့်အစုံ မဖွင့်ဘဲ ကျန်းမာရေးစစ်ဆေးမှု ပြုလုပ်ရန် ဤအချက်များဖြင့် လုံလောက်သည်။
• webhook စာရင်းနှင့် ၎င်း၏ ပေးပို့မှုမှတ်တမ်းကို အစီအစဉ်တိုင်းတွင် ဖတ်ရှုနိုင်သည် — ထို့ကြောင့် အစီအစဉ်လျှော့ချမှုကြောင့် ရပ်တန့်သွားသော ပေါင်းစပ်မှုသည် တိတ်တဆိတ် သေဆုံးမသွားဘဲ မြင်သာနေမည် ဖြစ်သည်။
• ပေးပို့မှုများ ကျရှုံးစပြုသည့်အခါ သင့်အား သတိပေးမည့်အရာ ဘာမျှ မရှိပါ — အီးမေးလ်လည်း မရှိ၊ အသိပေးချက်လည်း မရှိပါ။ တိတ်တဆိတ် ရပ်တန့်မှုက ပြဿနာဖြစ်စေမည်ဆိုပါက သင့်ကိုယ်ပိုင် စောင့်ကြည့်စနစ်မှ ပေးပို့မှုမှတ်တမ်းကို ပုံမှန် စစ်ဆေးပါ။

လုံခြုံရေး

webhook ကို သိမ်းဆည်းချိန်တွင် URL များကို စိစစ်ပြီး၊ စည်းမျဉ်းများကို တမင်တကာ တင်းကျပ်ထားသည်- webhook သည် ကျွန်ုပ်တို့၏ ဆာဗာများမှ ထွက်သွားသည့် တောင်းဆိုမှုတစ်ခုဖြစ်ရာ ပြေလျော့သော စည်းမျဉ်းတစ်ခုသည် SSRF လမ်းကြောင်းတစ်ခု ဖြစ်သွားနိုင်သည်။

• key များကို SHA-256 hash အဖြစ် သိမ်းဆည်းထားသည် — ဖန်တီးပြီးနောက် တန်ဖိုးအကြမ်းကို FreeMaint မှ ပြန်လည်ရယူ၍ မရပါ။
• webhook URL များသည် https ကို သုံးရမည်။ သာမန် http နှင့် အခြား scheme အားလုံးကို ငြင်းပယ်သည်။
• port 443 နှင့် 8443 ကိုသာ လက်ခံသည်။
• loopback၊ link-local နှင့် သီးသန့်အကွာအဝေး host များ (127.x၊ 10.x၊ 192.168.x၊ 172.16–31.x၊ ::1 နှင့် အလားတူများ) ကို ငြင်းပယ်သည်- လက်ခံသူသည် အများသုံး အင်တာနက်မှ ဆက်သွယ်၍ ရရမည်။ သင့်စက်ရုံအတွင်း၌သာ တည်ရှိသော စနစ်တစ်ခုအတွက် အများသုံး relay တစ်ခု သို့မဟုတ် tunnel တစ်ခု လိုအပ်သည်။
• URL အတွင်းရှိ အထောက်အထားများ (https://user:pass@host) ကို ငြင်းပယ်သည်။
• redirect များကို လိုက်နာခြင်း မရှိပါ — သင်မှတ်ပုံတင်လိုက်သည့် endpoint သည်ပင် POST ကို လက်ခံရရှိသည့် endpoint ဖြစ်သည်။
• webhook တစ်ခုစီတွင် ကိုယ်ပိုင် လက်မှတ်ထိုးလျှို့ဝှက်ကီး ရှိပြီး လျှို့ဝှက်ကီး လှည့်ပြောင်းသည့် လုပ်ဆောင်ချက်တစ်ခုလည်း ရှိသည်။ လှည့်ပြောင်းမှုသည် ချက်ချင်း အကျိုးသက်ရောက်သဖြင့် လျှို့ဝှက်ကီးအသစ်ကို သင့်ဘက်တွင် တူညီသည့် အချိန်အတွင်း ထည့်သွင်းပါ။
• SLACK နှင့် TEAMS ဦးတည်ရာများသည် ထိုပလက်ဖောင်းအလိုက် ပုံစံချထားသော မက်ဆေ့ချ်ကို ရရှိပြီး FreeMaint ၏ HMAC header ကို လုံးဝ မရရှိပါ- ၎င်းတို့အတွက် URL ၏ လျှို့ဝှက်မှုသာလျှင် တစ်ခုတည်းသော အထောက်အထားစိစစ်မှု ဖြစ်သည်။ cryptographic နည်းဖြင့် အတည်ပြုရန် လိုအပ်သည့် မည်သည့်အရာအတွက်မဆို GENERIC ကို သုံးပါ။

ယနေ့ ကောင်းစွာ အလုပ်လုပ်သည့် ပုံစံများ

ဤအရာများသည် လက်ရှိမျက်နှာပြင်က သပ်သပ်ရပ်ရပ် ပံ့ပိုးပေးနိုင်သည့် ပေါင်းစပ်မှုများဖြစ်ပြီး၊ တစ်ခုချင်းစီကို လက်တွေ့လုပ်ငန်းခွင်တွင် စိတ်ချစွာ အသုံးပြုနိုင်စေမည့် အသေးစိတ်ချက်များပါ ပါဝင်သည်။

သင်လိုအပ်မည့် အစီအစဉ်

သီးခြားတံခါး နှစ်ခု- API အတွက် တစ်ခု၊ webhook အတွက် တစ်ခု။ Starter အစီအစဉ်ရှိ ကုမ္ပဏီသည် API မရှိဘဲ webhook များ လက်ခံနိုင်သည်။