Hogyan állítsuk be az API-rendelések befejezéséről szóló értesítéseket

Mely események számítanak a rendelés befejezésének

Először rögzítse, melyik státusz jelenti az API-ban a rendelés tényleges befejezését. Különböző szolgáltatóknál ez lehet teljesített, kiszállított, törölt, elutasított, visszaküldött vagy részben teljesített rendelés. Ne kösse az automatizálást kizárólag a „siker” szóhoz: a rendelés több köztes állapoton is áthaladhat, majd megállhat egy limit, ellenőrzés vagy törlés miatt.

Nem csak a pozitív eredményt kell feldolgozni. Ha a szolgáltatás értesítést küld hibáról, törlésről, visszaküldésről vagy részleges teljesítésről, azt is rögzíteni kell a belső rendszerben. Ellenkező esetben a panelben, a CRM-ben vagy a botban a rendelés várakozó állapotban marad, pedig a további teljesítés már nem fog megtörténni.

Készítsen státusz-megfeleltetési táblázatot

Ne adja tovább az API státuszát feldolgozás nélkül a felületnek. A szolgáltató elnevezései és logikája változhat, és ugyanaz a belső státusz néha több külső státuszt von össze. Az eredeti értéket tárolja külön: hasznos lesz a hibák elemzéséhez és a dokumentációval való egyeztetéshez.

• pending, created, queued — új vagy feldolgozásra váró rendelés.
• processing, in_progress, running — a rendelés teljesítés alatt áll.
• completed, delivered, success — teljesített rendelés.
• partial, partially_completed — részben teljesített rendelés.
• cancelled, rejected, failed — törölt vagy hibával lezárult rendelés.
• refunded, returned — a rendelés visszatérítést vagy korrekciót igényel.
• Ismeretlen státusz — nem módosítja automatikusan a kártyát, és ellenőrzésre kerül.

A fenti elnevezések csak példák egy sémára. A végleges táblázatot az adott API státuszai alapján kell felépíteni. A kézi leképezés hátránya, hogy az API frissítése után karban kell tartani: egy új státusz hamarabb eljuthat a kezelőhöz, mint hogy szabály születne rá.

Válasszon webhookokat, API-lekérdezést vagy mindkét sémát

A webhook egy kérés a szolgáltatástól az Ön URL-jére, amikor a rendelés státusza megváltozik. Az API-lekérdezés fordítva működik: az Ön rendszere adott időközönként információt kér a rendelésről. A befejezésről szóló értesítésekhez általában kényelmesebbek a webhookok, mert a frissítés állandó státuszellenőrző kérések nélkül érkezik.

• A webhookok alkalmasak a gyors reakcióra: a kártya frissítésére, a következő szakasz elindítására vagy üzenet küldésére a felelősnek.
• A lekérdezés akkor alkalmas, ha a szolgáltató nem támogat callback-értesítéseket, vagy a szerver nem fogad külső kéréseket.
• A kombinált séma a webhookokat használja fő csatornaként, a lekérdezést pedig a kihagyott vagy elakadt rendelések felkutatására.

A lekérdezés hátránya a késleltetés és az API felesleges terhelése. A webhookok hátránya, hogy védeni kell az endpointot, figyelembe kell venni a duplikátumokat, és nem szabad az események kézbesítési sorrendjére hagyatkozni.

Állítson be endpointot az események fogadásához

Az értesítésekhez nyilvános HTTPS-cím szükséges, amely elérhető az API-szolgáltatás felől. Az integráció beállításaiban általában megadják a kezelő URL-jét, az aláírási titkot és az események listáját: státuszváltozás, befejezés, törlés, hiba vagy részleges teljesítés.

Jelöljön ki külön útvonalat kizárólag az API-események számára. Így könnyebb beállítani a naplózást, korlátozni a hozzáférést, kéréslimiteket megadni, és nem keveredik a szolgálati forgalom a webhely űrlapjaival. Ne használjon tesztkörnyezeti címet éles rendelésekhez: a környezet frissítése után a szolgáltató továbbra is a mentett URL-re küldi az eseményeket.

