Kako nastaviti obvestila o zaključku naročil prek API-ja

Kateri dogodki veljajo za zaključek naročila

Najprej določite, kateri status v API-ju pomeni dejanski zaključek naročila. Pri različnih ponudnikih so to lahko izpolnjeno, dostavljeno, preklicano, zavrnjeno, vrnjeno ali delno izpolnjeno naročilo. Avtomatizacije ne vežite samo na besedo »uspeh«: naročilo lahko preide več vmesnih stanj, nato pa se ustavi zaradi omejitve, preverjanja ali preklica.

Obdelati je treba tudi neuspešne izide. Če storitev pošlje obvestilo o napaki, preklicu, vračilu ali delni izpolnitvi, ga je prav tako treba zabeležiti v interni sistem. Sicer bo naročilo na nadzorni plošči, v CRM-ju ali botu ostalo v čakanju, čeprav se nadaljnja izvedba ne bo zgodila.

Pripravite tabelo preslikave statusov

Statusa API ne posredujte v vmesnik brez obdelave. Imena in logika ponudnika se lahko spremenijo, isti interni status pa lahko včasih združuje več zunanjih. Izvirno vrednost hranite ločeno: prišla bo prav pri odpravljanju napak in usklajevanju z dokumentacijo.

• pending, created, queued — novo naročilo ali naročilo, ki čaka na obdelavo.
• processing, in_progress, running — naročilo se izvaja.
• completed, delivered, success — izpolnjeno naročilo.
• partial, partially_completed — delno izpolnjeno naročilo.
• cancelled, rejected, failed — preklicano naročilo ali naročilo, ki se je končalo z napako.
• refunded, returned — naročilo zahteva vračilo ali popravek.
• Neznan status — kartice ne spremeni samodejno in se posreduje v preverjanje.

Zgornja imena so navedena kot primer sheme. Končno tabelo je treba sestaviti po statusih konkretnega API-ja. Pomanjkljivost ročnega preslikavanja je, da ga je treba po posodobitvi API-ja vzdrževati: nov status lahko pride v obdelovalec, preden zanj obstaja pravilo.

Izberite spletne kavlje, poizvedovanje API ali obe shemi

Spletni kavelj je zahteva storitve na vaš URL ob spremembi statusa naročila. Poizvedovanje API deluje obratno: vaš sistem v rednih intervalih poizveduje o naročilu. Za obvestila o zaključku so običajno primernejši spletni kavlji, ker posodobitev prispe brez nenehnih zahtev na metodo za preverjanje statusa.

• Spletni kavlji so primerni za hiter odziv: posodobitev kartice, zagon naslednje faze ali pošiljanje sporočila odgovorni osebi.
• Poizvedovanje je primerno, če ponudnik ne podpira povratnih obvestil ali strežnik ne sprejema zunanjih zahtev.
• Kombinirana shema uporablja spletne kavlje kot glavni kanal, poizvedovanje pa za iskanje zamujenih ali obtičalih naročil.

Pomanjkljivost poizvedovanja sta zakasnitev in dodatna obremenitev API-ja. Pomanjkljivost spletnih kavljev je, da je treba končno točko zaščititi, upoštevati dvojnike in se ne zanašati na vrstni red dostave dogodkov.

Nastavite končno točko za sprejemanje dogodkov

Za obvestila potrebujete javni naslov HTTPS, dostopen s strani storitve API. V nastavitvah integracije se običajno navedejo URL obdelovalca, skrivnost podpisa in seznam dogodkov: sprememba statusa, zaključek, preklic, napaka ali delna izpolnitev.

Za dogodke API določite ločeno pot. Tako je lažje nastaviti beleženje, omejiti dostop, določiti omejitve zahtev in ne mešati servisnega prometa z obrazci na spletnem mestu. Za delovna naročila ne uporabljajte naslova testnega okolja: po posodobitvi okolja bo ponudnik še naprej pošiljal dogodke na shranjeni URL.

