01 · Erste Anfrage

Vom Token zur Fiskalrechnung

Nutzen Sie zuerst die Entwicklungsumgebung. Unternehmen und Fiskalgerät kommen aus dem Token; der Body enthält nur Dokumentdaten.

01
Zugangsdaten erhalten
Fordern Sie ein Token für Umgebung, Unternehmen und Gerät an.
02
docId erstellen
Erzeugen und speichern Sie vor der ersten Anfrage eine stabile ID.
03
Registrieren und prüfen
Senden Sie die Rechnung und prüfen Sie Kennungen statt nur HTTP 200.

Minimale normale Rechnung

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SHOP-2026-000123",
  "articles": [
    {
      "articleId": "ART-1",
      "name": "Kafe",
      "vatCode": "B",
      "price": 120,
      "units": 2,
      "soldIn": "XPP"
    }
  ],
  "payment": [
    {
      "type": "CASH",
      "amount": 240
    }
  ]
}'

Abgeschlossene Antwort

{
  "orderId": "SHOP-2026-000123",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "12/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": 240
}

02 · Zugriff

Authentifizierung und Header

Jeder Endpoint benötigt ein Bearer-Token. Ersetzen Sie den Beispielwert von integration-app durch die stabile Kennung Ihrer Integration und verwenden Sie sie unverändert für alle Anfragen.

Header	Anforderung	Zweck
`Authorization`	Erforderlich	Bearer-Token der gewählten Umgebung.
`Content-Type`	Erforderlich	Für jede Anfrage application/json.
`integration-app`	Empfohlen	Ersetzen Sie your-client-name oder erp-x durch die Kennung Ihrer Integration.

03 · Wiederherstellungsprotokoll

docId verhindert Duplikate

Wählen Sie docId vor dem Senden in Ihrem System. Die Wiederverwendung setzt denselben Fiskalvorgang fort und darf keine zweite Rechnung erzeugen.

Einmal erzeugen: 5–200 Zeichen, eindeutig pro Geschäftsdokument.
Vor POST speichern: docId, unveränderlichen Body und lokale ID atomar speichern.
Bei Wiederherstellung nutzen: Timeout, Verbindungsabbruch, 502/503 und unvollständige E-Rechnung behalten dieselbe docId.
Single Flight: register und status nie parallel für dieselbe docId ausführen.

Sichere Wiederherstellung

same docId · same body

01
POST register
02
Unklar / unvollständig
03
Warten + Jitter
04
POST status
05
Fertig?
06
Gleichen Body senden

1Normal erfordert fic; elektronisch erfordert fic und eic.
2Bei Timeout, Netzwerk, 502/503 oder unvollständigem Ergebnis exponentielles Backoff mit Jitter bis 30 Sekunden.
3/invoice/status mit derselben docId aufrufen. Falls nicht vorhanden, /invoice/register mit identischem Body und docId wiederholen.
4Validierungsfehler oder env:CLIENT erst nach Korrektur wiederholen.

Eine Stornierung ist ein neues Fiskaldokument und erhält eine neue docId. Wiederholungen verwenden diese Storno-docId.

Client-Entscheidungsablauf

const docId = await persistOperation(payload)

const result = await register({ ...payload, docId })
if (result.fic && (!payload.isEinvoice || result.eic)) return complete(result)

await backoffWithJitter()
const recovered = await status({ docId })

if (recovered.notFound) {
  return register({ ...payload, docId }) // exact same body
}

return evaluate(recovered)

04 · Dokumentmodell

Beispiele für Rechnungsanfragen

Dokumenttyp öffnen, um vollständige Anfrage, Antwort und Abschlusskennungen zu sehen.

POST NORMALArtikel, kombinierte Zahlungen und optionaler buyer; documentType kann fehlen. fic

/invoice/registerAbschluss: fic #invoice-type-normal

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SHOP-2026-000123",
  "articles": [
    {
      "articleId": "ART-COFFEE",
      "name": "Kafe ekspres",
      "vatCode": "B",
      "price": 120,
      "units": 2,
      "soldIn": "XPP"
    },
    {
      "articleId": "ART-WATER",
      "name": "Ujë natyral",
      "vatCode": "B",
      "price": 100,
      "units": 1,
      "soldIn": "XPP"
    }
  ],
  "payment": [
    {
      "type": "CASH",
      "amount": 200
    },
    {
      "type": "CARD",
      "amount": 140
    }
  ]
}'

Beispielantwort

{
  "orderId": "SHOP-2026-000123",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "12/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": 340
}

Request-Felder

Feld	Typ
`docId`	`string`
`articles`	`object[]`
`articles[].articleId`	`string`
`articles[].name`	`string`
`articles[].vatCode`	`string`
`articles[].price`	`number`
`articles[].units`	`number`
`articles[].soldIn`	`string`
`payment`	`object[]`
`payment[].type`	`string`
`payment[].amount`	`number`

Response-Felder

Feld	Typ
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST ORDERNur Artikel; payment entfällt und wird als ORDER erzeugt. fic

/invoice/registerAbschluss: fic #invoice-type-order

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "ORDER-2026-000124",
  "documentType": "ORDER",
  "articles": [
    {
      "articleId": "ORD-1",
      "name": "Drekë biznesi",
      "vatCode": "B",
      "price": 1200,
      "units": 1,
      "soldIn": "XPP"
    }
  ]
}'

Beispielantwort

{
  "orderId": "ORDER-2026-000124",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "13/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": 1200
}

Request-Felder

Feld	Typ
`docId`	`string`
`documentType`	`string`
`articles`	`object[]`
`articles[].articleId`	`string`
`articles[].name`	`string`
`articles[].vatCode`	`string`
`articles[].price`	`number`
`articles[].units`	`number`
`articles[].soldIn`	`string`

Response-Felder

Feld	Typ
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST SUMMARYVerbraucht ungenutzte ORDER-iic; articles entfällt. fic

/invoice/registerAbschluss: fic #invoice-type-summary

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SUMMARY-2026-000125",
  "documentType": "SUMMARY",
  "summaryInvoices": [
    "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
    "A11EBF3F7B7C502D6AAF2321A7CE2CE9"
  ],
  "total": 1800,
  "payment": [
    {
      "type": "CASH",
      "amount": 1800
    }
  ]
}'

Beispielantwort

{
  "orderId": "SUMMARY-2026-000125",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "14/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": 1800
}

