A „feldolgozás alatt” állapot kezelése a rendelés API-n keresztüli ellenőrzésekor

Mit jelent a processing az API válaszában

A processing, in_progress vagy más ezzel egyenértékű állapot azt jelenti, hogy a szolgáltató átvette a rendelést feldolgozásra, de még nem rögzítette az eredményt. Promóciós szolgáltatások esetében ez lehet a hivatkozás ellenőrzése, a sorban állás, a feladat elindítása vagy a megrendelt mennyiség fokozatos teljesítése.

A processing nem igazolja a sikeres teljesítést, és nem jelent hibát sem. Utána a rendelés átléphet completed, partial, canceled vagy failed állapotba. Amíg a szolgáltató köztes állapotot ad vissza, ne hozzon létre újabb kérést ugyanarra a hivatkozásra és ugyanarra a mennyiségre.

A HTTP 200 processing állapottal sikeres API-választ jelent, nem a rendelés sikeres befejezését. Ezeket az eseményeket külön kell tárolni és kezelni.

Milyen adatok szükségesek a rendelés ellenőrzéséhez

A pollinghoz szükség van arra a külső rendelés-ID-ra, amelyet a szolgáltató a létrehozáskor visszaadott. Ezt a belső ID-val, az eredeti mennyiséggel, a szolgáltatás paramétereivel, a hivatkozással, a létrehozás idejével és az eredeti API-válasszal együtt tárolja. A csatorna neve, a hivatkozás vagy a mennyiség alapján nem megbízható a rendelés keresése: ezek az értékek több kérésnél is megegyezhetnek.

Ha a létrehozás után időtúllépés érkezik, ne küldje újra automatikusan a kérést. A szolgáltató fogadhatta a kérést, és a válasz elveszhetett az úton. Először használja a rendeléskereső metódust, ha van ilyen a dokumentációban, vagy adja át az esetet ellenőrzésre.

Ha csak az aktuális állapotot tárolja, vita esetén nem lehet visszaállítani, mikor lépett a rendelés processing állapotba, volt-e előrehaladás, és milyen válaszok érkeztek korábban.

Példa állapotlekérdezésre curl-lel

A pontos címet, az engedélyezési módot és a mezőneveket a szolgáltató dokumentációjából vegye. Az alábbiakban egy sablon látható: a csúcsos zárójelben lévő értékeket az adott API adataival kell helyettesíteni.

GET-kérés egyetlen rendeléshez

curl -X GET "https:///orders//status" \

-H "Authorization: Bearer " \

-H "Accept: application/json"

Példa válaszra:

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

"updated_at": "időérték"

}

A completed_quantity és a remains mezők csak a szerkezet példájaként szerepelnek. A szolgáltató használhat progress, start_count, balance vagy más neveket. A GET-megközelítés hátránya, hogy egyes API-k csak POST-on keresztül fogadják el az állapotellenőrzést.

Példa POST-kérésre és kötegelt ellenőrzésre

POST-kérés egyetlen rendelés állapotához

curl -X POST "https:///orders/status" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_id":""}'

Ne adja át az API-kulcsot az URL-ben. A kérés címek bekerülnek a proxy naplókba, az analitikai rendszerekbe, a böngésző előzményeibe és a technikai naplókba. A POST hátránya, hogy nehezebb kézzel ellenőrizni a címsoron keresztül, de ez nem ok arra, hogy a titkot az URL-be helyezze.

Aktív rendelések kötegelt lekérdezése

Ha az API támogatja a kötegelt ellenőrzést, küldjön több ID-t egyetlen kérésben:

curl -X POST "https:///orders/statuses" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_ids":["",""]}'

A választ a külső ID alapján párosítsa a belső rendeléshez, ne a tömb elemének pozíciója alapján. A kötegelt ellenőrzés hátránya: a szolgáltató nem feltétlenül ad vissza minden rendelést, korlátozhatja a lista méretét, vagy csak egy ID-ra jelezhet hibát.

Hogyan kell beütemezni a pollingot processing állapothoz

