Kthimet dhe anulimet

Kthimet rimbursojnë pjesë të një shitjeje nga bilancet e mbetura; anulimet e përmbysin atë të plotë. Cilin ta zgjedhësh dhe kur.

Ka dy mënyra për të përmbysur një shitje, dhe zgjedhja nuk është çështje preference.

	Kthim (`return`)	Anulim (`cancellation`)
Fushëveprimi	I plotë ose i pjesshëm	Gjithmonë i plotë
Dërgon rreshta?	Po	Jo
Mund të përsëritet?	Po, derisa bilanci shterret	Jo
I bllokuar nëse ka kthime të mëparshme	Jo	Po

Rregull i thjeshtë

Nëse shitja është ende e paprekur dhe duhet përmbysur e gjitha, përdor anulim. Në çdo rast tjetër, përdor kthim.

Të dyja krijohen si veprime mbi shitjen që përmbysin, prandaj shitja identifikohet nga rruga dhe jo nga një fushë në trup. Të dyja kërkojnë Idempotency-Key.

POST /v1/pos/{pos_id}/sales/{sale_id}/return
POST /v1/pos/{pos_id}/sales/{sale_id}/cancel

sale_id është ID-ja e vetë komandës së shitjes — id që u kthye kur u krijua shitja.

Përmbysjet nuk kanë koleksione të vetat

/v1/pos/{pos_id}/sales vetëm lëshon shitje. Për t'i lexuar përmbysjet, listo /v1/pos/{pos_id}/commands me kind=RETURN ose kind=CANCELLATION.

Anulimi

POST /v1/pos/{pos_id}/sales/{sale_id}/cancel nuk mban rreshta, pagesa apo totale. Fiskaliza kopjon rreshtat, pagesat, grupet e taksave, monedhën dhe totalet e shitjes së emërtuar në rrugë për të ndërtuar përmbysjen ekzakte.

cancel.sh

curl -X POST "$BASE_URL/v1/pos/$POS_ID/sales/$SALE_ID/cancel" \
  -H "Authorization: Bearer $FISKALIZA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cancel-order_123" \
  -d '{
    "external_id": "cancel_123",
    "reason": "Entered by mistake",
    "occurred_at": "2026-08-25T11:00:00+02:00"
  }'

Kur anulimi nuk lejohet

Një shitje që është tashmë e anuluar, ose që është kthyer pjesërisht, nuk mund të anulohet. Përmbys atë që ka mbetur me një kthim.

Kthimi

POST /v1/pos/{pos_id}/sales/{sale_id}/return merr rreshta që referojnë shitjen e emërtuar në rrugë.

return.sh

curl -X POST "$BASE_URL/v1/pos/$POS_ID/sales/$SALE_ID/return" \
  -H "Authorization: Bearer $FISKALIZA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: return-order_123-a" \
  -d '{
    "external_id": "return_123",
    "reason": "Customer return",
    "occurred_at": "2026-08-26T10:00:00+02:00",
    "items": [ { "original_line_id": "line_1" } ],
    "payments": [ { "type": "CASH" } ]
  }'

Fiskaliza e merr emrin e produktit, njësinë, tipin, çmimin njësi, monedhën dhe kategorinë tatimore nga shitja e lëshuar. Ti dërgon vetëm se çfarë kthehet.

Rreshtat

Çdo element kërkon vetëm original_line_id — line_id-në e rreshtit në shitjen origjinale.

Fusha	Nëse e lë jashtë	Nëse e vendos
`quantity`	kthehet e gjithë sasia e mbetur e atij rreshti	kthehet kjo sasi e pjesshme pozitive
`discount_cents`	zbritja origjinale e mbetur ndahet proporcionalisht	vlera mbivendoset

discount_cents: 0 nuk është e njëjtë me mungesën

Lënia jashtë kërkon shpërndarje proporcionale; 0 thotë shprehimisht "asnjë zbritje për këtë rresht". Të dyja janë të vlefshme dhe japin rezultate të ndryshme.

Vlera e dhënë duhet të hyjë brenda subtotalit, zbritjes dhe totalit të rimbursueshëm të mbetur. Nëse kthen të gjithë sasinë e mbetur, duhet shterur edhe e gjithë zbritja e mbetur.

Një rresht origjine vetëm një herë për kthim

I njëjti original_line_id nuk mund të shfaqet dy herë në të njëjtin kthim. Bashkoji në një element të vetëm.

`items` është i detyrueshëm

{ "items": [ { "original_line_id": "line_1" } ] }

Lënia jashtë e items nuk kthen të gjithë kuponin — kërkesa refuzohet. Për të përmbysur gjithçka, ose listo çdo rresht, ose përdor një anulim.

Kthim i pjesshëm

{
  "external_id": "return_partial",
  "reason": "Partial return",
  "occurred_at": "2026-08-26T10:00:00+02:00",
  "items": [ { "original_line_id": "beans", "quantity": 0.1, "discount_cents": 0 } ],
  "payments": [ { "type": "CREDIT_CARD" } ]
}

Si alokohen shumat

Shumat alokohen nën një bllokim të shitjes origjinale, duke marrë parasysh të gjitha përmbysjet e mëparshme jo-të-refuzuara — përfshirë komandat në gjendjen PENDING dhe RETRY.

Taksa nuk rillogaritet për çdo rimbursim të pjesshëm; ajo alokohet nga bilancet e mbetura të kategorisë. Kthimi përfundimtar konsumon shumat e mbetura ekzakte dhe qindarkat e rrumbullakimit, kështu që seria mbyllet gjithmonë saktësisht. Shih Taksat dhe rrumbullakimi.

Pagesat

Mënyra e pagesës është e shprehur dhe mund të ndryshojë nga shitja origjinale — një blerje me kartë mund të rimbursohet në para në dorë.

Rregullat janë të njëjta si te shitjet: një pagesë e vetme mund ta lërë jashtë amount_cents; pagesat e ndara kërkojnë shuma të shprehura.

Shitja duhet të jetë e dukshme dhe e lëshuar

sale_id në rrugë duhet të emërtojë një shitje të lëshuar që ky çelës e sheh. Shitjet që mungojnë, që janë të huaja, që nuk janë të mapuara ose që nuk janë të lëshuara kthejnë të gjitha 404 resource_not_found — pa dallim.

POS-i që përmbys nuk është medoemos POS-i që shiti

pos_id është POS-i që lëshon kthimin ose anulimin. Nuk është e thënë të jetë POS-i që lëshoi shitjen origjinale, kështu që klienti mund të kthejë një artikull në një arkë tjetër.

Përgjigjet

Kodi	`errors`	Kuptimi
`201`	—	Kthimi ose anulimi u krijua
`400`	`invalid_request`	Origjinal i anuluar, bilanc i shterur ose rimbursim i tepërt
`403`	`insufficient_capability`	Çelësit i mungon `fiskaliza:commands:write`
`404`	`resource_not_found`	Origjinali mungon ose nuk është i dukshëm
`409`	`idempotency_conflict`	Qëllim i ndryshuar nën të njëjtin çelës
`502`	`fiscalization_unavailable`	Shërbimi i fiskalizimit nuk u përgjigj

Në këtë faqe