Pred zagonom preverite metodo zahteve in obliko telesa v dokumentaciji. Najpogosteje je to POST z JSON, vendar se pojavljajo tudi form-data, parametri poizvedbe ali lastna shema serializacije. Napako pri razčlenjevanju je treba zabeležiti v dnevnik, sicer bo težko ločiti napačen payload od okvare aplikacije.

Ohranite povezavo med naročilom in dogodkom

Pri ustvarjanju naročila prek API-ja shranite identifikator, ki ga je vrnil ponudnik. Ob njem hranite interno številko naročila, vrsto storitve, izvirni status, čas zadnje spremembe in izvirni odgovor API-ja v varni obliki. Dohodni spletni kavelj povežite po ID-ju ponudnika, ne po povezavi na kanal, imenu storitve ali imenu stranke.

Če API dovoljuje posredovanje zunanjega identifikatorja ob ustvarjanju, dodajte svojo številko naročila v polje, kot je external_id ali client_reference. To olajša iskanje v dnevnikih in razreševanje spornih situacij. Vendar zunanje številke ne uporabljajte kot edini ključ: nekateri ponudniki je ne vrnejo v vsakem obvestilu.

Ne ustvarjajte novega naročila na podlagi neznanega ID-ja iz spletnega kavlja. Neznan dogodek je treba shraniti v dnevnik in ga preveriti ločeno. Samodejno ustvarjanje zapisa lahko privede do napačnih podatkov ali obdelave ponarejene zahteve.

Uporabite pregledno strukturo payload

Natančna imena polj so odvisna od API-ja. Spodaj ni pogodba določene storitve, temveč primer dogodka JSON, po katerem se lahko zgledujete pri načrtovanju internega obdelovalca. Pomembni so identifikator dogodka, ID naročila pri ponudniku, status, čas spremembe in podatki za diagnostiko.

{

  "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

  }

}

Količine izpolnjenih enot ne uporabljajte kot znak zaključka brez statusa. Naročilo je lahko delno izpolnjeno, število v payloadu pa je lahko zaokroženo, posodobljeno z zakasnitvijo ali sploh ni posredovano. Pomanjkljivost shranjevanja celotnega telesa dogodka je, da lahko vsebuje osebne podatke ali servisna polja, zato je treba takšne zapise maskirati in omejiti čas hrambe.

Preverite podpis po izvirnem telesu zahteve

Odprti URL obdelovalca lahko prejme zahtevo, ki ne prihaja od storitve API. Če ponudnik posreduje podpis, skrivnost ali žeton, jih preverite pred spremembo naročila. Pogosta shema je HMAC-SHA256: ponudnik izračuna podpis iz bajtov telesa zahteve in skupne skrivnosti, nato pa rezultat posreduje v glavi HTTP.

Načelo izračuna je naslednje: vzame se izvirno telo zahteve, na primer bajti JSON brez sprememb, in skrivnost integracije. Nato se izračuna HMAC-SHA256. Če se rezultat v šestnajstiški obliki ujema z vrednostjo glave, se telo po podpisu ni spremenilo in zahtevo je verjetno poslala stran, ki pozna skrivnost.

Pogojni primer: HMAC_SHA256(skrivnost, raw_body) = podpis iz glave X-Signature. Ime glave, algoritem in obliko rezultata je treba vzeti samo iz dokumentacije API-ja. Nekatere storitve v niz za podpis dodajo časovni žig ali ID dogodka. V tem primeru ni mogoče preverjati samo telesa JSON.

Ne spreminjajte JSON pred preverjanjem podpisa

Podpis se preverja po izvirnih bajtih zahteve, ne po objektu JSON, ki ga je aplikacija že razčlenila in znova sestavila. Pri ponovni serializaciji se lahko spremenijo vrstni red polj, presledki, izhodni znaki, prelom vrstice ali kodiranje. Za človeka bo JSON ostal enak, nabor bajtov pa se bo spremenil in HMAC se ne bo več ujemal.

