Otu esi ahazi ọkwa mmechi nke ndị API nyere

Kedu ihe omume a ga-ewere dị ka mmechi nke iwu

Nke mbụ, kpebie ọkwa nke API pụtara mmechi nke iwu n'ezie. N'ebe ndị na-eweta ọrụ dị iche iche, nke a nwere ike ịbụ iwu e mezuru, e nyefere, e kagburu, a jụrụ, e weghachiri ma ọ bụ nke e mezuru nke ọma. Ejikọla akpaaka naanị na okwu «ịga nke ọma»: iwu nwere ike ịgafe ọtụtụ ọnọdụ etiti, wee kwụsị n'ihi oke, nyocha ma ọ bụ nkagbu.

Ọ bụghị naanị nsonaazụ ọma ka a ga-ahazi. Ọ bụrụ na ọrụ ahụ eziga ọkwa banyere njehie, nkagbu, nlọghachi ma ọ bụ mmezu nke ọma, a ga-edekwa ya na sistemụ ime. Ma ọ bụghị ya, na panel, CRM ma ọ bụ bot, iwu ahụ ga-anọ na-eche, ọ bụ ezie na mmezu ọzọ agaghị eme.

Mepụta tebụl ndakọrịta ọkwa

Ebufela ọkwa API na interface na-enweghị nhazi. Aha na usoro nke onye na-eweta ọrụ nwere ike ịgbanwe, otu ọkwa ime nwekwara ike ijikọ ọtụtụ nke mpụga. Debe uru mbụ iche: ọ ga-abara gị uru maka nyocha njehie na ntụnyere na akwụkwọ.

• pending, created, queued — iwu ọhụrụ ma ọ bụ nke na-eche nhazi.
• processing, in_progress, running — a na-eme iwu ahụ.
• completed, delivered, success — iwu e mezuru.
• partial, partially_completed — iwu e mezuru nke ọma.
• cancelled, rejected, failed — iwu e kagburu ma ọ bụ nke kwụsịrị na njehie.
• refunded, returned — iwu chọrọ nlọghachi ma ọ bụ mmezi.
• Ọkwa a na-amaghị — anaghị agbanwe kaadị na-akpaghị aka, a na-enyefe ya maka nyocha.

Aha ndị dị n'elu bụ ọmụmaatụ nke atụmatụ. A ga-ewu tebụl ikpeazụ site na ọkwa nke API akọwapụtara. Ihe ọjọọ nke ịhazi aka bụ na mgbe emelitere API, a ga-edobe ya: ọkwa ọhụrụ nwere ike irute onye na-ahazi tupu e nwee iwu maka ya.

Họrọ webhook, ịjụ API ajụjụ, ma ọ bụ ha abụọ

Webhook bụ arịrịọ site n'aka ọrụ ahụ na URL gị mgbe ọkwa iwu gbanwere. Ịjụ API ajụjụ na-arụ ọrụ n'ụzọ ọzọ: sistemụ gị na-ajụ maka ozi iwu mgbe oge ụfọdụ gasịrị. Maka ọkwa mmechi, webhook na-adịkarị mma, n'ihi na mmelite na-abịa na-enweghị arịrịọ na-aga n'ihu na usoro nyocha ọkwa.

• Webhook dabara maka mmeghachi ngwa ngwa: imelite kaadị, ịmalite ọkwa ọzọ ma ọ bụ iziga ozi nye onye ọrụ.
• Ịjụ ajụjụ dabara ma ọ bụrụ na onye na-eweta ọrụ anaghị akwado ọkwa callback ma ọ bụ sava anaghị anabata arịrịọ mpụga.
• Atụmatụ jikọtara ọnụ na-eji webhook dị ka ọwa bụ isi, na ịjụ ajụjụ maka ịchọta ndị furu efu ma ọ bụ ndị kwụsịrị.

Ihe ọjọọ nke ịjụ ajụjụ bụ igbu oge na ibu ọzọ na API. Ihe ọjọọ nke webhook bụ na ọ dị mkpa ichekwa endpoint, tụlee ndị oyiri na ịghara ịdabere na usoro nnyefe nke omume.

Hazie endpoint maka ịnabata omume

