Fiskaliza
Referenca e API-sëKomandat

Return part or all of a sale

The sale being reversed is the path's `sale_id`, not a body field. Lines reference it by `original_line_id`; Fiskaliza takes the product name, unit, type, unit price, currency, and tax category from the issued sale. It must be an issued sale this key can see — anything else is a 404. `pos_id` is the POS that issues the return, and need not be the POS that issued the sale. The fiscal return coupon is issued immediately in the requested locale and returned as receipt_document.

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

The sale being reversed is the path's sale_id, not a body field. Lines reference it by original_line_id; Fiskaliza takes the product name, unit, type, unit price, currency, and tax category from the issued sale. It must be an issued sale this key can see — anything else is a 404. pos_id is the POS that issues the return, and need not be the POS that issued the sale. The fiscal return coupon is issued immediately in the requested locale and returned as receipt_document.

Authorization

fiskalizaKey fiskaliza:commands:write
AuthorizationBearer <token>

An opaque Fiskaliza API key. Each operation lists the capabilities required on that key.

In: header

Scope: fiskaliza:commands:write

Path Parameters

pos_id*string
Match^nj_pos_
sale_id*string

The issued sale command being reversed.

Length1 <= length

Query Parameters

locale?unknown

Language of the server-rendered coupon. Defaults to Albanian.

Default"sq"

Value in

  • "sq"
  • "sr-Latn"
  • "en"

Header Parameters

Idempotency-Key*string

Reuse with the same request to replay the result. Changed input returns idempotency_conflict. Scoped to the business for POS onboarding and receipt documents, and to the POS for commands. Command creation also deduplicates by external_id within that POS; a matching request replays the existing command even with a different idempotency key.

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The original sale is the path's sale_id and must be an issued sale visible to this key; inaccessible, missing, foreign and non-issued originals all return resource_not_found. Items are required; omission does not return the entire receipt. Tax is allocated from remaining original category balances, not calculated afresh for each partial refund. Payment method is explicit and may differ from the original sale. Cancelled originals, exhausted balances and over-refunds are rejected with invalid_request. Idempotency binds normalized intent before remaining quantities are read: retrying an all-remaining return replays its command, never another refund. Changed intent under the same idempotency key returns idempotency_conflict.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/pos/string/sales/string/return" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -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"      }    ]  }'
{  "success": true,  "warnings": [    "string"  ],  "data": {    "command": {      "id": "string",      "pos_id": "string",      "external_id": "string",      "type": "SALE",      "sale_type": "STANDARD",      "status": "PENDING",      "issuance_mode": "ONLINE",      "attempt_count": 0,      "last_error": "string",      "next_retry_at": "2019-08-24T14:15:22Z",      "receipt_ready": true,      "created_at": "2019-08-24T14:15:22Z",      "coupon": {        "coupon_id": 0,        "daily_receipt_no": 0,        "reference_no": 0,        "verification_no": "string",        "qr_payload": "string",        "transaction_no": "string",        "atk_message": "string",        "issued_at": "2019-08-24T14:15:22Z",        "transmitted_at": "2019-08-24T14:15:22Z"      }    },    "receipt_document": {      "id": "string",      "command_id": "string",      "locale": "sq",      "kind": "ORIGINAL",      "pdf_url": "/v1/receipt-documents/{id}/pdf",      "pdf_sha256": "string",      "issued_at": "2019-08-24T14:15:22Z"    }  }}

Issue a sale POST

The route determines the command type; a request may not send `type` or the canonical `kind`. The fiscal coupon is issued immediately and its ORIGINAL PDF document is returned with the command. A rejected command has a null receipt_document. Locale defaults to Albanian. Replaying the idempotency key with a different locale conflicts.

Cancel a sale in full POST

The sale being cancelled is the path's `sale_id`. The body carries no lines or totals: Fiskaliza copies that sale's lines, payments, tax groups, currency, and totals to build the exact reversal. `pos_id` is the POS that issues the cancellation. The cancellation coupon is issued immediately in the requested locale and returned as receipt_document.