Az első processing válasz után tegye sorba a következő ellenőrzést. Az intervallumot az API dokumentációja, a gyakorisági korlátok és a szolgáltatás jellege alapján válassza. Azoknál a feladatoknál, ahol az állapot gyorsan változik, az elején elfogadható a sűrűbb ellenőrzés. A fokozatos promóciónál az állandó rövid kérések általában nem adnak új információt.

Gyakorlatias séma: az azonos processing válaszok után növelje a szünetet. Az első ellenőrzés a kezdeti késleltetés után történik, majd az intervallum a beállított maximumig nő. Ha az API előrehaladást vagy új frissítési időt ad vissza, a számítást ettől a változástól lehet indítani.

• A rendelés létrehozása után ne ellenőrizze az állapotot azonnal sokszor egymás után: a szolgáltatásnak időre lehet szüksége a sorba állításhoz.
• Ismétlődő processing esetén növelje a kérések közötti intervallumot, ne tartson állandó gyakoriságot.
• Adjon kis véletlen eltérést a feladatok indítási idejéhez, hogy a rendelések ne kérdezzék le az API-t egyszerre.
• Ha a szolgáltató Retry-After vagy hasonló javaslatot ad, azt elsőbbséggel használja.
• Webhookokkal rendelkező rendeléseknél tartson fenn kontroll-pollingot: az értesítés nem biztos, hogy megérkezik.

A ritka polling hátránya, hogy a felület a tényleges befejezés után régi állapotot mutathat. A túl gyakori polling hátránya, hogy az API-korlátokba ütközhet, 429-et kaphat, és felesleges terhelést okozhat.

Milyen időpontokat kell tárolni a processing ellenőrzéséhez

Ahhoz, hogy megkülönböztesse a normál végrehajtást az elakadástól, egyetlen aktuális állapot nem elegendő. Minden aktív rendelésnél tárolja a létrehozás idejét, a processing első megjelenését, az utolsó sikeres API-választ, a külső állapot utolsó változását és az előrehaladás utolsó változását.

Hasznos továbbá tárolni az eredeti mennyiséget, a visszaigazolt teljesített mennyiséget, a fennmaradó mennyiséget és a szolgáltató eredeti állapotát. Ha az API nem ad előrehaladást, ez nem ok arra, hogy a rendelést elakadtnak tekintse: támaszkodjon az utolsó válasz idejére és a várható feldolgozási időszakra, ha azt a szolgáltatás feltételei megadják.

A maximális várakozási időt nem lehet egyetlen számmal megadni minden szolgáltatásra. Használja azt a határidőt, amelyet a szolgáltató az adott szolgáltatásra megad, belső tartalékkal a sorra és az adatok frissítésére. Ha nincs megadva határidő, állítson be külön szabályt minden szolgáltatáskategóriára, és a tényleges feldolgozási előzmények alapján vizsgálja felül.

Mit kell tenni, ha a processing nem változik

A hosszú processing nem bizonyít hibát. Először ellenőrizze, érkeztek-e sikeres API-válaszok, változott-e a completed_quantity vagy a remains, voltak-e webhookok, és nem változtak-e a szolgáltatás szabályai. A látható növekedés hiánya összefügghet a platform statisztikájának késésével, vagy azzal, hogy a szolgáltató csak a végén frissíti az előrehaladást.

Amikor a belső várakozási határidő túllépésre kerül, ne mondja le a rendelést automatikusan. Végezzen soron kívüli állapotellenőrzést, kérjen adatokat külön metódussal, ha van ilyen, és ellenőrizze az értesítések előzményeit. Ha a szolgáltató továbbra is processing állapotot igazol, állítsa a rendelést belső „ellenőrzés szükséges” állapotba, de a külső állapotot helyettesítés nélkül őrizze meg.

• Rögzítse az utolsó visszaigazolt válasz idejét és a teljes API-választ.
• Ellenőrizze, változott-e az előrehaladás az előző lekérdezés óta.
• A belső küszöb elérése után csökkentse az automatikus kérések gyakoriságát.
• Adja át az ügyfélszolgálatnak a külső ID-t, a hivatkozást, a szolgáltatás paramétereit, az állapotelőzményeket és a technikai hibákat.
• Ne indítsa újra a fennmaradó mennyiséget a szolgáltató válasza vagy egyértelmű végleges állapot előtt.