Maka ọkwa, a chọrọ adreesị HTTPS ọha, nke ọrụ API nwere ike ịnweta. Na ntọala njikọ, a na-akọkarị URL nke onye na-ahazi, nzuzo nke akara na ndepụta omume: mgbanwe ọkwa, mmechi, nkagbu, njehie ma ọ bụ mmezu nke ọma.

Wepụta ụzọ dị iche naanị maka omume API. Nke a na-eme ka ọ dị mfe ịhazi ndekọ, igbochi ohere, ịtọ oke arịrịọ na ịghara ijikọ okporo ụzọ ọrụ na ụdị saịtị. Ejila adreesị gburugburu ule maka iwu ọrụ: mgbe emelitere gburugburu, onye na-eweta ọrụ ga-aga n'ihu na-eziga omume na URL echekwara.

Tupu ịmalite, lelee usoro arịrịọ na usoro ahụ dị na akwụkwọ. Ọtụtụ mgbe, ọ bụ POST na JSON, mana a na-ahụ form-data, query-paramita ma ọ bụ usoro nhazi nke ha. A ga-edekọ njehie nyocha na ndekọ, ma ọ bụghị ya, ọ ga-esi ike ịmata ọdịiche dị n'etiti payload na-ezighi ezi na ọdịda nke ngwa.

Debe njikọ n'etiti iwu na omume

Mgbe ị na-emepụta iwu site na API, debe njirimara nke onye na-eweta ọrụ weghachiri. N'akụkụ ya, debe nọmba iwu ime, ụdị ọrụ, ọkwa mbụ, oge mgbanwe ikpeazụ na nzaghachi API mbụ n'ụzọ nchekwa. Jikọọ webhook na-abata site na ID nke onye na-eweta ọrụ, ọ bụghị site na njikọ ọwa, aha ọrụ ma ọ bụ aha onye ahịa.

Ọ bụrụ na API na-ekwe ka ibufe njirimara mpụga mgbe ị na-emepụta, tinye nọmba iwu gị na mpaghara dị ka external_id ma ọ bụ client_reference. Nke a na-eme ka ọ dị mfe ịchọta na ndekọ na idozi esemokwu. Ma emela nọmba mpụga naanị igodo: ụfọdụ ndị na-eweta ọrụ anaghị eweghachi ya na ọkwa ọ bụla.

Emepụtala iwu ọhụrụ site na ID a na-amaghị site na webhook. A ga-edebe omume a na-amaghị na ndekọ ma nyochaa ya iche. Ịmepụta ndekọ na-akpaghị aka nwere ike ibute data ezighi ezi ma ọ bụ nhazi arịrịọ adịgboroja.

Jiri usoro payload doro anya

Aha mpaghara ndị ziri ezi dabere na API. Ihe dị n'okpuru abụghị nkwekọrịta nke ọrụ akọwapụtara, kama ọ bụ ọmụmaatụ omume JSON nke ị nwere ike iji duzie mgbe ị na-emepụta onye na-ahazi ime. Ihe dị mkpa bụ njirimara omume, ID iwu nke onye na-eweta ọrụ, ọkwa, oge mgbanwe na data maka nchọpụta nsogbu.

{

  "event_id": "evt_7f31",

  "event_type": "order.status_changed",

  "created_at": "2025-01-15T12:40:00Z",

  "data": {

    "order_id": "provider_order_4815",

    "external_id": "internal_order_9021",

    "status": "completed",

    "completed_quantity": 1000,

    "requested_quantity": 1000

  }

}

Ejila ọnụọgụ nke nkeji e mezuru dị ka ihe ịrịba ama nke mmechi na-enweghị ọkwa. Iwu nwere ike ịbụ nke e mezuru nke ọma, ọnụọgụ dị na payload nwekwara ike ịbụ nke e gbara gburugburu, nke emelitere na igbu oge ma ọ bụ nke a na-ebufeghị ma ọlị. Ihe ọjọọ nke ịchekwa ahụ omume zuru ezu bụ na data onwe onye ma ọ bụ mpaghara ọrụ nwere ike ịdị na ya, ya mere a ga-ekpuchi ndekọ ndị dị otú ahụ ma nwee oke oge nchekwa.

Lelee akara site na ahụ arịrịọ mbụ