Request-Felder

Feld	Typ
`docId`	`string`
`documentType`	`string`
`summaryInvoices`	`string[]`
`total`	`number`
`payment`	`object[]`
`payment[].type`	`string`
`payment[].amount`	`number`

Response-Felder

Feld	Typ
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST SELFISSUEBenötigt selfIssueType und Lieferantendaten in buyer. fic

/invoice/registerAbschluss: fic #invoice-type-selfissue

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SELFISSUE-2026-000126",
  "documentType": "SELFISSUE",
  "selfIssueType": "DOMESTIC",
  "reverseCharge": true,
  "buyer": {
    "buyerIDType": "NUIS",
    "buyerIDNum": "{{supplierNipt}}",
    "buyerName": "Furnitor SHPK",
    "buyerAddress": "Tiranë",
    "buyerTown": "Tiranë",
    "buyerCountry": "ALB"
  },
  "articles": [
    {
      "articleId": "SVC-1",
      "name": "Shërbim profesional",
      "vatCode": "B",
      "price": 10000,
      "units": 1,
      "soldIn": "HUR"
    }
  ],
  "payment": [
    {
      "type": "CASH",
      "amount": 10000
    }
  ]
}'

Beispielantwort

{
  "orderId": "SELFISSUE-2026-000126",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "15/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": 10000
}

Request-Felder

Feld	Typ
`docId`	`string`
`documentType`	`string`
`selfIssueType`	`string`
`reverseCharge`	`boolean`
`buyer`	`object`
`buyer.buyerIDType`	`string`
`buyer.buyerIDNum`	`string`
`buyer.buyerName`	`string`
`buyer.buyerAddress`	`string`
`buyer.buyerTown`	`string`
`buyer.buyerCountry`	`string`
`articles`	`object[]`
`articles[].articleId`	`string`
`articles[].name`	`string`
`articles[].vatCode`	`string`
`articles[].price`	`number`
`articles[].units`	`number`
`articles[].soldIn`	`string`
`payment`	`object[]`
`payment[].type`	`string`
`payment[].amount`	`number`

Response-Felder

Feld	Typ
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST EXPORTAusländischer buyer und konfigurierter Export-USt-Code. fic

/invoice/registerAbschluss: fic #invoice-type-export

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "EXPORT-2026-000127",
  "documentType": "EXPORT",
  "supplyPeriod": {
    "start": "2026-08-01",
    "end": "2026-08-28"
  },
  "buyer": {
    "buyerIDType": "VAT",
    "buyerIDNum": "IT12345678901",
    "buyerName": "Acquirente Demo SRL",
    "buyerAddress": "Via Roma 1",
    "buyerTown": "Bari",
    "buyerCountry": "ITA",
    "buyerCountryCode": "IT"
  },
  "articles": [
    {
      "articleId": "EXP-1",
      "name": "Mall për eksport",
      "vatCode": "J",
      "price": 25000,
      "units": 4,
      "soldIn": "XPP"
    }
  ],
  "payment": [
    {
      "type": "TRANSFER",
      "amount": 100000
    }
  ]
}'

Beispielantwort

{
  "orderId": "EXPORT-2026-000127",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "16/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": 100000
}

Request-Felder

Feld	Typ
`docId`	`string`
`documentType`	`string`
`supplyPeriod`	`object`
`supplyPeriod.start`	`string`
`supplyPeriod.end`	`string`
`buyer`	`object`
`buyer.buyerIDType`	`string`
`buyer.buyerIDNum`	`string`
`buyer.buyerName`	`string`
`buyer.buyerAddress`	`string`
`buyer.buyerTown`	`string`
`buyer.buyerCountry`	`string`
`buyer.buyerCountryCode`	`string`
`articles`	`object[]`
`articles[].articleId`	`string`
`articles[].name`	`string`
`articles[].vatCode`	`string`
`articles[].price`	`number`
`articles[].units`	`number`
`articles[].soldIn`	`string`
`payment`	`object[]`
`payment[].type`	`string`
`payment[].amount`	`number`

Response-Felder

Feld	Typ
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST ELEKTRONISCH · P1Standard-E-Rechnung mit NUIS-buyer und bargeldloser Zahlung. fic + eic

/invoice/registerAbschluss: fic + eic #invoice-type-electronic-p1

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "EINVOICE-P1-2026-000128",
  "isEinvoice": true,
  "selectedProcess": "P1",
  "payDeadline": "2026-09-30",
  "buyer": {
    "buyerIDType": "NUIS",
    "buyerIDNum": "{{buyerNipt}}",
    "buyerName": "Blerës SHPK",
    "buyerAddress": "Tiranë",
    "buyerTown": "Tiranë",
    "buyerCountry": "ALB",
    "buyerCountryCode": "AL"
  },
  "articles": [
    {
      "articleId": "SVC-CLOUD",
      "name": "Shërbim cloud",
      "vatCode": "B",
      "price": 10000,
      "units": 1,
      "soldIn": "HUR"
    }
  ],
  "payment": [
    {
      "type": "ACCOUNT",
      "amount": 10000,
      "details": [
        {
          "idNumber": "{{sellerIban}}",
          "name": "Shitësi SHPK",
          "bankName": "Banka",
          "swift_code": "ABCDEFGH",
          "country": "Shqipëri",
          "countryCode": "AL",
          "currency": "ALL"
        }
      ]
    }
  ]
}'

Beispielantwort

{
  "orderId": "EINVOICE-P1-2026-000128",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "17/2026/xx123xx123",
  "invoiceType": "NONCASH",
  "totalPrice": 10000,
  "eic": "2a8d91cf-8fea-4d86-b79d-4bcb0b153e78"
}

Request-Felder

Feld	Typ
`docId`	`string`
`isEinvoice`	`boolean`
`selectedProcess`	`string`
`payDeadline`	`string`
`buyer`	`object`
`buyer.buyerIDType`	`string`
`buyer.buyerIDNum`	`string`
`buyer.buyerName`	`string`
`buyer.buyerAddress`	`string`
`buyer.buyerTown`	`string`
`buyer.buyerCountry`	`string`
`buyer.buyerCountryCode`	`string`
`articles`	`object[]`
`articles[].articleId`	`string`
`articles[].name`	`string`
`articles[].vatCode`	`string`
`articles[].price`	`number`
`articles[].units`	`number`
`articles[].soldIn`	`string`
`payment`	`object[]`
`payment[].type`	`string`
`payment[].amount`	`number`
`payment[].details`	`object[]`
`payment[].details[].idNumber`	`string`
`payment[].details[].name`	`string`
`payment[].details[].bankName`	`string`
`payment[].details[].swift_code`	`string`
`payment[].details[].country`	`string`
`payment[].details[].countryCode`	`string`
`payment[].details[].currency`	`string`