Indítás előtt ellenőrizze a kérés metódusát és a törzs formátumát a dokumentáció alapján. Leggyakrabban POST JSON-nal, de előfordul form-data, query-paraméterek vagy saját szerializációs séma. Az értelmezési hibát naplózni kell, különben nehéz lesz megkülönböztetni a hibás payloadot az alkalmazás hibájától.

Őrizze meg a kapcsolatot a rendelés és az esemény között

Az API-n keresztül történő rendelés létrehozásakor mentse el a szolgáltató által visszaadott azonosítót. Mellette tárolja a belső rendelésszámot, a szolgáltatás típusát, az eredeti státuszt, az utolsó módosítás idejét és az API eredeti válaszát biztonságos formában. A beérkező webhookot a szolgáltató ID-ja alapján párosítsa, ne a csatornára mutató hivatkozás, a szolgáltatás neve vagy az ügyfél neve alapján.

Ha az API engedi külső azonosító átadását létrehozáskor, adja hozzá saját rendelésszámát egy external_id vagy client_reference jellegű mezőben. Ez megkönnyíti a keresést a naplókban és a vitás helyzetek elemzését. De ne tegye a külső számot egyetlen kulccsá: egyes szolgáltatók nem adják vissza minden értesítésben.

Ne hozzon létre új rendelést a webhookból származó ismeretlen ID alapján. Az ismeretlen eseményt naplózni kell, és külön ellenőrizni. A rekord automatikus létrehozása hibás adatokhoz vagy hamis kérés feldolgozásához vezethet.

Használjon érthető payload-szerkezetet

A mezők pontos nevei az API-tól függenek. Az alábbi nem egy adott szolgáltatás szerződése, hanem példa egy JSON-eseményre, amely iránymutatásul szolgálhat a belső kezelő tervezésekor. Fontos az esemény azonosítója, a rendelés ID-ja a szolgáltatónál, a státusz, a módosítás ideje és a diagnosztikai adatok.

{

  "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

  }

}

Ne használja a teljesített egységek számát a befejezés ismérveként státusz nélkül. A rendelés részben is teljesülhet, a payloadban szereplő szám pedig lehet kerekített, késve frissített vagy egyáltalán nem átadott. Az esemény teljes törzsének tárolásának hátránya, hogy személyes adatok vagy szolgálati mezők kerülhetnek bele, ezért az ilyen rekordokat maszkolni kell és a megőrzési időt korlátozni.

Ellenőrizze az aláírást az eredeti kéréstörzs alapján

A nyílt kezelő URL-hez nem csak az API-szolgáltatástól érkezhet kérés. Ha a szolgáltató aláírást, titkot vagy tokent ad át, ellenőrizze azokat a rendelés módosítása előtt. Gyakori séma a HMAC-SHA256: a szolgáltató a kéréstörzs bájtjaiból és egy közös titokból számítja ki az aláírást, majd az eredményt HTTP-fejlécben adja át.

A számítás elve így néz ki: vesszük az eredeti kéréstörzset, például a változatlan JSON bájtokat, és az integráció titkát. Ezután kiszámítjuk a HMAC-SHA256-ot. Ha az eredmény hexadecimális formában megegyezik a fejléc értékével, a törzs nem változott az aláírás után, és a kérést valószínűleg a titkot ismerő fél küldte.

Feltételes példa: HMAC_SHA256(titok, raw_body) = az X-Signature fejlécben szereplő aláírás. A fejléc nevét, az algoritmust és az eredmény formátumát kizárólag az API dokumentációjából vegye. Egyes szolgáltatások időbélyeget vagy esemény-ID-t adnak az aláírandó karakterlánchoz. Ebben az esetben nem ellenőrizhető csak a JSON-törzs.

Ne módosítsa a JSON-t az aláírás ellenőrzése előtt

Az aláírást a kérés eredeti bájtjai alapján ellenőrzik, nem azon JSON-objektum alapján, amelyet az alkalmazás már értelmezett és újra összeállított. Az újraszerializálás megváltoztathatja a mezők sorrendjét, a szóközöket, a karakterek escape-elését, a sortörést vagy a kódolást. Az ember számára a JSON ugyanaz marad, de a bájtok halmaza megváltozik, és a HMAC már nem fog egyezni.