URL onye na-ahazi mepere emepe nwere ike ịnata arịrịọ ọ bụghị naanị site n'aka ọrụ API. Ọ bụrụ na onye na-eweta ọrụ na-ebufe akara, nzuzo ma ọ bụ token, lelee ha tupu ịgbanwe iwu. Atụmatụ a na-ahụkarị bụ HMAC-SHA256: onye na-eweta ọrụ na-agbakọ akara site na bytes nke ahụ arịrịọ na nzuzo nkekọrịta, wee bufee nsonaazụ na HTTP header.

Ụkpụrụ ngbakọ ahụ dị otú a: a na-ewere ahụ arịrịọ mbụ, dịka ọmụmaatụ bytes JSON na-enweghị mgbanwe, na nzuzo njikọ. Mgbe ahụ, a na-agbakọ HMAC-SHA256. Ọ bụrụ na nsonaazụ n'ụdị hexadecimal dabara na uru header, ahụ agbanwebeghị mgbe e tinyere akara, arịrịọ ahụ nwekwara ike ịbụ nke otu nwere nzuzo ahụ zitere.

Ọmụmaatụ nkịtị: HMAC_SHA256(nzuzo, raw_body) = akara sitere na header X-Signature. Aha header, algọridim na usoro nsonaazụ kwesịrị isite naanị na akwụkwọ API. Ụfọdụ ọrụ na-agbakwunye stampụ oge ma ọ bụ ID omume na eriri maka akara. N'ọnọdụ a, enweghị ike ịlele naanị ahụ JSON.

Agbanwela JSON tupu ịlele akara

A na-elele akara site na bytes mbụ nke arịrịọ, ọ bụghị site na ihe JSON nke ngwa ahụ nyochara ma chịkọtaghachi ọzọ. Mgbe a na-ahazi ọzọ, usoro mpaghara, oghere, mgbapụ akara, mgbanwe ahịrị ma ọ bụ koodu nwere ike ịgbanwe. Nye mmadụ, JSON ga-anọgide otu, mana usoro bytes ga-agbanwe, HMAC agaghịkwa adaba.

Iji zere nke a, buru ụzọ nweta raw body dị ka bytes ma ọ bụ buffer, chekwaa ya na ebe nchekwa, gbakọọ akara, na naanị mgbe nyocha gara nke ọma ka nyochaa JSON. Etinyela trim, mgbanwe koodu, nhazi igodo na nhazi usoro na ahụ. Na middleware nke framework, lelee ma a na-anyocha JSON na-akpaghị aka tupu enweta ahụ mbụ.

Ihe ọjọọ nke atụmatụ a bụ na onye na-ahazi na-adabere na usoro middleware. Ọ bụrụ na ahaziri ya n'ụzọ na-ezighi ezi, ngwa ahụ ga-ahụ naanị ihe e gbanwere, ọkwa ziri ezi ga-amalite ịjụ.

Ọmụmaatụ onye na-ahazi nwere nyocha HMAC

Ihe dị n'okpuru bụ ọmụmaatụ nkịtị na Python. Ọ na-egosi usoro omume, ọ bụghị njikọ dị njikere: a ga-edochi headers, algọridim, usoro akara na mpaghara payload na ụkpụrụ sitere na akwụkwọ onye na-eweta ọrụ.

import hmac

import hashlib

import json

from hmac import compare_digest

def handle_webhook(request):

  raw_body = request.body

  received_signature = request.headers.get("X-Signature", "")

  secret = get_webhook_secret()

  expected_signature = hmac.new(

    secret.encode("utf-8"), raw_body, hashlib.sha256

  ).hexdigest()

  if not compare_digest(expected_signature, received_signature):

    log_invalid_signature(request)

    return response(status=401)

  payload = json.loads(raw_body.decode("utf-8"))

  return process_event(payload)

Maka ntụnyere, jiri ọrụ na-akwụsịghị na akara mbụ na-adabaghị. Nke a na-ebelata ihe ize ndụ nke ịwụpụ ozi gbasara akara site na oge nzaghachi. Ebufela nzuzo na koodu onye ahịa, tinyela ya na URL ma ọ bụ dee ya dum na ndekọ.

Mee ka nhazi omume bụrụ idempotent

