Fiskaliza
Referenca e API-sëKomandat

Issue a sale

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.

POST/v1/pos/{pos_id}/sales

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.

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_

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.

EUR is implicit and must not be sent. The backend calculates line amounts, tax groups and receipt totals; these output fields are rejected in requests. STANDARD is the default sale type. FREE_SUPPLY must total zero; other sales must have positive totals. Operator and free text inherit the POS defaults. Idempotency-Key is required separately from external_id. Repeating normalized input reuses the command; changing it 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" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "external_id": "order_123",    "occurred_at": "2026-08-25T10:00:00+02:00",    "items": [      {        "name": "Coffee",        "unit_price_cents": 118,        "tax_category": "E"      }    ],    "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"    }  }}

Update a point of sale PATCH

Send any non-empty subset of fields. Omitted fields are preserved, address replaces the whole address, and vat_number: null clears VAT.

Return part or all of a sale POST

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.