IOSOR

IOSOR Tieto

Lähetys-API:n idempotenssi: kaksoiskappaleet, uudelleenyritykset ja raha

Kehittäjäopas prepaid-lähetys-API:ille — idempotenssiavaimet, turvalliset uudelleenyritykset, kaksoiskappaleiden esto ja ledger-ystävällinen korrelaatio, jotta engineering-virheet eivät muutu taloushäiriöiksi.

Aikakatkaisut tapahtuvat. Kuormantasaajat yrittävät uudelleen. Mobiiliasiakkaat kaksoisnapauttavat. Ilman idempotenssia "lähetä kerran" -tuotteesta tulee kaksinkertainen prepaid-veloitus ja päällekkäinen OTP-UX. Opas on engineeringille ja tekniselle productille, jotka integroivat white-label prepaid-viestintä-API:n — jossa jokainen kaksoiskappale näkyy lompakossa.

IOSOR odottaa money-aware-integraatioita: autentikoituja kutsuja, korreloitavia veloituksia ja asiakasvirheitä, jotka eivät koskaan dumppaa vieraita brändipayloadeja. Lähellä USD 1 000+ kuukausittaista alustakäyttöä kaksoiskappaledisipliini ei ole enää valinnainen.

Miksi kaksoiskappaleista tulee rahaongelmia

Vikamuoto Käyttäjä näkee Lompakko näkee
Asiakkaan aikakatkaisu + sokea uudelleenyritys Kaksi OTP:tä / kaksi hälytystä Kaksi veloitusta
Ei-idempotenssi webhook-käsittelijä Kaksois sivuvaikutukset Hämmennys onnistumisessa
Käyttäjän uudelleenlähetys auto-retryn päällä Ärsyyntyneet käyttäjät Kertyneet yksiköt
Puuttuva korrelaatio "Epäonnistui"-tiketit Sovittamattomat ledger-rivit

Idempotenssiavaimet jotka kestävät uudelleenyritykset

Vakava lähetyspolku hyväksyy asiakkaan luoman avaimen, joka on yksilöllinen liiketoimintaintentiota kohden. Se palauttaa saman accepted-tuloksen toistossa selkeässä TTL-ikkunassa. Se ei hiljaa luo toista veloitusta samalle intensiolle. Se lokitetaan viesti-ID:n ja prepaid-viitteen viereen. Se toimii aikakatkaisujen, yhdyskäytävän uudelleenyritysten ja tukiredrivejen yli.

Uudelleenyritysbudjetit vs käyttäjän uudelleenlähetys

Automaattiset uudelleenyritykset tarvitsevat budjetin: maksimiyritykset, backoff ja mitkä virheluokat ovat uudelleenyrityskelpoisia. Käyttäjän aloittama uudelleenlähetys on toinen tuotetoiminto omine rajoineen ja prepaid-kuluineen. Niiden sekoittaminen muuttaa epävakaan verkon viikonloppuongelmaksi.

Ostajan / engineeringin tarkistuslista

  1. Dokumentoitu idempotenssiavaimen semantiikka ja TTL.
  2. Replay-testi, joka todistaa yhden veloituksen yhdelle intensiolle.
  3. Erillinen auto-retry-budjetti käyttäjän uudelleenlähetyslogiikasta.
  4. Korrelaatio-ID:t pyynnön, viestin tilan ja prepaid-ledgerin välillä.
  5. Staging, joka harjoittelee todellisia käytäviä — mallinnetut vihreät valot eivät ole julkaisuja.
  6. Avainhygienia ja vähimmäisoikeudet lähetystunnuksille.
  7. 429- ja 503-koodien käsittely ilman alkuperäisen intent-avaimen menetystä.
  8. Automaattiset hälytykset korkeille duplicate-key -hylkäysasteille.

Punaiset liput

  • "Yritä vain uudelleen 200:aan asti" ilman idempotenssiavaimia.
  • Webhook-käsittelijät, jotka eivät ole idempotensseja ja laukaisevat sivuvaikutukset kahdesti.
  • Täydet salaiset avaimet tai auth-tokenit lokeissa tai tukitikeissä.
  • Virheet, jotka liittävät ulkoisia brändipayloadeja tai sisäisiä stack-traceja loppukäyttäjille.
  • Ei strategiaa matalan saldon hallintaan uudelleenyritysten aikana.

Aloita IOSOR:lla

Lähetyskonsolissa ammu yksi OTP tai hälytys asiakkaan luomalla idempotenssiavaimella. Pakota asiakkaan aikakatkaisu ja toista sama pyyntö avaimen TTL:n sisällä. Avaa prepaid-ledger: tuolla aikomuksella on oltava yksi veloitus ja yksi näkyvä viesti. Kaksi riviä tarkoittaa, ettei avain selvinnyt uudelleenyrityksestä — korjaa TTL ja käsittelijä ennen kuin käytävä jää Live-tilaan.

IOSOR-yhteenveto

Tee: käsittele jokainen lähetys ensin ledger-tapahtumana. Avain on yksilöllinen liiketoiminta-aikeelle, ei TCP-yritykselle. Automaattisella uudelleenyrityksellä on budjetti; käyttäjän uudelleenlähetys on toinen tuote-toimi omalla prepaid-hinnallaan.

Oliko tästä oppaasta apua?

Aiheeseen liittyvät oppaat