Onye na-eweta ọrụ nwere ike ibuga otu omume ọtụtụ ugboro. Ihe kpatara ya bụ ihe nkịtị: sava gị zara ogologo oge, njikọ kwụsịrị mgbe echekwara data, endpoint weghachiri njehie nwa oge ma ọ bụ ọrụ ahụ malitere nnyefe ọzọ site na iwu ya. Ntinye ọzọ apụtaghị na API mepụtara iwu ọhụrụ.

Idempotency pụtara na otu omume na-agbanwe nsonaazụ naanị otu ugboro. Ọ bụrụ na e leghara iwu a anya, onye oyiri ga-ezigaghachi ozi nye onye ahịa, mepụta ọtụtụ ọrụ nye onye njikwa, nye nkwụghachi ma ọ bụ malite ọrụ ọzọ.

Kacha mma iji event_id sitere na payload. Debe ya na tebụl dị iche ma ọ bụ ndekọ omume a haziri nwere mmachi pụrụ iche. Ọ bụrụ na enweghị ID dị iche, mepụta igodo site na mpaghara kwụsiri ike: ID iwu nke onye na-eweta ọrụ, ụdị omume, ọkwa na oge mgbanwe. Nhọrọ a ka njọ: na stampụ oge na-ezighi ezi, omume dị iche iche nwere ike ịdị ka otu.

Chekwaa omume na ọkwa n'otu ọrụ

Nyocha «a haziri omume a?» na ndekọ nsonaazụ kwesịrị ime n'otu oge. Ma ọ bụghị ya, arịrịọ abụọ yiri onwe ha batara n'otu oge ga-ahụ enweghị ndekọ ma malite omume ugboro abụọ. Nhọrọ bara uru bụ ndeksi pụrụ iche na event_id na azụmahịa nchekwa data.

Ntinye nke onye na-ahazi na-aga n'ihu dị otú a:

def process_event(payload):

  event_id = payload["event_id"]

  provider_order_id = payload["data"]["order_id"]

  new_status = map_status(payload["data"]["status"])

  with database_transaction():

    if event_exists(event_id):

      return response(status=200)

    order = find_order_by_provider_id(provider_order_id)

    if order is None:

      save_unmatched_event(event_id, payload)

      return response(status=200)

    apply_status_if_allowed(order, new_status, payload)

    save_processed_event(event_id, provider_order_id)

  enqueue_follow_up_actions(event_id)

  return response(status=200)

Ihe ọjọọ nke ịza na koodu ọma maka iwu a na-amaghị bụ na onye na-eweta ọrụ nwere ike ịghara ịkwagharị nnyefe. Ya mere, a ga-enyocha omume a na-amaghị iche ma dozie ya ngwa ngwa. Ọ bụrụ na akwụkwọ API na-atụ aro koodu nzaghachi ọzọ maka ọnọdụ ndị dị otú a, soro ya.

Tụlee mmebi nke usoro omume

Webhook anaghị abịakarị n'usoro oge mgbanwe ọkwa. Nke mbụ, omume banyere mmechi nwere ike ịbịa, mgbe ahụ ọkwa gbubigara oge banyere ọkwa «na-arụ ọrụ». Ọ bụrụ na ị dee naanị uru ikpeazụ enwetara, iwu e mezuru ga-abụ ọzọ nke na-arụ ọrụ.

Tọọ mgbanwe ndị ekwenyere. Dịka ọmụmaatụ, ọkwa etiti enweghị ike idegharị nke ikpeazụ, a gaghịkwa agbanwe iwu e kagburu ka ọ bụrụ nke e mezuru na-enweghị nyocha iche. Ọ bụrụ na API na-ekwe ka mmezi nke ọkwa ikpeazụ, debe ihe kpatara ya, uru mbụ na isi iyi mgbanwe.

Ọ bụrụ na payload nwere oge mgbanwe iwu, tụnyere ya, ọ bụghị oge enwetara webhook. Mgbe API na-ebufeghị stampụ oge dị otú ahụ, jiri ọkwa ndị dị mkpa na ntụnyere site na usoro inweta iwu. Ihe ọjọọ nke ọkwa ndị dị mkpa bụ na ha anaghị edochi usoro n'ezie, karịsịa ma ọ bụrụ na onye na-eweta ọrụ na-ekwe ka nlọghachi site na ọkwa ikpeazụ.