Response-Felder

Feld	Typ
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

POST ELEKTRONISCH · P4Vorauszahlung; prepaidAmount darf den Gesamtbetrag nicht überschreiten. fic + eic

/invoice/registerAbschluss: fic + eic #invoice-type-electronic-p4

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "EINVOICE-P4-2026-000129",
  "isEinvoice": true,
  "selectedProcess": "P4",
  "prepaidAmount": 5000,
  "buyer": {
    "buyerIDType": "NUIS",
    "buyerIDNum": "{{buyerNipt}}",
    "buyerName": "Blerës SHPK",
    "buyerAddress": "Tiranë",
    "buyerTown": "Tiranë",
    "buyerCountry": "ALB"
  },
  "articles": [
    {
      "articleId": "ADV-1",
      "name": "Parapagim shërbimi",
      "vatCode": "B",
      "price": 10000,
      "units": 1,
      "soldIn": "XPP"
    }
  ],
  "payment": [
    {
      "type": "TRANSFER",
      "amount": 10000
    }
  ]
}'

Beispielantwort

{
  "orderId": "EINVOICE-P4-2026-000129",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "18/2026/xx123xx123",
  "invoiceType": "NONCASH",
  "totalPrice": 10000,
  "eic": "0543e84b-6108-48b2-a2af-5db66bb80616"
}

Request-Felder

Feld	Typ
`docId`	`string`
`isEinvoice`	`boolean`
`selectedProcess`	`string`
`prepaidAmount`	`number`
`buyer`	`object`
`buyer.buyerIDType`	`string`
`buyer.buyerIDNum`	`string`
`buyer.buyerName`	`string`
`buyer.buyerAddress`	`string`
`buyer.buyerTown`	`string`
`buyer.buyerCountry`	`string`
`articles`	`object[]`
`articles[].articleId`	`string`
`articles[].name`	`string`
`articles[].vatCode`	`string`
`articles[].price`	`number`
`articles[].units`	`number`
`articles[].soldIn`	`string`
`payment`	`object[]`
`payment[].type`	`string`
`payment[].amount`	`number`

Response-Felder

Feld	Typ
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

POST ELEKTRONISCH · P9/P10Gutschrift oder Korrektur mit elektronischer iic-Referenz. fic + eic

/invoice/registerAbschluss: fic + eic #invoice-type-electronic-p9-p10

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "EINVOICE-P9-2026-000130",
  "isEinvoice": true,
  "selectedProcess": "P9",
  "correctiveInvoice": {
    "iicRef": "{{electronicIic}}"
  },
  "buyer": {
    "buyerIDType": "NUIS",
    "buyerIDNum": "{{buyerNipt}}",
    "buyerName": "Blerës SHPK",
    "buyerAddress": "Tiranë",
    "buyerTown": "Tiranë",
    "buyerCountry": "ALB"
  },
  "articles": [
    {
      "articleId": "CORR-1",
      "name": "Korrigjim shërbimi",
      "vatCode": "B",
      "price": -1000,
      "units": 1,
      "soldIn": "XPP"
    }
  ],
  "payment": [
    {
      "type": "TRANSFER",
      "amount": -1000
    }
  ]
}'

Beispielantwort

{
  "orderId": "EINVOICE-P9-2026-000130",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "19/2026/xx123xx123",
  "invoiceType": "NONCASH",
  "totalPrice": -1000,
  "eic": "6df80aec-f690-43ce-a2f2-45ee0cb948ce"
}

Request-Felder

Feld	Typ
`docId`	`string`
`isEinvoice`	`boolean`
`selectedProcess`	`string`
`correctiveInvoice`	`object`
`correctiveInvoice.iicRef`	`string`
`buyer`	`object`
`buyer.buyerIDType`	`string`
`buyer.buyerIDNum`	`string`
`buyer.buyerName`	`string`
`buyer.buyerAddress`	`string`
`buyer.buyerTown`	`string`
`buyer.buyerCountry`	`string`
`articles`	`object[]`
`articles[].articleId`	`string`
`articles[].name`	`string`
`articles[].vatCode`	`string`
`articles[].price`	`number`
`articles[].units`	`number`
`articles[].soldIn`	`string`
`payment`	`object[]`
`payment[].type`	`string`
`payment[].amount`	`number`

Response-Felder

Feld	Typ
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

POST ELEKTRONISCH · P11Teilweiser elektronischer Rechnungsfluss. fic + eic

/invoice/registerAbschluss: fic + eic #invoice-type-electronic-p11

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "EINVOICE-P11-2026-000131",
  "isEinvoice": true,
  "selectedProcess": "P11",
  "buyer": {
    "buyerIDType": "NUIS",
    "buyerIDNum": "{{buyerNipt}}",
    "buyerName": "Blerës SHPK",
    "buyerAddress": "Tiranë",
    "buyerTown": "Tiranë",
    "buyerCountry": "ALB"
  },
  "articles": [
    {
      "articleId": "PART-1",
      "name": "Faturim i pjesshëm",
      "vatCode": "B",
      "price": 25000,
      "units": 1,
      "soldIn": "XPP"
    }
  ],
  "payment": [
    {
      "type": "TRANSFER",
      "amount": 25000
    }
  ]
}'

Beispielantwort

{
  "orderId": "EINVOICE-P11-2026-000131",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "20/2026/xx123xx123",
  "invoiceType": "NONCASH",
  "totalPrice": 25000,
  "eic": "55df7eaf-126f-41b7-8270-6fa57080703e"
}

Request-Felder

Feld	Typ
`docId`	`string`
`isEinvoice`	`boolean`
`selectedProcess`	`string`
`buyer`	`object`
`buyer.buyerIDType`	`string`
`buyer.buyerIDNum`	`string`
`buyer.buyerName`	`string`
`buyer.buyerAddress`	`string`
`buyer.buyerTown`	`string`
`buyer.buyerCountry`	`string`
`articles`	`object[]`
`articles[].articleId`	`string`
`articles[].name`	`string`
`articles[].vatCode`	`string`
`articles[].price`	`number`
`articles[].units`	`number`
`articles[].soldIn`	`string`
`payment`	`object[]`
`payment[].type`	`string`
`payment[].amount`	`number`

