Ágens ERP-integrációs hibákhoz: taxonómia, runbookok és biztonságos újrapróbálás

Az ERP-integrációs hibakezelés a webshop, a PIM és az ERP összekötésének üzemeltetési oldala: a hibás üzenetek olvasása, döntés az újrapróbálás és a javítás között, annak kiderítése, melyik rendszer felel a javításért, és melyik rendelések érintettek. Egy ágens az olvasás és rendezés nagy részét leveheti az integrációs csapat válláról, feltéve, hogy valódi hibataxonómia szerint osztályoz, csak biztonságos runbook-műveletek rövid listáján keresztül cselekszik, és az üzleti adatok minden módosítását embereknek hagyja.

Ez a cikk sorra veszi, mi romlik el a webshop, a PIM és az ERP között, az SAP hibaszerződéseiből épített taxonómiát, az ágens osztályozó körét, a biztonságos újrapróbálást és a runbookokat, a sorok és dead letter sorok működését, a védőkorlátokat, az üzleti indoklást, és hogy mikor jobb válasz egy szabálymotor. Magának a szinkronizációnak a tervezését a Pimcore ERP delta szinkron című cikk írja le.

Mi romlik el a webshop, a PIM és az ERP között?

Öt hibacsalád fedi le az incidensek többségét: leképezési és validációs hibák, hiányzó vagy zárolt törzsadatok, ár- és ügyfélállapot-tiltások, elérhetőségi és allokációs ütközések, valamint hitelesítési, időtúllépési és infrastrukturális hibák. Minden osztályozás három kérdésre felel: újrapróbálás vagy javítás, melyik rendszer felel a javításért, és hány rendelés érintett.

Az újrapróbálás és a javítás közötti különbség a legfontosabb. Csak az utolsó család javul az idővel; egy hiányzó anyag vagy egy zárolt ügyfél minden újrapróbálásnál ugyanúgy bukik el, és az az integráció, amely ezeket a végtelenségig ismétli, egyetlen adatproblémából több száz zajos riasztást csinál. A Spryker és Pimcore alapú B2B kereskedelmi rendszereken végzett munkám során azt láttam, hogy egy projekt után a csapatok nem az integrációs kódot tartják meg, hanem a runbook-könyvtárat és a hibairányítópultot, ezért ezekre tervezzen kezdettől.

Hogyan épül fel egy integrációs hibataxonómia?

Azokból a hibaszerződésekből építse, amelyeket a rendszerei már kibocsátanak, ne kitalált címkékből. Az SAP kettő jót is ad: az IDoc-állapotrekordokat és az OData-hibaobjektumokat.

• IDoc-állapotrekordok. Az SAP állapotlistája szerint, az SAP Communityben ellenőrizve, az 51 jelentése „az alkalmazásbizonylat nincs könyvelve”, az 53-é „az alkalmazásbizonylat könyvelve”, a 64-é „az IDoc kész az alkalmazásnak való átadásra”, a 66-é „az IDoc az előző IDocra vár”, a 68-é pedig „hiba, további feldolgozás nincs”. Az SAP ALE-dokumentációja szerint egy hibás IDoc bejövő feldolgozása leáll, munkafolyamat-tétel keletkezik, és a javítás után az IDocot újra beküldik; az RBDMANI2 riport újra feldolgozza az 51-es és 63-as állapotú IDocokat, és ütemezhető, hogy összegyűjtse a zárolás miatt elbukottakat (SAP Library).
• OData-hibaobjektumok. Egy OData V4 hibaválasz egy JSON error objektum nyelvfüggetlen code mezővel, üzenettel, a hibás tulajdonságra mutató opcionális target mezővel és egy details tömbbel. Az SAP CAP numerikus súlyosságot ad hozzá, és világos határt húz: egy ServiceException megszakít és visszagörget, a Messages API-val hozzáadott üzenetek viszont nem állítják meg a feldolgozást (SAP CAP). Egy targettel ellátott figyelmeztetés jelentés, nem újrapróbálási jelölt.

Hogyan működik az ágens osztályozó köre?

