Idempotenca
Header-i Idempotency-Key është i detyrueshëm për çdo operacion që krijon diçka. Si ndryshon nga external_id dhe si trajtohen konfliktet.
Fiskalizimi nuk fal dyfishime: një shitje e dërguar dy herë është një shitje e
dyfishtë e regjistruar te ATK. Prandaj çdo rrugë që krijon diçka të
pandryshueshme e kërkon header-in Idempotency-Key.
Ku kërkohet
| Operacioni | Rruga |
|---|---|
| Regjistro POS | POST /v1/pos |
| Lësho shitje | POST /v1/pos/{pos_id}/sales |
| Lësho kthim | POST /v1/pos/{pos_id}/sales/{sale_id}/return |
| Lësho anulim | POST /v1/pos/{pos_id}/sales/{sale_id}/cancel |
| Lësho kopje kuponi | POST /v1/commands/{command_id}/receipt-documents?locale=… |
Ritentimi i një komande
(POST /v1/commands/{command_id}/retry)
nuk merr çelës idempotence: komanda ekziston tashmë.
Idempotency-Key kundrejt external_id
Të dyja janë string-je që i zgjedh ti, dhe krijimi i një komande përdor të dyja për të shmangur dyfishimet.
Idempotency-Key | external_id | |
|---|---|---|
| Ku shkon | Header | Trupi i kërkesës |
| Çfarë është | Mbrojtje ripërsëritjeje për një kërkesë | Referenca jote për transaksionin |
| Fushëveprimi | Biznesi, ose POS-i për komandat | POS-i |
| I detyrueshëm? | Po | Po, për komandat |
external_id është mbrojtja më e fortë te komandat
Te krijimi i komandave, një kërkesë që përputhet ripërsërit komandën
ekzistuese edhe me një Idempotency-Key tjetër. Pra ripërdorimi i një
reference transaksioni nuk krijon në heshtje një shitje të dytë.
Përdori për atë që janë: Idempotency-Key e bën një thirrje HTTP të sigurt për
ripërsëritje, kurse external_id e lidh komandën me porosinë në sistemin tënd.
Fushëveprimi
Çelësi i idempotencës nuk është global. Ai është i kufizuar sipas:
| Operacioni | Fushëveprimi |
|---|---|
| Regjistrimi i POS-it | Biznesi |
| Dokumentet e kuponit | Biznesi |
| Komandat | POS-i |
Krijimi i komandave deduplikon gjithashtu mbi external_id brenda atij POS-i.
Si lexohet përgjigja
201 Created— kërkesa u përpunua për herë të parë.200 OK— ripërsëritje idempotente e një trupi identik; po të kthehet i njëjti burim, asgjë e re nuk u krijua.409 Conflict— shih më poshtë.
Trajtoji 200 dhe 201 si sukses të barasvlershëm.
Dy lloje konfliktesh
Të dyja kthejnë 409, por kuptimi ndryshon:
errors | Kuptimi | Veprimi |
|---|---|---|
idempotency_conflict | I njëjti çelës u ripërdor me trup të ndryshëm | Defekt në kodin tënd |
request_in_progress | Një kërkesë me këtë çelës është në përpunim tani | Prit dhe ritento pas pak |
request_in_progress është i përkohshëm
Ai do të thotë se dy thirrje me të njëjtin çelës u nisën njëkohësisht dhe njëra mban ende lease-in. Ritentimi pas një pauze të shkurtër është i sigurt dhe do të kthejë rezultatin e së parës. Te regjistrimi i POS-it ky lease zgjat dy minuta.
Zgjedhja e çelësit
Çelësi duhet të rrjedhë nga ngjarja e biznesit, jo nga tentativa e kërkesës.
# Mirë: i qëndrueshëm përgjatë ritentimeve
-H "Idempotency-Key: sale-order_123"
# Keq: ndryshon në çdo ritentim, humb çdo mbrojtje
-H "Idempotency-Key: $(uuidgen)"Ruaje çelësin në bazën tënde të të dhënave në të njëjtin transaksion që krijon porosinë — jo në momentin e dërgimit.
Normalizimi i inputit
Fiskaliza krahason inputin e normalizuar, jo bajtat e papërpunuar. Për një
shitje, përsëritja e të njëjtit input të normalizuar ripërdor komandën;
ndryshimi i tij jep idempotency_conflict.
Te kopjet e kuponit
Çelësi ka fushëveprim biznesi dhe përfshin gjuhën. Ripërsëritja me të njëjtin
locale kthen të njëjtën kopje; ripërsëritja me një tjetër jep
idempotency_conflict. Përdor një çelës për çdo gjuhë që do të rendërosh.
Te kthimet
Kthimet kanë një sjellje shtesë që vlen të kuptohet: idempotenca lidh qëllimin e normalizuar përpara se të lexohen sasitë e mbetura.
Praktikisht, ritentimi i një kthimi "të gjithë sasinë e mbetur" ripërsërit komandën e tij — nuk gjeneron kurrë një rimbursim të dytë, edhe nëse ndërkohë bilanci ka ndryshuar.
Modeli i rekomanduar
Gjenero çelësin bashkë me ngjarjen
Në të njëjtin transaksion që krijon porosinë.
Ritento gabimet e rrjetit me çelësin e njëjtë
Timeout-e, 5xx dhe 502 fiscalization_unavailable janë të sigurta për
ridërgim me të njëjtin çelës.
Trajto idempotency_conflict si defekt
Regjistroje dhe hetoje. Mos e "zgjidh" duke gjeneruar automatikisht një çelës të ri — kjo krijon pikërisht dyfishimin që po parandalonim.