Response-Felder

Feld	Typ
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

POST STORNIERUNG · NORMALNeue Storno-docId mit Verweis auf die ursprüngliche iic. fic

/invoice/cancelAbschluss: fic #invoice-type-cancellation

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/cancel' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "CANCEL-2026-000132",
  "correctiveInvoice": {
    "iicRef": "D21EBF3F7B7C502D6AAF2321A7CE2CE8"
  },
  "invoiceNotes": "Anulim me kërkesë të klientit"
}'

Beispielantwort

{
  "orderId": "CANCEL-2026-000132",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "21/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": -340
}

Request-Felder

Feld	Typ
`docId`	`string`
`correctiveInvoice`	`object`
`correctiveInvoice.iicRef`	`string`
`invoiceNotes`	`string`

Response-Felder

Feld	Typ
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST STORNIERUNG · ELEKTRONISCHP10-Korrekturstorno einer Rechnung, die bereits eine eic besitzt. fic + eic

/invoice/cancelAbschluss: fic + eic #invoice-type-electronic-cancellation

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/cancel' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "CANCEL-EINVOICE-2026-000133",
  "isEinvoice": true,
  "selectedProcess": "P10",
  "correctiveInvoice": {
    "iicRef": "{{electronicIic}}"
  },
  "invoiceNotes": "Anulim i faturës elektronike"
}'

Beispielantwort

{
  "orderId": "CANCEL-EINVOICE-2026-000133",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "22/2026",
  "invoiceType": "NONCASH",
  "totalPrice": -10000,
  "eic": "d59ef857-47df-4a80-a7d8-22ce70577df3"
}

Request-Felder

Feld	Typ
`docId`	`string`
`isEinvoice`	`boolean`
`selectedProcess`	`string`
`correctiveInvoice`	`object`
`correctiveInvoice.iicRef`	`string`
`invoiceNotes`	`string`

Response-Felder

Feld	Typ
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

Prozessübersicht E-Rechnung

Fiskalisierung und E-Rechnungszustellung sind getrennte Stufen. Vollständig ist die Rechnung erst mit beiden Kennungen.

Prozess	Standardtyp	Zusatzregel
`P1`	`380`	Lieferungen gegen Bestellungen auf Vertragsbasis.
`P2`	`380`	Lieferungen von Waren oder Dienstleistungen auf Vertragsbasis.
`P3`	`380`	Lieferung gegen eine gelegentliche Bestellung.
`P4`	`386`	Vorauszahlung; prepaidAmount muss positiv und höchstens so hoch wie der Gesamtbetrag sein.
`P5`	`380`	Zahlung vor Ort.
`P6`	`380`	Zahlung vor Lieferung.
`P7`	`380`	Rechnung mit Verweis auf den Lieferschein.
`P8`	`380`	Rechnung mit Verweisen auf Liefer- und Empfangsbeleg.
`P9`	`384`	Gutschrift oder negative Rechnung; correctiveInvoice.iicRef verweist auf eine Rechnung mit eic.
`P10`	`384`	Korrektur oder Storno; correctiveInvoice.iicRef verweist auf eine Rechnung mit eic.
`P11`	`326`	Teil- und Schlussrechnung.

UNTDID-Codes für Rechnungstypen

Verwenden Sie selectedInvoiceType nur für eine gezielte Dokumentklassifizierung. Fehlt der Wert, wählt selectedProcess den oben angegebenen Standardcode.

Code	Bedeutung
`82`	Rechnung für gemessene Dienstleistungen
`84`	Lastschrift für finanzielle Anpassungen
`325`	Pro-forma-Rechnung
`326`	Teilrechnung
`380`	Handelsrechnung
`383`	Lastschrift
`386`	Vorauszahlungsrechnung
`393`	Factoring-Rechnung
`394`	Leasingrechnung
`395`	Konsignationsrechnung
`575`	Versichererrechnung
`623`	Spediteurrechnung
`780`	Frachtrechnung

Die Codes 80, 381, 384, 385 und 389 sind für automatisch vom Prozess zugewiesene Dokumenttypen reserviert und nicht direkt auswählbar.

05 · HTTP-Referenz

Endpoints

Alle Endpoints verwenden POST, JSON und dieselben Auth-Header.

POST/invoice/registerRechnung registrieren · Neues Dokument erstellen oder per docId fortsetzen.

Rechnungen#register-invoice

Erforderlich: docId · articles[]* · payment[]*
Regeln: NORMAL | ORDER | SUMMARY | SELFISSUE | EXPORT | eInvoice

Request-Felder

Feld	Typ
`docId`	`string`
`operatorCode`	`string?`
`currency`	`Currency?`
`articles`	`Article[] (conditional)`
`payment`	`Payment[] (conditional)`
`invoiceRebate`	`Rebate?`
`buyer`	`Buyer (conditional)`
`correctiveInvoice`	`CorrectiveInvoiceRef (conditional)`
`invoiceNotes`	`string?`
`documentType`	`NORMAL \| ORDER \| SUMMARY \| SELFISSUE \| EXPORT?`
`selfIssueType`	`AGREEMENT \| DOMESTIC \| ABROAD \| SELF \| OTHER (conditional)`
`reverseCharge`	`boolean?`
`summaryInvoices`	`string[] (conditional)`
`total`	`number (conditional)`
`supplyPeriod`	`{ start: date; end: date }?`
`isEinvoice`	`boolean?`
`selectedProcess`	`P1 \| P2 \| P3 \| P4 \| P5 \| P6 \| P7 \| P8 \| P9 \| P10 \| P11?`
`selectedInvoiceType`	`UNTDID code?`
`payDeadline`	`string(date)?`
`prepaidAmount`	`number (conditional)`

Response-Felder