Ennek elkerüléséhez először szerezze be a raw body-t bytes vagy buffer formában, tartsa a memóriában, számítsa ki az aláírást, és csak a sikeres ellenőrzés után értelmezze a JSON-t. Ne alkalmazzon a törzsre trim-et, kódolásátalakítást, kulcsrendezést és formázást. A keretrendszer middleware-jében ellenőrizze, hogy a JSON nem kerül-e automatikusan értelmezésre az eredeti törzs elérése előtt.

Ennek a sémának a hátránya, hogy a kezelő függővé válik a middleware sorrendjétől. Hibás beállítás esetén az alkalmazás csak az átalakított objektumot látja, és a legitim értesítések elutasításra kerülnek.

Példa kezelőre HMAC-ellenőrzéssel

Az alábbi egy feltételes példa Pythonban. A műveletek sorrendjét mutatja, nem kész integrációt: a fejléceket, az algoritmust, az aláírás formátumát és a payload mezőit a szolgáltató dokumentációjában szereplő értékekre kell cserélni.

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)

Az összehasonlításhoz olyan függvényt használjon, amely nem áll le az első eltérő karakternél. Ez csökkenti az aláírásra vonatkozó adatok válaszidőn keresztüli kiszivárgásának kockázatát. A titkot ne adja át kliensoldali kódnak, ne fűzze az URL-hez, és ne naplózza teljes egészében.

Tegye idempotenssé az események feldolgozását

A szolgáltató ugyanazt az eseményt többször is kézbesítheti. Az okok megszokottak: a szerver sokáig válaszolt, a kapcsolat az adatok mentése után megszakadt, az endpoint átmenetileg hibát adott vissza, vagy a szolgáltatás saját szabályai szerint újrakézbesítést indított. Az ismétlés nem jelenti azt, hogy az API új rendelést hozott létre.

Az idempotencia azt jelenti, hogy ugyanaz az esemény csak egyszer változtat az eredményen. Ha nem veszi figyelembe ezt a szabályt, a duplikátum újra üzenetet küld az ügyfélnek, több feladatot hoz létre a menedzsernek, kompenzációt ír jóvá vagy megismétel egy műveletet.

A legjobb a payloadban szereplő event_id használata. Tárolja külön táblában vagy feldolgozott események naplójában egyedi megkötéssel. Ha nincs külön ID, képezzen kulcsot stabil mezőkből: a szolgáltató rendelés-ID-ja, az esemény típusa, a státusz és a módosítás ideje. Ez a változat rosszabb: pontatlan időbélyegek esetén különböző események tűnhetnek azonosnak.

Egy műveletben mentse az eseményt és a státuszt

A „feldolgozva van-e az esemény” ellenőrzését és az eredmény rögzítését atomikusan kell végrehajtani. Ellenkező esetben két azonos, egyidejűleg érkező kérés mindkettő hiányolni fogja a rekordot, és kétszer indítja el a műveletet. Gyakorlati megoldás az event_id szerinti egyedi index és egy adatbázis-tranzakció.

A kezelő feltételes folytatása így néz ki:

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)

Az ismeretlen rendelésre adott sikeres kód hátránya, hogy a szolgáltató esetleg nem ismétli meg a kézbesítést. Ezért az ismeretlen eseményeket külön figyelni kell, és gyorsan ki kell vizsgálni. Ha az API dokumentációja más válaszkódot javasol ilyen esetekre, kövesse azt.

Vegye figyelembe az események sorrendjének felborulását

A webhookok nem mindig szigorúan a státuszváltozás ideje szerint érkeznek. Először érkezhet a befejezésről szóló esemény, majd egy késve érkező értesítés a „folyamatban” státuszról. Ha egyszerűen a legutóbb kapott értéket írja be, a teljesített rendelés újra aktívvá válik.

Határozzon meg engedélyezett átmeneteket. Például egy köztes státusz nem írhatja felül a véglegeset, és egy törölt rendelés külön ellenőrzés nélkül nem kerül teljesített állapotba. Ha az API engedi a végleges státusz korrekcióját, mentse el az okot, az eredeti értéket és a módosítás forrását.