A kézi ellenőrzés hátránya, hogy a rendelés az ügyfélszolgálat figyelmét igényli. De az automatikus lemondás vagy a duplikáció veszélyesebb: a teljesítés a szolgáltatónál tovább folytatódhat.

Hogyan kell megkülönböztetni a kérés hibáját a rendelés állapotától

A hálózati hiba, az időtúllépés, a HTTP 429 és az 5xx válasz nem a rendelés állapotáról tájékoztat. Ezek csak azt jelentik, hogy nem sikerült új, hiteles állapotot szerezni. Ilyen esetben tartsa meg az utolsó visszaigazolt állapotot, rögzítse a technikai hibát, és tervezzen új ellenőrzést.

429 esetén vegye figyelembe a Retry-After fejlécet, ha át van adva. Átmeneti hálózati hibák és 5xx esetén növelje a próbálkozások közötti szünetet. Engedélyezési, aláírási vagy hozzáférési hiba esetén ne indítson sűrű újrapróbálkozásokat: ellenőrizni kell a kulcsot, a token érvényességét, az IP-korlátozásokat és a hozzáférési beállításokat.

Ha az API HTTP 200-at adott vissza, de a JSON nem értelmezhető, vagy a válaszban nincs order_id és status, mentse el a válasz teljes törzsét, és jelölje az ellenőrzést hibásnak. Ne helyettesítse az állapot hiányát completed, canceled vagy processing értékkel.

Mikor kell leállítani az automatikus ismételt kéréseket

A polling nem lehet végtelen. Korlátozza a technikai újrapróbálkozások számát átmeneti hibák esetén, és külön ellenőrizze a rendelés processing állapotban töltött teljes időtartamát. Az újrapróbálkozási limit kimerülése után a ellenőrzési feladatot helyezze át a feldolgozási sorba, és ne hozzon létre új kéréseket percenként eredmény nélkül.

Az állapotkérés ismétlése általában biztonságos, ha a metódus csak adatot olvas. A létrehozás, lemondás, feltöltés, újraindítás és visszatérítés metódusait nem szabad időtúllépés után mechanikusan megismételni. Idempotens kulcs vagy a szolgáltató egyértelmű visszaigazolása nélkül az ilyen ismétlés kétszer módosíthatja a rendelést.

Az újrapróbálkozások korlátozásának hátránya, hogy bizonyos frissítések kézi feladattá válnak. A végtelen újrapróbálkozások rosszabbak: elfedik a hibát, felemésztik a limiteket, és megnehezítik a naplók elemzését.

Hogyan kell elfogadni a végleges állapotot a processing után

Akadályozza meg a visszalépést completed állapotból processing állapotba egy késői polling-válasz vagy egy régi webhook miatt. Minden frissítésnél hasonlítsa össze a szolgáltató eseményének idejét, a verzió sorszámát, ha van ilyen, és az aktuális belső állapotot.

• A new és a pending átléphet processing, canceled vagy failed állapotba.
• A processing átléphet completed, partial, canceled vagy failed állapotba.
• A partialt nem kell automatikusan completednek tekinteni.
• A completed, canceled és failed általában véglegesnek számít, és blokkolja az automatikus visszalépést.
• Az ismeretlen állapot vagy a nem megengedett átmenet külön ellenőrzést igényel.

A merev átmeneti táblázatnak is van hátránya: a szolgáltató hozzáadhat egy érvényes új állapotot. Ezért őrizze meg az eredeti állapotot, és ne írja felül a belső besorolással.

Hogyan kell kezelni a partialt és a rendelés fennmaradó mennyiségét

A partial azt jelenti, hogy az eredeti mennyiségnek csak egy részét igazolták. Az API-válaszban szerepelhet a ténylegesen teljesített mennyiség, a fennmaradó mennyiség, az ok és a kompenzációra vonatkozó adatok. Ezeket az értékeket külön tárolja: az eredeti rendelési mennyiséget nem lehet a teljesített mennyiséggel helyettesíteni.