Feld	Typ
`orderId`	`string`
`fic`	`string?`
`eic`	`string?`
`iic`	`string?`
`link`	`string(uri)?`
`error`	`FiscalError?`
`invoiceNumber`	`string?`
`invoiceOrderNumber`	`integer?`
`invoiceType`	`CASH \| NONCASH?`
`totalPrice`	`number?`
`totalPriceWithoutVat`	`number?`
`totalVatAmount`	`number?`
`taxFreeAmount`	`number?`
`goodsExport`	`number?`
`markUpAmount`	`number?`
`operatorCode`	`string?`
`businessUnitCode`	`string?`
`tcrCode`	`string?`
`sellerName`	`string?`
`sellerNuis`	`string?`
`sellerAddress`	`string?`

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SHOP-2026-000123",
  "articles": [
    {
      "articleId": "ART-1",
      "name": "Kafe",
      "vatCode": "B",
      "price": 120,
      "units": 2,
      "soldIn": "XPP"
    }
  ],
  "payment": [
    {
      "type": "CASH",
      "amount": 240
    }
  ]
}'

Beispielantwort

{
  "orderId": "SHOP-2026-000123",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "12/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": 240
}

POST/invoice/cancelRechnung stornieren · Korrekturstorno für eine vorhandene iic erstellen.

Rechnungen#cancel-invoice

Erforderlich: new docId · correctiveInvoice.iicRef
Regeln: no articles · no payment

Request-Felder

Feld	Typ
`docId`	`string`
`operatorCode`	`string?`
`correctiveInvoice`	`CorrectiveInvoiceRef`
`invoiceNotes`	`string?`
`isEinvoice`	`boolean?`
`selectedProcess`	`P1–P11?`
`selectedInvoiceType`	`UNTDID code?`
`payDeadline`	`string(date)?`
`prepaidAmount`	`number?`

Response-Felder

Feld	Typ
`orderId`	`string`
`fic`	`string?`
`eic`	`string?`
`iic`	`string?`
`link`	`string(uri)?`
`error`	`FiscalError?`
`invoiceNumber`	`string?`
`invoiceOrderNumber`	`integer?`
`invoiceType`	`CASH \| NONCASH?`
`totalPrice`	`number?`
`totalPriceWithoutVat`	`number?`
`totalVatAmount`	`number?`
`taxFreeAmount`	`number?`
`goodsExport`	`number?`
`markUpAmount`	`number?`
`operatorCode`	`string?`
`businessUnitCode`	`string?`
`tcrCode`	`string?`
`sellerName`	`string?`
`sellerNuis`	`string?`
`sellerAddress`	`string?`

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/cancel' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SHOP-2026-000123-CANCEL",
  "correctiveInvoice": {
    "iicRef": "D21EBF3F7B7C502D6AAF2321A7CE2CE8"
  },
  "invoiceNotes": "Customer cancellation"
}'

Beispielantwort

{
  "orderId": "SHOP-2026-000123-CANCEL",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "13/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": -240
}

POST/invoice/statusRechnungsstatus · Status per docId lesen und unvollständigen Vorgang fortsetzen.

Rechnungen#invoice-status

Erforderlich: docId
Regeln: same docId · may continue processing

Request-Felder

Feld	Typ
`docId`	`string`

Response-Felder

Feld	Typ
`orderId`	`string`
`fic`	`string?`
`eic`	`string?`
`iic`	`string?`
`link`	`string(uri)?`
`error`	`FiscalError?`
`invoiceNumber`	`string?`
`invoiceOrderNumber`	`integer?`
`invoiceType`	`CASH \| NONCASH?`
`totalPrice`	`number?`
`totalPriceWithoutVat`	`number?`
`totalVatAmount`	`number?`
`taxFreeAmount`	`number?`
`goodsExport`	`number?`
`markUpAmount`	`number?`
`operatorCode`	`string?`
`businessUnitCode`	`string?`
`tcrCode`	`string?`
`sellerName`	`string?`
`sellerNuis`	`string?`
`sellerAddress`	`string?`

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/status' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SHOP-2026-000123"
}'

Beispielantwort

{
  "orderId": "SHOP-2026-000123",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "12/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": 240
}

POST/invoice/pdfRechnungs-PDF · A4-PDF, Beleg-PNG oder E-Rechnungs-PDF als base64.

Rechnungen#invoice-pdf

Erforderlich: iic
Regeln: A4 | receipt | eInvoice

Request-Felder

Feld	Typ
`iic`	`string`
`pdfType`	`'A4' \| 'receipt' \| 'eInvoice'`
`paperWidth`	`58 \| 80 \| 110?`
`lang`	`'sq' \| 'en'?`

Response-Felder

Feld	Typ
`base64`	`string`
`lang`	`string?`
`eic`	`string?`

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/pdf' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "pdfType": "A4",
  "lang": "sq"
}'

Beispielantwort

{
  "base64": "JVBERi0xLjQKJcfsj6IK...",
  "lang": "sq"
}

POST/balance/initiateKasse initialisieren · Anfangsbestand in ALL melden.

Kassenbestand#initiate-balance

Erforderlich: docId · amount
Regeln: once per business day and fiscal device · before the first cash invoice · amount in ALL

Request-Felder

Feld	Typ
`docId`	`string`
`amount`	`number`
`notes`	`string?`
`operatorCode`	`string?`

Response-Felder

Feld	Typ
`orderId`	`string`
`fcdc`	`string?`
`error`	`FiscalError?`

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/balance/initiate' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SHIFT-2026-08-28-OPEN",
  "amount": 10000
}'

Beispielantwort

{
  "orderId": "SHIFT-2026-08-28-OPEN",
  "fcdc": "b5c3e1a2-9f44-4c3a-9c1e-2f0d7a5b8e10"
}

POST/balance/depositBargeld einzahlen · Kassenzugang in ALL melden.

Kassenbestand#deposit-balance

Erforderlich: docId · amount
Regeln: amount in ALL

Request-Felder

Feld	Typ
`docId`	`string`
`amount`	`number`
`notes`	`string?`
`operatorCode`	`string?`

Response-Felder

Feld	Typ
`orderId`	`string`
`fcdc`	`string?`
`error`	`FiscalError?`

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/balance/deposit' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SHIFT-2026-08-28-IN-1",
  "amount": 5000,
  "notes": "Cash added to till"
}'

Beispielantwort

{
  "orderId": "SHIFT-2026-08-28-IN-1",
  "fcdc": "d6a4e2b3-8e55-4d2b-8b2f-3a1e6b4c9f21"
}

POST/balance/withdrawBargeld entnehmen · Kassenentnahme in ALL melden.

Kassenbestand#withdraw-balance

Erforderlich: docId · amount
Regeln: amount in ALL