Da se temu izognete, najprej pridobite raw body kot bytes ali buffer, ga shranite v pomnilnik, izračunajte podpis in šele po uspešnem preverjanju razčlenite JSON. Na telo ne uporabljajte trim, pretvorbe kodiranja, razvrščanja ključev in oblikovanja. V middleware ogrodja preverite, ali se JSON samodejno razčleni pred dostopom do izvirnega telesa.

Pomanjkljivost te sheme je, da obdelovalec postane odvisen od vrstnega reda middleware. Ob napačni nastavitvi bo aplikacija videla samo pretvorjen objekt, legitimna obvestila pa bodo začela biti zavrnjena.

Primer obdelovalca s preverjanjem HMAC

Spodaj je pogojni primer v Pythonu. Prikazuje vrstni red dejanj, ne pa pripravljene integracije: glave, algoritem, obliko podpisa in polja payload je treba zamenjati z vrednostmi iz dokumentacije ponudnika.

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)

Za primerjavo uporabite funkcijo, ki se ne ustavi ob prvem neujemajočem se znaku. To zmanjša tveganje uhajanja podatkov o podpisu prek časa odziva. Skrivnosti ne posredujte v odjemalsko kodo, je ne dodajajte v URL in je ne zapisujte v celoti v dnevnike.

Obdelava dogodkov naj bo idempotentna

Ponudnik lahko isti dogodek dostavi večkrat. Razlogi so običajni: vaš strežnik je dolgo odgovarjal, povezava se je prekinila po shranjevanju podatkov, končna točka je začasno vrnila napako ali pa je storitev zagnala ponovno dostavo po svojih pravilih. Ponovitev ne pomeni, da je API ustvaril novo naročilo.

Idempotentnost pomeni, da enak dogodek spremeni rezultat samo enkrat. Če tega pravila ne upoštevate, bo dvojnik znova poslal sporočilo stranki, ustvaril več nalog za upravitelja, dodelil nadomestilo ali zagnal ponovno operacijo.

Najbolje je uporabiti event_id iz payloada. Shranjujte ga v ločeni tabeli ali dnevniku obdelanih dogodkov z edinstveno omejitvijo. Če ločenega ID-ja ni, sestavite ključ iz stabilnih polj: ID naročila ponudnika, vrste dogodka, statusa in časa spremembe. Ta možnost je slabša: pri nenatančnih časovnih žigih so lahko različni dogodki videti enaki.

Shranite dogodek in status v eni operaciji

Preverjanje, ali je dogodek že obdelan, in zapis rezultata se morata izvesti atomsko. Sicer bosta dve enaki zahtevi, ki prideta hkrati, obe videli, da zapisa ni, in dejanje zagnali dvakrat. Praktična možnost je edinstven indeks po event_id in transakcija baze podatkov.

Pogojno nadaljevanje obdelovalca je videti takole:

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)

Pomanjkljivost odgovora z uspešno kodo za neznano naročilo je, da ponudnik dostave morda ne bo ponovil. Zato je treba neznane dogodke spremljati ločeno in jih hitro razrešiti. Če dokumentacija API-ja priporoča drugačno kodo odgovora za takšne primere, ji sledite.

Upoštevajte kršitev vrstnega reda dogodkov

Spletni kavlji ne pridejo vedno strogo po času spremembe statusa. Najprej lahko prispe dogodek o zaključku, nato pa zakasnjeno obvestilo o statusu »v izvajanju«. Če preprosto zapišete zadnjo prejeto vrednost, bo izpolnjeno naročilo znova postalo aktivno.

Določite dovoljene prehode. Na primer, vmesni status ne more prepisati končnega, preklicanega naročila pa ni mogoče prevesti v izpolnjeno brez ločenega preverjanja. Če API dovoljuje popravek končnega statusa, shranite razlog, izvirno vrednost in vir spremembe.