Ha a payload tartalmazza a rendelés módosításának idejét, azt hasonlítsa össze, ne a webhook fogadásának idejét. Ha az API nem ad át ilyen jelölést, használjon állapotprioritásokat és egyeztessen a rendelés lekérdezési metódusán keresztül. A prioritások hátránya, hogy nem helyettesítik a valós sorrendet, különösen ha a szolgáltató engedi a visszatérést a végleges státuszból.

Gyorsan igazolja a kézbesítést, és tegye a műveleteket sorba

Ne végezzen hosszú műveleteket a szolgáltatónak adott válasz előtt. Az aláírás ellenőrzése, a rendelés keresése, az esemény rögzítése és a státusz frissítése általában gyorsan befejezhető. Az üzenetküldést, a CRM-mel való szinkronizálást, a jelentéskészítést vagy a külső rendszerek felé irányuló kéréseket jobb feladatütemezőnek átadni.

A működő sorrend így néz ki: ellenőrizze az aláírást, atomikusan mentse az eseményt és a státuszváltozást, adjon vissza sikeres választ, majd hajtsa végre a másodlagos műveleteket. Ha a mentés előtt válaszol, hiba esetén az adatok elvesznek. Ha a hosszú értesítésküldés után válaszol, a szolgáltató sikertelennek tekintheti a kézbesítést, és duplikátumot küldhet.

A sor hátránya, hogy megjelenik egy külön komponens, amelyet felügyelni kell: feladathibák, késleltetések és ismételt futtatások. Cserébe a menedzser értesítésének hibája nem blokkolja a rendelési státuszok fogadását.

Állítson be értesítéseket a csapat és az ügyfél számára

A státuszváltozás után nem kell mindenkit ugyanúgy értesíteni. A menedzsernek általában a törlések, hibák, részleges teljesítések és a sokáig változatlan rendelések fontosak. Az ügyfélnek gyakrabban elég egy érthető végkimenet: a rendelés teljesült, törölték, vagy pontosításra vár.

• Teljesített rendelés — frissítés a fiókban vagy rövid üzenet az ügyfélnek.
• Teljesítési hiba — értesítés a felelősnek az API által átadott okkal.
• Részleges teljesítés — feladat a korrekció, visszatérítés vagy következő lépés ellenőrzésére.
• Ismeretlen státusz — naplóbejegyzés és üzenet a technikai szakembernek.
• Ismeretlen rendelés-ID — az Ön rendszere és a szolgáltató közötti kapcsolat külön ellenőrzése.

Ne küldjön üzenetet minden technikai átmenetnél. A hírfolyam gyorsan zajjá válik, és egy fontos probléma észrevétlen marad. A belső értesítésnek tartalmaznia kell a rendelésszámot, a szolgáltatást, az aktuális státuszt, a külső ID-t és a kártyára mutató hivatkozást.

Vezessen naplót, és egyeztesse a be nem fejezett rendeléseket

A naplókra azért van szükség, hogy megértsük, küldött-e eseményt a szolgáltatás, milyen törzs érkezett, miért nem ment át az aláírás, és melyik szakaszban állt meg a feldolgozás. Mentse a fogadás idejét, az esemény ID-ját, a rendelés ID-ját, az esemény típusát, az aláírás-ellenőrzés eredményét, a belső státuszt és a válaszkódot. A titkokat, tokeneket és személyes adatokat maszkolja.

Külön kövesse a kézbesítési hibákat, az érvénytelen aláírásokat, az ismeretlen rendeléseket, a nem támogatott státuszokat, a duplikátumokat és azokat az eseményeket, amelyeket az állapotok sorrendje miatt nem lehet alkalmazni. Az ilyen bejegyzések növekedése az API-séma változását, lejárt titkot, útvonalhibát vagy a kezelő logikájának hibáját jelezheti.

Rendszeresen egyeztesse a köztes státuszban lévő rendeléseket az API adatlekérdezési metódusán keresztül. Ez az ellenőrzés nem helyettesíti a webhookokat, de segít felderíteni egy kihagyott eseményt, egy sorhibát vagy azt az esetet, amikor a külső státusz megfelelő értesítés nélkül változott meg.