Request-Felder

Feld	Typ
`docId`	`string`
`amount`	`number`
`notes`	`string?`
`operatorCode`	`string?`

Response-Felder

Feld	Typ
`orderId`	`string`
`fcdc`	`string?`
`error`	`FiscalError?`

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/balance/withdraw' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SHIFT-2026-08-28-OUT-1",
  "amount": 2500,
  "notes": "Bank deposit"
}'

Beispielantwort

{
  "orderId": "SHIFT-2026-08-28-OUT-1",
  "fcdc": "e7b5f3c4-7d66-5e3c-9a3e-4b2f7c5d0a32"
}

POST/utilities/get-taxpayersSteuerzahler suchen · Nach NIPT oder Firmenname suchen.

Hilfsfunktionen#get-taxpayers

Erforderlich: searchTerm (3–200)
Regeln: NIPT or business name · searchTerm minimum 3 characters · no activity-status field

Request-Felder

Feld	Typ
`searchTerm`	`string (3–200)`

Response-Felder

Feld	Typ
`[]`	`Taxpayer[]`
`[].Tin`	`string`
`[].Name`	`string`
`[].Address`	`string`
`[].Town`	`string`
`[].Country`	`string (ISO 3166-1 alpha-3)`

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/utilities/get-taxpayers' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "searchTerm": "Vodafone"
}'

Beispielantwort

[
  {
    "Address": "Rruga Pavaresia, kodi postal 1050, Kashar 61",
    "Country": "ALB",
    "Name": "FONDACIONI VODAFONE ALBANIA",
    "Tin": "K72118452F",
    "Town": "Tirane"
  },
  {
    "Address": "Autostrada Tirane-Durres, Rruga Pavaresia, Nr.61, Kashar",
    "Country": "ALB",
    "Name": "VODAFONE ALBANIA",
    "Tin": "K11715005L",
    "Town": "Kashar"
  }
]

POST/utilities/get-operatorsOperatoren auflisten · Verfügbare Operatoren zurückgeben.

Hilfsfunktionen#get-operators

Erforderlich: none
Regeln: authenticated business + device

Request-Felder

Feld	Typ
`body`	`{}`

Response-Felder

Feld	Typ
`[]`	`Operator[]`
`[].name`	`string`
`[].opCode`	`string`

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/utilities/get-operators' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{}'

Beispielantwort

[
  {
    "name": "test3",
    "opCode": "gh537ez280"
  },
  {
    "name": "User A",
    "opCode": "aa111aa222"
  }
]

06 · Feldreferenz

API-Schemakatalog

Schema öffnen, um jedes Feld, den exakten Datentyp, die Anforderung und Validierungsregel zu sehen.

RegisterInvoiceRequest22

Feld	Typ	Anforderung	Regeln
`docId`	`string`	Erforderlich	5–200 chars · unique per business document
`operatorCode`	`string`	Optional	^[a-z]{2}\d{3}[a-z]{2}\d{3}$
`currency`	`Currency`	Optional	default: ALL / 1
`articles`	`Article[]`	Bedingt	required except SUMMARY · minItems: 1
`payment`	`Payment[]`	Bedingt	required except ORDER · minItems: 1
`invoiceRebate`	`Rebate`	Optional	percentage or value, never both
`buyer`	`Buyer`	Bedingt	required for eInvoice and EXPORT
`correctiveInvoice`	`CorrectiveInvoiceRef`	Bedingt	required for P9 / P10
`invoiceNotes`	`string`	Optional	maxLength: 500
`documentType`	`enum`	Optional	NORMAL \| ORDER \| SUMMARY \| SELFISSUE \| EXPORT
`selfIssueType`	`enum`	Bedingt	AGREEMENT \| DOMESTIC \| ABROAD \| SELF \| OTHER
`reverseCharge`	`boolean`	Optional	true only for SELFISSUE
`summaryInvoices`	`string[]`	Bedingt	SUMMARY only · minItems: 1 · each iic is 32 hex chars
`total`	`number`	Bedingt	SUMMARY only · exact referenced ORDER total
`supplyPeriod`	`object`	Optional	start/end in one calendar month
`supplyPeriod.start`	`string(date)`	Bedingt	YYYY-MM-DD
`supplyPeriod.end`	`string(date)`	Bedingt	YYYY-MM-DD
`isEinvoice`	`boolean`	Optional	default: false
`selectedProcess`	`enum`	Optional	P1–P11 · default: P1
`selectedInvoiceType`	`string(enum)`	Optional	82 \| 84 \| 325 \| 326 \| 380 \| 383 \| 386 \| 393 \| 394 \| 395 \| 575 \| 623 \| 780
`payDeadline`	`string(date)`	Optional	YYYY-MM-DD · current year · not in the past
`prepaidAmount`	`number`	Bedingt	required for P4 · >= 0 · max 2 decimals

Article8

Feld	Typ	Anforderung	Regeln
`articleId`	`string`	Erforderlich	maxLength: 100
`name`	`string`	Erforderlich	maxLength: 100
`vatCode`	`string(enum)`	Erforderlich	A \| B \| C \| D \| E \| F \| G \| H \| I \| J \| K \| L · must match the business fiscal configuration
`price`	`number`	Erforderlich	unit price including VAT
`units`	`number`	Erforderlich	quantity
`soldIn`	`string`	Erforderlich	UN/CEFACT unit code, e.g. XPP \| KGM \| LTR \| HUR
`totalPrice`	`number`	Optional	default: price × units
`rebate`	`Rebate`	Optional	line-level discount

Rebate2

Feld	Typ	Anforderung	Regeln
`inPercentage`	`number`	Bedingt	mutually exclusive with inValue
`inValue`	`number`	Bedingt	mutually exclusive with inPercentage

Payment3

Feld	Typ	Anforderung	Regeln
`type`	`string(enum)`	Erforderlich	CASH \| BANKNOTE \| CARD \| CHECK \| SVOUCHER \| COMPANY \| ORDER \| ACCOUNT \| FACTORING \| COMPENSATION \| TRANSFER \| WAIVER \| KIND \| OTHER
`amount`	`number`	Erforderlich	payment sum must equal calculated invoice total
`details`	`PaymentDetail[]`	Bedingt	required and non-empty for ACCOUNT

PaymentDetail7