Minden jelet egy rekordra normalizáljon, előbb szabályokkal osztályozzon, a taxonómia alapján döntsön, egy engedélyezett listán belül cselekedjen, rögzítse, mi történt, és ujjlenyomat alapján deduplikáljon. Az LLM az osztályozó egyik eleme, csak olyan strukturálatlan futásidejű szövegre, amelyre egyetlen szabály sem illik.

// One record shape for every signal (sketch)
type IntegrationError = {
  source: 'idoc' | 'cpi' | 'odata' | 'queue' | 'shop'
  interface: string      // e.g. "ORDERS inbound", "stock sync"
  entityKey: string      // order number, material, customer
  code: string           // IDoc status + message class/number, OData error code, DLQ reason
  target?: string        // OData target path or IDoc segment/field
  text: string           // runtime message text: untrusted input for any LLM step
  retryCount: number
}

// Same class, same runbook: fingerprint without volatile values
const fingerprint = (e: IntegrationError) =>
  sha256([e.source, e.interface, e.code, e.target ?? '', stripVolatile(e.text)].join('|'))
// stripVolatile removes ids, numbers and timestamps, so
// "material 4711 not found" and "material 4712 not found" share one fingerprint

Az ujjlenyomat teszi az áradatból listát. Kétszáz hibás rendelési IDoc ugyanazzal a hiányzó anyaggal egyetlen incidens lesz számlálóval és az érintett rendelések listájával, egyetlen jegyhez kötve. A futásidejű szöveget kezelje megbízhatatlan bemenetként: ügyfél által megadott szöveget is tartalmazhat, ezért az LLM-lépés csak osztályoz és összefoglal, és soha nem dönt a taxonómián kívüli műveletről. A saját jev-decide skillem ugyanilyen formájú, típusos döntés bizalmi szinttel, ahol az alacsony bizalom emberhez kerül, és az osztályozónak pontosan ezt kell visszaadnia: hibaosztály, újrapróbálható-e, gazda, bizalom.

Mikor biztonságos az újrapróbálás, és mi kerül egy runbookba?

Az újrapróbálás akkor biztonságos, ha a hiba átmeneti és a művelet idempotens, és csak akkor marad biztonságos, ha a próbálkozások száma korlátozott és időben elosztott. Minden más karantén plusz jegy. A runbook hibaosztályonként megnevezett műveletek rövid listája: automatikus újrapróbálás, karantén felelőssel, értesítés, jegy kontextussal, vagy leképezési változtatás javaslata.

Az idempotencia a fogadó oldal szerződése. A Stripe API a tiszta referencia: egy idempotenciakulccsal a hívó megismételheti a kérést anélkül, hogy a művelet kétszer lefutna, és ha a kulcsot más paraméterekkel használja újra, hibát kap (Stripe). Minden hívásnak, amely vevői rendelést, szállítást vagy számlát hoz létre, ugyanilyen szerződés kell, mielőtt egy ágens újrapróbálhatná; a duplikált vevői rendelés az a hiba, amely valódi pénzbe kerül, ezért teszi az e-mailes rendelésrögzítés automatizálása a kulcsot a létrehozó hívásra. A visszalépés önmagában sem elég: az AWS 100 versengő klienssel végzett szimulációjában a korlátozott exponenciális visszalépéshez adott teljes jitter több mint felére csökkentette a hívások számát (AWS).

// Capped exponential backoff with full jitter, for idempotent operations only
function retryDelayMs(attempt: number, baseMs = 1_000, capMs = 60_000): number {
  const ceiling = Math.min(capMs, baseMs * 2 ** attempt)
  return Math.random() * ceiling
}

const MAX_ATTEMPTS = 5   // bounded: after that, quarantine and open a ticket

