ContractsContract များ

Every public capability is contract-first: the OpenAPI 3.0.3 specification is the authoritative machine contract, frozen and CI-enforced. The reference pages on this portal are generated from those specs and the code examples are vendored from CI-type-checked sources — neither can drift from the real surface, by construction.

အများသုံး စွမ်းဆောင်ရည်တိုင်းသည် contract-first ဖြစ်သည် — OpenAPI 3.0.3 specification သည် တရားဝင် machine contract ဖြစ်ပြီး frozen လုပ်ကာ CI ဖြင့် ထိန်းချုပ်ထားသည်။ ဤ portal ၏ အကိုးအကား စာမျက်နှာများကို ထို spec များမှ ထုတ်လုပ် ပြီး code နမူနာများကို CI-type-check လုပ်ထားသော မူရင်းများမှ ကူးယူ ထားသည် — နှစ်ခုလုံး အစစ်အမှန် surface မှ သွေဖည်၍ မရအောင် တည်ဆောက်ထားသည်။

What the contract guarantees

Contract က အာမခံသည့်အရာများ

Stable wire errors: error codes are UPPER_SNAKE identifiers and never change meaning. SDKs surface them as typed errors you catch — never string-match a message. See the error reference.
Additive evolution: within a version, changes are backward-compatible — new endpoints, new optional fields, new enum values. Write clients to ignore unknown fields. Breaking changes ship under a new version path. See versioning & changelog.
Idempotency: merchant-plane POSTs take an Idempotency-Key; a retry with the same key returns the original result. The consumer write (redeem) carries no idempotency promise yet — the consumer SDK therefore never blind-retries it.
Server-authoritative money: pricing, totals and balances are resolved server-side; client-supplied amounts are never trusted.
Golden fixtures: the canonical Orders example (request + resolved response) is a CI drift-gate fixture; the portal renders it verbatim with provenance.

တည်ငြိမ်သော wire error များ — error code များသည် UPPER_SNAKE identifier များဖြစ်ပြီး အဓိပ္ပါယ် ဘယ်တော့မှ မပြောင်းပါ။ SDK များက ၎င်းတို့ကို catch လုပ်နိုင်သော typed error အဖြစ် ပေးသည် — message ကို string ကိုက်ညှိခြင်း ဘယ်တော့မှ မလုပ်ပါနှင့်။ error အကိုးအကား ကို ကြည့်ပါ။
ထပ်ဆင့်တိုး ပြောင်းလဲမှု — version တစ်ခုအတွင်း ပြောင်းလဲမှုများသည် နောက်ပြန် တွဲဖက်နိုင်သည်။ client များကို မသိသော field များ လျစ်လျူရှုအောင် ရေးပါ။ breaking ပြောင်းလဲမှုများ version path အသစ်အောက်တွင် ထွက်သည်။ versioning နှင့် changelog ကို ကြည့်ပါ။
Idempotency — merchant-plane POST များတွင် Idempotency-Key သုံးသည်။ consumer write (redeem) တွင် idempotency အာမခံချက် မရှိသေး — ထို့ကြောင့် consumer SDK က ၎င်းကို မျက်စိမှိတ် retry ဘယ်တော့မှ မလုပ်ပါ။
Server-authoritative ငွေကြေး — စျေးနှုန်း၊ စုစုပေါင်းနှင့် လက်ကျန်များကို server ဘက်တွင် တွက်ချက်သည်။ client ပို့သော ပမာဏများကို ဘယ်တော့မှ မယုံပါ။
Golden fixture များ — Orders နမူနာ အစစ် (request + resolved response) သည် CI drift-gate fixture ဖြစ်ပြီး portal က provenance နှင့်အတူ အတိအကျ ပြသည်။

If the docs and the wire ever differ

Docs နှင့် wire ကွဲလွဲလျှင်

The OpenAPI specification governs the wire; curated pages govern intent. Because the pages are generated and the examples vendored, a difference is a bug — report it.

OpenAPI specification က wire ကို အုပ်ချုပ်သည်။ curated စာမျက်နှာများက ရည်ရွယ်ချက်ကို အုပ်ချုပ်သည်။ စာမျက်နှာများကို ထုတ်လုပ်ထားပြီး နမူနာများကို ကူးယူထားသောကြောင့် ကွဲလွဲမှုသည် bug ဖြစ်သည် — သတင်းပို့ပါ။