Feld	Typ	Anforderung	Regeln
`idNumber`	`string`	Erforderlich	IBAN or account number
`name`	`string`	Erforderlich	account holder
`bankName`	`string`	Erforderlich	bank name
`swift_code`	`string`	Erforderlich	SWIFT / BIC
`country`	`string`	Erforderlich	country name
`countryCode`	`string`	Erforderlich	ISO 3166-1 alpha-2 · exactly 2 chars
`currency`	`string`	Erforderlich	ISO 4217 · exactly 3 chars

Buyer7

Feld	Typ	Anforderung	Regeln
`buyerIDType`	`string(enum)`	Erforderlich	NUIS \| ID \| PASS \| VAT \| TAX \| SOC \| POINTS
`buyerIDNum`	`string`	Erforderlich	when buyerIDType=NUIS: ^[A-Za-z][0-9]{8}[A-Za-z]$ · normalize to uppercase
`buyerName`	`string`	Erforderlich	buyer legal/display name
`buyerAddress`	`string`	Erforderlich	buyer address
`buyerTown`	`string`	Erforderlich	buyer town
`buyerCountry`	`string`	Erforderlich	ISO 3166-1 alpha-3, e.g. ALB
`buyerCountryCode`	`string`	Optional	ISO 3166-1 alpha-2 · default: AL

Currency2

Feld	Typ	Anforderung	Regeln
`code`	`string`	Optional	ISO 4217 · default: ALL
`exRate`	`number`	Bedingt	required when code != ALL · rate against ALL

CorrectiveInvoiceRef2

Feld	Typ	Anforderung	Regeln
`iicRef`	`string`	Erforderlich	existing invoice iic · 32 hex chars
`issueDateTime`	`string(date)`	Optional	defaults to original invoice date

CancelInvoiceRequest9

Feld	Typ	Anforderung	Regeln
`docId`	`string`	Erforderlich	new cancellation id · 5–200 chars
`operatorCode`	`string`	Optional	^[a-z]{2}\d{3}[a-z]{2}\d{3}$
`correctiveInvoice`	`CorrectiveInvoiceRef`	Erforderlich	iicRef points to original invoice
`invoiceNotes`	`string`	Optional	maxLength: 500
`isEinvoice`	`boolean`	Optional	inherits from original when omitted
`selectedProcess`	`enum`	Optional	P1–P11 · electronic default: P10
`selectedInvoiceType`	`string(enum)`	Optional	same values as RegisterInvoiceRequest
`payDeadline`	`string(date)`	Optional	YYYY-MM-DD
`prepaidAmount`	`number`	Optional	>= 0 · max 2 decimals

StatusInvoiceRequest1

Feld	Typ	Anforderung	Regeln
`docId`	`string`	Erforderlich	same invoice docId · 5–200 chars

InvoicePdfRequest4

Feld	Typ	Anforderung	Regeln
`iic`	`string`	Erforderlich	exactly 32 hexadecimal chars
`pdfType`	`string(enum)`	Optional	A4 \| receipt \| eInvoice · default: A4
`paperWidth`	`integer(enum)`	Optional	58 \| 80 \| 110 · receipt only · default: 80
`lang`	`string(enum)`	Optional	sq \| en

BalanceRequest4

Feld	Typ	Anforderung	Regeln
`docId`	`string`	Erforderlich	5–200 chars · unique per balance operation · no prescribed naming convention
`amount`	`number`	Erforderlich	amount in ALL
`notes`	`string`	Optional	operation note
`operatorCode`	`string`	Optional	^[a-z]{2}\d{3}[a-z]{2}\d{3}$

GetTaxpayersRequest1

Feld	Typ	Anforderung	Regeln
`searchTerm`	`string`	Erforderlich	NIPT or business name · 3–200 chars

InvoiceResponse21

Feld	Typ	Anforderung	Regeln
`orderId`	`string`	Erforderlich	echoes request docId
`fic`	`string`	Bedingt	normal completion identifier
`eic`	`string`	Bedingt	required with fic for electronic completion
`iic`	`string`	Bedingt	invoice identifier · 32 hex chars
`link`	`string(uri)`	Optional	public verification URL
`error`	`FiscalError`	Optional	present when incomplete or failed
`invoiceNumber`	`string`	Optional	fiscal invoice number
`invoiceOrderNumber`	`integer`	Optional	fiscal sequence number
`invoiceType`	`string(enum)`	Optional	CASH \| NONCASH
`totalPrice`	`number`	Optional	gross total
`totalPriceWithoutVat`	`number`	Optional	net total
`totalVatAmount`	`number`	Optional	VAT total
`taxFreeAmount`	`number`	Optional	tax-free total
`goodsExport`	`number`	Optional	export amount
`markUpAmount`	`number`	Optional	markup amount
`operatorCode`	`string`	Optional	fiscal operator code
`businessUnitCode`	`string`	Optional	fiscal business-unit code
`tcrCode`	`string`	Optional	empty for electronic invoices
`sellerName`	`string`	Optional	seller name
`sellerNuis`	`string`	Optional	seller NIPT
`sellerAddress`	`string`	Optional	seller address

InvoiceIncompleteResponse2

Feld	Typ	Anforderung	Regeln
`orderId`	`string`	Erforderlich	echoes request docId
`error`	`FiscalError`	Erforderlich	fiscalization or eInvoice delivery has not completed

Error2

Feld	Typ	Anforderung	Regeln
`message`	`string`	Erforderlich	validation, authorization or domain error message
`field`	`string`	Optional	field that failed validation

CisError3

Feld	Typ	Anforderung	Regeln
`faultEnv`	`string(enum)`	Optional	env:CLIENT \| env:SERVER
`faultString`	`string`	Optional	message returned by the tax platform
`faultCode`	`string`	Optional	tax-platform error code

FiscalError2

Feld	Typ	Anforderung	Regeln
`cisError`	`CisError`	Optional	tax platform error
`otherError`	`string`	Optional	temporary processing error

PdfResponse2

Feld	Typ	Anforderung	Regeln
`base64`	`string`	Erforderlich	base64 PDF or PNG
`lang`	`string`	Optional	document language

EinvoicePdfResponse2

Feld	Typ	Anforderung	Regeln
`base64`	`string`	Erforderlich	official eInvoice PDF encoded as base64
`eic`	`string`	Erforderlich	electronic invoice identifier

BalanceResponse3