A runbook-könyvtár egyben a visszacsatolási kör is. Ha ugyanaz az ujjlenyomat újra és újra karanténba kerül, az ágens jegyben leképezési javítást javasol az adatgazdának, a számlálóval, az érintett rendelésekkel és egy minta-payloaddal. Így tűnnek el a visszatérő osztályok, ahelyett hogy örökké kezelni kellene őket. Az LLM API-hívások újrapróbálása hasonló szabályokat követ, de más hibamóddal, ezt az LLM rate limitek, újrapróbálás és szolgáltatói tartalék című cikk tárgyalja.

Milyen sor- és dead letter mechanikát érdemes ismerni?

Tudja pontosan, mi kerül az egyes dead letter sorokba, mert a szabályok platformonként eltérnek, és egy ágens, amely rosszat feltételez, hibákat hagy figyelmen kívül. Három példa lefedi a legtöbb rendszert.

• SAP Cloud Integration JMS-sorok: a nem kizárólagos JMS-soroknál, ahogy az SAP 2017-ben dokumentálta, az újrapróbálási időköz alapértéke egy perc, az exponenciális visszalépés minden hiba után megduplázza, és legalább 60 perces maximális időköz ajánlott (SAP Community). Az ottani dead letter sor szűk: azokat az üzeneteket tartja, amelyek egy csomópont összeomlása miatt nem dolgozhatók fel, kétszer újrapróbálva, majd kézi beavatkozásra félretéve; a feldolgozási hiba miatt elbukó üzenetek nem kerülnek oda (SAP Community). Az újabb kizárólagos sorok másként viselkednek, ezért ellenőrizze, melyik típust használja egy interfész.
• Amazon SQS: a maxReceiveCount értékkel beállított redrive szabály dead letter sorba helyezi az üzeneteket, amelyek lejárata az eredeti sorba állítás idejéhez igazodik, ezért a megőrzési idejének hosszabbnak kell lennie a forrássorénál (AWS).
• Azure Service Bus: a dead letter üzenetek DeadLetterReason és DeadLetterDescription mezőt hordoznak, például MaxDeliveryCountExceeded értéket az alapértelmezett 10 kézbesítés után, és a Microsoft azt javasolja, hogy a kivétel típusa és a veremkivonat ezekbe a mezőkbe kerüljön (Microsoft Learn). Ez ingyenes bemenet az osztályozónak.

A tartós végrehajtást biztosító motorok alapértelmezésként ugyanezeket a szabályokat kódolják. A Temporal exponenciális visszalépéssel próbálja újra a tevékenységeket, 2,0-s szorzóval az egymásodperces kezdőidőköztől 100 másodpercig, a nulla maximális próbálkozást korlátlannak tekinti, és dokumentációja a hibás bemeneti adatot nevezi meg a nem újrapróbálható hiba észszerű esetének (Temporal). Ha a rendelési folyamatai ezen futnak, az ágens a hibáikat bármely más jelhez hasonlóan olvassa; magát a platformot a Temporal című cikk értékeli.

Milyen védőkorlátok kellenek egy osztályozó ágensnek?

Alapértelmezésben csak olvasás, műveletek csak engedélyezett listáról, próbafuttatási mód, műveletosztályonkénti jóváhagyási kapuk és teljes audit nyomvonal. Az OWASP LLM-alkalmazásokra vonatkozó Top 10 listája 2025-ös kiadásában LLM06 néven tartja nyilván a túlzott cselekvési jogkört, vagyis azt, ha egy LLM-vezérelt rendszer több funkciót, jogosultságot vagy önállóságot kap, mint amire a feladatához szüksége van (OWASP GenAI).

Egy jó jegy a haszon fele. Tartalmazza az interfészt, az IDoc-számot vagy üzenetazonosítót, az üzenetosztályt és -számot, az entitáskulcsot, az ujjlenyomat számlálóját, az érintett rendeléseket és a runbook linkjét. Ilyen jegyeket naponta nyitok egy 20 eszközös Jira MCP szerveren keresztül, és a kontextussal ellátott és a kontextus nélküli jegy közötti különbség elemzői percekben mérhető.

Mennyit ér egy integrációs hibaosztályozó ágens?