Egy példa végleges válasz így nézhet ki:

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

"refund": "érték_vagy_a_mező_hiánya"

}

Először állapítsa meg, mit igazol pontosan az API: a visszatérítés már megtörtént, a visszatérítés csak tervezett, a fennmaradó mennyiséget lemondták, vagy ügyfélszolgálati megkeresés szükséges. Ha nincs visszatérítésre vonatkozó mező, ne tekintse a fennmaradó mennyiséget automatikusan kompenzáltnak.

Ne indítsa újra a nem teljesített részt külön döntés nélkül. A szolgáltató még végezheti az elszámolást, a platform statisztikája késéssel frissülhet, és az ismételt kérés duplikált promóciót hozhat létre. A visszaigazolásra várás hátránya, hogy a fennmaradó mennyiség nem zárul le azonnal, de nem jelenik meg felesleges rendelés.

A webhookok nem helyettesítik a kontroll-ellenőrzést

A webhook lehetővé teszi a rendelés kártyájának azonnali frissítését az esemény után, anélkül hogy a következő pollingra várna. A kezelőben keresse meg a rendelést a külső ID alapján, ellenőrizze az aláírást vagy a titkot, mentse el az esemény ID-ját, és csak az átmenet megengedettségének ellenőrzése után alkalmazza azt.

A webhook ismételt kézbesítésének biztonságosnak kell lennie: ugyanazt az eseményt nem lehet új változásként kezelni. Az események nem sorrendben is érkezhetnek, ezért ne állítsa vissza a végleges rendelést csak egy késői processing alapján.

Kontroll-pollingra akkor is szükség van, ha a webhookok stabilak. A webhookok hátránya a bonyolultabb beállítás: elérhető kezelőre, hamis kérések elleni védelemre, deduplikációra és eseménynaplóra van szükség.

Mit kell mutatni az ügyfélnek processing és elakadás esetén

A felületen nem kell kiírni a teljes technikai JSON-t. Processing esetén elegendő a „rendelés feldolgozás alatt” állapot. Ha az API hiteles előrehaladást adott át, a visszaigazolt mennyiséget az eredetitől külön mutassa, és ne tüntesse fel végleges eredményként.

Azon rendelésnél, amely túllépte a belső ellenőrzési határidőt, használjon érthető állapotot, például „a teljesítést ellenőrizzük”. Ne jelentsen lemondást, visszatérítést vagy teljes befejezést, amíg azt a szolgáltató válasza nem igazolja.

Az értesítések hasznosak a rendelés elfogadásakor, a végleges teljesítéskor, partial, lemondás, hiba és ellenőrzés szükségessége esetén. Az üzenetek minden polling után zajt keltenek, és nem segítenek az ügyfélnek megérteni a kérelem tényleges állapotát.

Milyen bejegyzések szükségesek a feldolgozási naplóban

A válaszok előzményei segítenek kivizsgálni az elakadt processinget, az elveszett webhookot, a részleges teljesítéssel kapcsolatos vitát és a felület és az API közötti eltérést. Minden hívásnál mentse el a külső ID-t, a frissítés forrását, a kérés és a válasz idejét, a HTTP-kódot, az eredeti állapotot, a normalizált állapotot, az előrehaladást, a fennmaradó mennyiséget és a technikai hiba szövegét.

Ne írjon a normál naplókba API-kulcsokat, tokeneket, aláírásokat és egyéb titkokat. Korlátozza a nyers válaszokhoz való hozzáférést: azok olyan adatokat tartalmazhatnak, amelyeknek nem szabad az ügyfélszolgálati felületen megjelenniük.

Indítás előtt ellenőrizze az ismétlődő processing, az előrehaladás hiánya, az időtúllépés, a 429, az 5xx hiba, a hibás JSON, a késői webhook, a duplicate-webhook, a partial, a canceled és az ismeretlen állapot forgatókönyveit. A tesztmód hasznos az integráció szerkezetéhez, de hátránya, hogy nem feltétlenül ismétli a valós sorokat és az éles API késéseit.