Kwenye nnyefe ngwa ngwa ma wepụta omume na ọkwa

Emela ọrụ ogologo oge tupu ịza onye na-eweta ọrụ. Nyocha akara, ịchọta iwu, ịdekọ omume na imelite ọkwa na-emekarị ngwa ngwa. Iziga ozi, imekọrịta na CRM, ịmepụta akụkọ ma ọ bụ arịrịọ na sistemụ ndị ọzọ ka mma ibufe na ọkwa ọrụ.

Usoro ọrụ dị otú a: lelee akara, chekwaa omume na mgbanwe ọkwa n'otu oge, weghachi nzaghachi ọma, wee mee omume nke abụọ. Ọ bụrụ na ị zaa tupu echekwaa, data ga-efu ma ọ bụrụ na enwee ọdịda. Ọ bụrụ na ị zaa mgbe iziga ọkwa ogologo oge gasịrị, onye na-eweta ọrụ nwere ike iwere nnyefe ahụ dị ka nke na-aga nke ọma ma ziga onye oyiri.

Ihe ọjọọ nke ọkwa bụ na otu akụkụ dị iche na-apụta, nke a ga-achịkwa: njehie ọrụ, igbu oge na mmalite ọzọ. Ma ọdịda na ọkwa onye njikwa anaghị egbochi ịnabata ọkwa iwu.

Hazie ọkwa maka otu na onye ahịa

Mgbe ọkwa gbanwere, ekwesịghị ịkọwa otu ihe nye mmadụ niile. Onye njikwa na-achọkarị nkagbu, njehie, mmezu nke ọma na iwu ndị na-agbanweghị ogologo oge. Onye ahịa na-ezukarị nsonaazụ doro anya: e mezuru iwu, e kagburu ya ma ọ bụ ọ chọrọ nkọwa.

• Iwu e mezuru — mmelite na akaụntụ onwe onye ma ọ bụ ozi dị mkpirikpi nye onye ahịa.
• Njehie mmezu — ọkwa nye onye ọrụ nwere ihe kpatara nke API bufere.
• Mmezu nke ọma — ọrụ maka nyocha mmezi, nlọghachi ma ọ bụ omume ọzọ.
• Ọkwa a na-amaghị — ndekọ na ndekọ na ozi nye ọkachamara teknụzụ.
• ID iwu a na-amaghị — nyocha iche nke njikọ n'etiti sistemụ gị na onye na-eweta ọrụ.

Eziganla ozi na mgbanwe teknụzụ ọ bụla. Feeds ga-agbanwe ngwa ngwa ka ọ bụrụ mkpọtụ, nsogbu dị mkpa ga-anọgidekwa na-ahụghị ya. Ọkwa ime kwesịrị ịnwe nọmba iwu, ọrụ, ọkwa ugbu a, ID mpụga na njikọ na kaadị.

Debe ndekọ ma tụnyere iwu ndị na-emechaghị

A chọrọ ndekọ iji ghọta ma ọrụ ahụ zigara omume, ahụ ọ bịara, ihe kpatara akara anaghị agafe na ebe nhazi kwụsịrị. Debe oge nnata, ID omume, ID iwu, ụdị omume, nsonaazụ nyocha akara, ọkwa ime na koodu nzaghachi. Kpuchie nzuzo, token na data onwe onye.

Nyochaa iche njehie nnyefe, akara na-ezighi ezi, iwu a na-amaghị, ọkwa a na-akwadoghị, ndị oyiri na omume ndị a na-enweghị ike itinye n'ihi usoro ọnọdụ. Mmụba nke ndekọ ndị dị otú a nwere ike ịpụta mgbanwe nke atụmatụ API, nzuzo kubiri, ọdịda ụzọ ma ọ bụ njehie na usoro onye na-ahazi.

Site n'oge ruo n'oge, tụnyere iwu ndị dị na ọkwa etiti site na usoro inweta data API. Nyocha a anaghị edochi webhook, mana ọ na-enyere aka ịchọpụta omume furu efu, ọdịda ọkwa ma ọ bụ ọnọdụ ebe ọkwa mpụga gbanwere na-enweghị ọkwa ziri ezi.