Annyit ér, amennyi integrációs időt felszabadít, és amennyi hibás rendelést láthatóvá tesz, mielőtt az ügyfelek észrevennék. Az osztályozás automatizálásával megtakarított elemzői órákra vagy egy hibás B2B rendelés költségére nincs publikált szám, ezért az indoklás kontextusszámokra és a saját alapértékére épül.

• Integrációs terhelés: a MuleSoft 2026-os Connectivity Benchmarkja, amely 1050 IT-vezetőt kérdezett meg 2025 októbere és novembere között, szerint az IT-csapatok idejük 36%-át egyedi integrációk tervezésével, építésével és tesztelésével töltik, egy átlagos szervezet 957 alkalmazást futtat, ebből 27% összekötött, és az IT-projektek 26%-a lekéste a határidőt (MuleSoft).
• A rendelési hibák elvándorlást okoznak: a Sana Commerce 2024 szeptemberi, 750 B2B vásárlót megkérdező tanulmányában 33% számolt be a webshop pontatlan adatai miatti rendelési hibákról, és 75% fontolóra venné a beszállítóváltást egy jobb élményért (Procurement Magazine; szállítói felmérés).

Egy e-kereskedelmi üzemeltetési vagy ERP-integrációs vezető a pilot előtt négy alapértéket rögzítsen: interfészenkénti heti hibás üzenetek, hibaosztályonkénti megoldási idő, az ember nélkül megoldott esetek aránya, és hibás rendelésenkénti kézi beavatkozások. Utána számolja meg a leképezési javításokkal megszűnő visszatérő osztályokat; ezt a számot egy operatív igazgató is érti.

Mikor ne építsen ehhez ágenst?

Ne építsen ilyet, ha kevés az üzenet, ha minden jel már strukturált, ha nincs olvasható megfigyelhetőség, vagy ha a valódi probléma egy megoldatlan tervezési hiba korábbi ponton. Ilyenkor egy szabálymotor riasztással nyer, az LLM pedig költséget és új hibamódot hoz, többletjelet nem.

Egyoldalas megvalósítási ellenőrzőlista

1. Válasszon a pilothoz egy interfészt és egy hibaosztályt, például a bejövő rendelési IDocokat.
2. A taxonómiát valódi állapotkódokból és hibaobjektumokból írja meg, osztályonként felelőssel.
3. Minden jelet egy rekordformára normalizáljon, és változó értékek nélkül képezzen ujjlenyomatot.
4. Előbb szabályokkal osztályozzon; csak az illeszkedés nélküli szabad szöveget küldje az LLM-nek, bizalmi küszöbbel.
5. Engedélyezett listán rögzítse a műveleteket, próbafuttatással induljon, és műveletosztályonként kérjen jóváhagyást.
6. Csak idempotens hívásokat próbáljon újra, korlátozottan, visszalépéssel és jitterrel.
7. Naplózzon minden döntést és műveletet az ujjlenyomattal, a szabály- vagy modellverzióval és az eredménnyel.
8. Rögzítse a négy mérőszám alapértékét, és havonta tekintse át a visszatérő osztályokat az adatgazdákkal.

Egy interfészre szűkített, rögzített hatókörű osztályozó pilot írott taxonómiával, runbook-könyvtárral, deduplikációs riportokkal és a saját naplóiból készült előtte-utána összevetéssel jól körülhatárolt projekt. Ha segítség kell a tervezéshez, nézze meg a B2B e-kereskedelmi munkámat.

Források

1. SAP Library: IDoc interface and ALE exception handling
2. SAP Community: IDoc status codes
3. SAP CAP: indicating errors (Java)
4. SAP Community: Cloud Integration asynchronous messaging with retry using JMS (2017)
5. SAP Community: Cloud Integration dead-letter handling in the JMS adapter (2017)
6. Temporal: retry policies
7. Amazon SQS: dead-letter queues
8. Azure Service Bus: dead-letter queues
9. Stripe API reference: idempotent requests
10. AWS Architecture Blog: Exponential backoff and jitter
11. MuleSoft: 2026 Connectivity Benchmark Report
12. OWASP GenAI Security Project: LLM06:2025 Excessive Agency