Če payload vsebuje čas spremembe naročila, primerjajte prav tega, ne časa prejema spletnega kavlja. Ko API ne posreduje takšne oznake, uporabite prioritete stanj in usklajevanje prek metode za pridobitev naročila. Pomanjkljivost prioritet je, da ne nadomestijo dejanskega zaporedja, še posebej če ponudnik dovoljuje vračilo iz končnega statusa.

Hitro potrdite dostavo in dejanja prenesite v čakalno vrsto

Pred odgovorom ponudniku ne izvajajte dolgih operacij. Preverjanje podpisa, iskanje naročila, zapis dogodka in posodobitev statusa je običajno mogoče zaključiti hitro. Pošiljanje sporočila, sinhronizacijo s CRM-jem, pripravo poročila ali zahteve do zunanjih sistemov je bolje prenesti v čakalno vrsto opravil.

Delovni vrstni red je tak: preverite podpis, atomsko shranite dogodek in spremembo statusa, vrnete uspešen odgovor, nato izvedete sekundarna dejanja. Če odgovorite pred shranjevanjem, se bodo podatki ob okvari izgubili. Če odgovorite po dolgem pošiljanju obvestila, lahko ponudnik dostavo šteje za neuspešno in pošlje dvojnik.

Pomanjkljivost čakalne vrste je, da se pojavi ločena komponenta, ki jo je treba nadzorovati: napake opravil, zakasnitve in ponovni zagoni. Prednost pa je, da okvara pri obveščanju upravitelja ne blokira sprejemanja statusov naročil.

Nastavite obvestila za ekipo in stranko

Po spremembi statusa ni treba vseh obveščati enako. Upravitelju so običajno pomembni preklici, napake, delna izpolnitev in naročila, ki se dolgo ne spreminjajo. Stranki pogosto zadostuje razumljiv izid: naročilo je izpolnjeno, preklicano ali zahteva pojasnilo.

• Zaključeno naročilo — posodobitev v osebnem računu ali kratko sporočilo stranki.
• Napaka pri izvajanju — obvestilo odgovorni osebi z razlogom, ki ga je posredoval API.
• Delna izpolnitev — naloga za preverjanje popravka, vračila ali naslednjega dejanja.
• Neznan status — zapis v dnevnik in sporočilo tehničnemu strokovnjaku.
• Neznan ID naročila — ločeno preverjanje povezave med vašim sistemom in ponudnikom.

Ne pošiljajte sporočila ob vsakem tehničnem prehodu. Vir bo hitro postal hrupen, pomembna težava pa bo ostala neopažena. Interno obvestilo mora vsebovati številko naročila, storitev, trenutni status, zunanji ID in povezavo do kartice.

Vodite dnevnik in usklajujte nedokončana naročila

Dnevniki so potrebni, da ugotovite, ali je storitev poslala dogodek, kakšno telo je prispelo, zakaj podpis ni uspel in na kateri stopnji se je obdelava ustavila. Shranjujte čas prejema, ID dogodka, ID naročila, vrsto dogodka, rezultat preverjanja podpisa, interni status in kodo odgovora. Skrivnosti, žetone in osebne podatke maskirajte.

Ločeno spremljajte napake pri dostavi, neveljavne podpise, neznana naročila, nepodprte statuse, dvojnike in dogodke, ki jih zaradi vrstnega reda stanj ni mogoče uporabiti. Rast takšnih zapisov lahko pomeni spremembo sheme API-ja, poteklo skrivnost, okvaro poti ali napako v logiki obdelovalca.

Občasno uskladite naročila v vmesnih statusih prek metode za pridobitev podatkov API-ja. To preverjanje ne nadomešča spletnih kavljev, vendar pomaga odkriti zamujen dogodek, okvaro čakalne vrste ali primer, ko se je zunanji status spremenil brez pravilnega obvestila.