Feld	Typ	Anforderung	Regeln
`orderId`	`string`	Erforderlich	echoes request docId
`fcdc`	`string`	Bedingt	balance-operation completion identifier
`error`	`FiscalError`	Optional	processing error

Taxpayer5

Feld	Typ	Anforderung	Regeln
`Tin`	`string`	Erforderlich	taxpayer NIPT
`Name`	`string`	Erforderlich	registered name
`Address`	`string`	Erforderlich	registered address
`Town`	`string`	Erforderlich	registered town
`Country`	`string`	Erforderlich	ISO 3166-1 alpha-3

Operator2

Feld	Typ	Anforderung	Regeln
`name`	`string`	Erforderlich	operator display name
`opCode`	`string`	Erforderlich	use as operatorCode in fiscal requests

Übersicht der USt.-Codes

vatCode hängt vom USt.-Status und der fiskalischen Konfiguration des Unternehmens ab, nicht nur vom Artikel. Für ein USt.-pflichtiges Unternehmen ist B die Standardkategorie mit 20%; A ist die 0%-Kategorie für ein nicht USt.-pflichtiges Unternehmen.

Code	Satz	Steuerliche Behandlung
`A`	`0%`	Nicht USt.-pflichtiges Unternehmen
`B`	`20%`	Regelsteuersatz
`C`	`0%`	Steuerbefreite Lieferung
`D`	`10%`	Ermäßigter Satz
`E`	`6%`	Ermäßigter Satz
`J`	`0%`	Warenausfuhr

Die API liefert diese Zuordnung derzeit nicht zurück. Speichern Sie sie in Ihrer Integrationskonfiguration. Verwenden Sie andere A–L-Codes nicht ohne bestätigte fiskalische Konfiguration.

Vollständige ACCOUNT-Zahlung

details muss ein nicht leeres Array sein. Jeder Eintrag beschreibt ein Verkäuferbankkonto und benötigt alle sieben hier gezeigten Felder.

Zahlungsfragment

{
  "payment": [
    {
      "type": "ACCOUNT",
      "amount": 10000,
      "details": [
        {
          "idNumber": "AL47212110090000000235698741",
          "name": "Shitësi SHPK",
          "bankName": "Banka XYZ",
          "swift_code": "ABCDEFGH",
          "country": "Shqipëri",
          "countryCode": "AL",
          "currency": "ALL"
        }
      ]
    }
  ]
}

Betriebliche Klarstellungen

Feld	Regeln
`buyerIDNum · NUIS`	Akzeptiertes Format: ein Buchstabe, acht Ziffern, ein Buchstabe (^[A-Za-z][0-9]{8}[A-Za-z]$). In Großbuchstaben normalisieren. Ein alternatives älteres NIPT-Format ist nicht Teil dieses Vertrags.
`get-taxpayers`	Country verwendet ISO 3166-1 Alpha-3 (ALB für Albanien). Die Antwort enthält keinen Aktiv-, Passiv- oder Abmeldestatus; verwenden Sie den Endpoint zur Suche und zum Ausfüllen der Käuferdaten, nicht zur abschließenden Prüfung des Steuerstatus.
`Ratenbegrenzung`	Derzeit ist kein numerisches Limit veröffentlicht. Suchanfragen entprellen und nicht bei jedem Tastendruck einen Request senden.
`balance/initiate`	Senden Sie pro Geschäftstag und authentifiziertem Fiskalgerät/TCR genau einen erfolgreichen Anfangsbestand, vor dessen erster Bar-Rechnung. Eine Anwendungsschicht ist keine Fiskalgrenze; einen Endpoint zum Schließen des Bestands gibt es nicht.
`Bestands-docId`	SHIFT-…-Werte sind nur Beispiele. Verwenden Sie eine stabile eindeutige Kennung mit 5–200 Zeichen und nutzen Sie sie nur zur Wiederherstellung desselben Bestandsvorgangs erneut.

MaßeinheitencodesLaden Sie die Liste der unterstützten Maßeinheiten herunter und verwenden Sie den Codewert als soldIn, zum Beispiel XPP, KGM, LTR oder HUR.Liste der Maßeinheiten herunterladen (.xlsx)

Kanonische Enums

soldIn: XPP · KGM · LTR · HUR · other UN/CEFACT unit codes
vatCode: A · B · C · D · E · F · G · H · I · J · K · L
payment.type: CASH · BANKNOTE · CARD · CHECK · SVOUCHER · COMPANY · ORDER · ACCOUNT · FACTORING · COMPENSATION · TRANSFER · WAIVER · KIND · OTHER
buyerIDType: NUIS · ID · PASS · VAT · TAX · SOC · POINTS
selectedProcess: P1 · P2 · P3 · P4 · P5 · P6 · P7 · P8 · P9 · P10 · P11
selectedInvoiceType: 82 · 84 · 325 · 326 · 380 · 383 · 386 · 393 · 394 · 395 · 575 · 623 · 780
selfIssueType: AGREEMENT · DOMESTIC · ABROAD · SELF · OTHER
pdfType: A4 · receipt · eInvoice

07 · Abschlussvertrag

Kennungen prüfen, bevor Erfolg gemeldet wird

Eine erfolgreiche HTTP-Antwort kann einen noch unvollständigen externen Vorgang beschreiben. Entscheiden Sie anhand der Kennungen.

Vorgang	Vollständig wenn	Wenn unvollständig
Normale Rechnung / Storno	`fic vorhanden`	Mit gleicher docId wiederherstellen.
E-Rechnung / Storno	`fic und eic vorhanden`	Status mit gleicher docId abfragen.
Kassenvorgang	`fcdc vorhanden`	Vorgang mit gleicher docId wiederholen.
PDF	`base64 vorhanden`	Nach Abschluss der Rechnung wiederholen.

Fehlerentscheidung

Error	Wiederholbar	Aktion
`400 Validierung / Feld`	Nein	Anfrage korrigieren.
`401 Unauthorized`	Nach Zugangsdaten	Richtiges Token erneuern und docId behalten.
`cisError env:CLIENT`	Nein	Fiskal- oder Requestdaten korrigieren.
`cisError env:SERVER / otherError`	Ja	Backoff und gleiche docId.
`Timeout / Netzwerk / 502 / 503`	Ja	Zuerst status; nur bei nicht gefunden erneut senden.
`Andere Anfrage läuft`	Ja, später	Parallelität stoppen, warten, status abfragen.