01 · API-Überblick

Fiskalisierung, Verkäufe und Einkäufe in einer API

Integrieren Sie Fiskalisierung und elektronische Rechnungsstellung in Albanien mit easyPos. Erstellen Sie Rechnungen, verwalten Sie Kassenbestände und greifen Sie über eine REST-API auf Verkäufe und Einkäufe Ihres Unternehmens zu.

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; der Lieferant in buyer wird Verkäufer und das Unternehmen wird Käufer. 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`	`SupplyPeriod? · start <= end · same calendar month`
`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?`
`supplyPeriod`	`SupplyPeriod? (inherits from original when omitted)`

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"
  }
]

POST/utilities/cis-invoices/salesCIS-Verkäufe · Verkaufsrechnungen des Unternehmens aus CIS abrufen. Daten umfassen ganze Tage; ToDate darf nicht vor FromDate liegen. Ohne Daten gilt der aktuelle Monat; FIC liefert auch Positionen.

Hilfsfunktionen#cis-sales

Erforderlich: none · body optional
Regeln: current month by default · up to 1000/page · FIC returns Items · CIS scalar values are strings

Request-Felder

Feld	Typ
`FromDate`	`string(date)? · YYYY-MM-DD · default: first day of current month`
`ToDate`	`string(date)? · YYYY-MM-DD · default: last day of current month`
`Page`	`integer? · minimum: 1 · default: 1`
`FIC`	`string(uuid)? · ignores FromDate, ToDate and Page`

Response-Felder

Feld	Typ
`[]`	`CisInvoice[] · empty when no invoice is found`
`[].TypeOfInv`	`CASH \| NONCASH?`
`[].IsSimplifiedInv`	`'true' \| 'false'?`
`[].IsBadDeb`	`'true' \| 'false'?`
`[].TypeOfSelfIss`	`string?`
`[].IssueDateTime`	`string?`
`[].SendDateTime`	`string?`
`[].InvNum`	`string?`
`[].InvOrdNum`	`string?`
`[].TCRCode`	`string?`
`[].IsIssuerInVAT`	`'true' \| 'false'?`
`[].TaxFreeAmt`	`string?`
`[].MarkUpAmt`	`string?`
`[].GoodsExAmt`	`string?`
`[].TotPriceWoVAT`	`string?`
`[].TotVATAmt`	`string?`
`[].TotPrice`	`string?`
`[].OperatorCode`	`string?`
`[].BusinUnitCode`	`string?`
`[].SoftCode`	`string?`
`[].IIC`	`string?`
`[].IICSignature`	`string?`
`[].FIC`	`string(uuid)?`
`[].IsReverseCharge`	`'true' \| 'false'?`
`[].PayDeadline`	`string(date)?`
`[].PayMethods`	`{ Type?: string; Amt?: string; CompCard?: string; Vouchers?: object[] }[]?`
`[].Seller`	`CisParty?`
`[].Buyer`	`CisParty?`
`[].Currency`	`{ Code?: string; ExRate?: string; IsBuying?: string }?`
`[].SupplyDateOrPeriod`	`{ Start?: string(date); End?: string(date) }?`
`[].CorrectiveInv`	`{ IICRef?: string; IssueDateTime?: string; Type?: string }?`
`[].BadDebtInv`	`{ IICRef?: string; IssueDateTime?: string }?`
`[].IsEinvoice`	`'true' \| 'false'?`
`[].EIC`	`string(uuid)?`
`[].SameTaxes`	`object[]? · numeric values are strings`
`[].Fees`	`{ Type?: string; Amt?: string }[]?`
`[].SumInvIICRefs`	`{ IIC?: string; IssueDateTime?: string }[]?`
`[].Items`	`CisInvoiceItem[]? · returned only for FIC lookup`

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/utilities/cis-invoices/sales' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "FromDate": "2026-09-01",
  "ToDate": "2026-09-30",
  "Page": 1
}'

Beispielantwort

[
  {
    "TypeOfInv": "NONCASH",
    "IssueDateTime": "2026-09-15T12:41:32+02:00",
    "InvNum": "12/2026/xx123xx123",
    "InvOrdNum": "12",
    "TotPriceWoVAT": "100.00",
    "TotVATAmt": "20.00",
    "TotPrice": "120.00",
    "IIC": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
    "FIC": "2ed48eff-f3d0-4315-a2a5-16618c63ad0b",
    "IsIssuerInVAT": "true",
    "IsEinvoice": "false",
    "Seller": {
      "IDType": "NUIS",
      "IDNum": "BUSINESS_NIPT",
      "Name": "Business Demo SHPK"
    },
    "Buyer": {
      "IDType": "NUIS",
      "IDNum": "BUYER_NIPT",
      "Name": "Buyer Demo SHPK"
    },
    "PayMethods": [
      {
        "Type": "ACCOUNT",
        "Amt": "120.00"
      }
    ],
    "SameTaxes": [
      {
        "NumOfItems": "1",
        "PriceBefVAT": "100.00",
        "VATRate": "20.00",
        "VATAmt": "20.00"
      }
    ]
  }
]

POST/utilities/cis-invoices/purchasesCIS-Einkäufe · Lieferantenrechnungen aus CIS abrufen, bei denen das Unternehmen Käufer ist. Bis zu 1.000 Rechnungen pro Seite; ohne Treffer wird ein leeres Array zurückgegeben. FIC ignoriert Daten und Page.

Hilfsfunktionen#cis-purchases

Erforderlich: none · body optional
Regeln: current month by default · up to 1000/page · FIC returns Items · CIS scalar values are strings

Request-Felder

Feld	Typ
`FromDate`	`string(date)? · YYYY-MM-DD · default: first day of current month`
`ToDate`	`string(date)? · YYYY-MM-DD · default: last day of current month`
`Page`	`integer? · minimum: 1 · default: 1`
`FIC`	`string(uuid)? · ignores FromDate, ToDate and Page`

Response-Felder

Feld	Typ
`[]`	`CisInvoice[] · empty when no invoice is found`
`[].TypeOfInv`	`CASH \| NONCASH?`
`[].IsSimplifiedInv`	`'true' \| 'false'?`
`[].IsBadDeb`	`'true' \| 'false'?`
`[].TypeOfSelfIss`	`string?`
`[].IssueDateTime`	`string?`
`[].SendDateTime`	`string?`
`[].InvNum`	`string?`
`[].InvOrdNum`	`string?`
`[].TCRCode`	`string?`
`[].IsIssuerInVAT`	`'true' \| 'false'?`
`[].TaxFreeAmt`	`string?`
`[].MarkUpAmt`	`string?`
`[].GoodsExAmt`	`string?`
`[].TotPriceWoVAT`	`string?`
`[].TotVATAmt`	`string?`
`[].TotPrice`	`string?`
`[].OperatorCode`	`string?`
`[].BusinUnitCode`	`string?`
`[].SoftCode`	`string?`
`[].IIC`	`string?`
`[].IICSignature`	`string?`
`[].FIC`	`string(uuid)?`
`[].IsReverseCharge`	`'true' \| 'false'?`
`[].PayDeadline`	`string(date)?`
`[].PayMethods`	`{ Type?: string; Amt?: string; CompCard?: string; Vouchers?: object[] }[]?`
`[].Seller`	`CisParty?`
`[].Buyer`	`CisParty?`
`[].Currency`	`{ Code?: string; ExRate?: string; IsBuying?: string }?`
`[].SupplyDateOrPeriod`	`{ Start?: string(date); End?: string(date) }?`
`[].CorrectiveInv`	`{ IICRef?: string; IssueDateTime?: string; Type?: string }?`
`[].BadDebtInv`	`{ IICRef?: string; IssueDateTime?: string }?`
`[].IsEinvoice`	`'true' \| 'false'?`
`[].EIC`	`string(uuid)?`
`[].SameTaxes`	`object[]? · numeric values are strings`
`[].Fees`	`{ Type?: string; Amt?: string }[]?`
`[].SumInvIICRefs`	`{ IIC?: string; IssueDateTime?: string }[]?`
`[].Items`	`CisInvoiceItem[]? · returned only for FIC lookup`

Request-Body

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/utilities/cis-invoices/purchases' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "FromDate": "2026-09-01",
  "ToDate": "2026-09-30",
  "Page": 1
}'

Beispielantwort

[
  {
    "TypeOfInv": "NONCASH",
    "IssueDateTime": "2026-09-15T12:41:32+02:00",
    "InvNum": "12/2026/xx123xx123",
    "InvOrdNum": "12",
    "TotPriceWoVAT": "100.00",
    "TotVATAmt": "20.00",
    "TotPrice": "120.00",
    "IIC": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
    "FIC": "2ed48eff-f3d0-4315-a2a5-16618c63ad0b",
    "IsIssuerInVAT": "true",
    "IsEinvoice": "false",
    "Seller": {
      "IDType": "NUIS",
      "IDNum": "SUPPLIER_NIPT",
      "Name": "Supplier Demo SHPK"
    },
    "Buyer": {
      "IDType": "NUIS",
      "IDNum": "BUSINESS_NIPT",
      "Name": "Business Demo SHPK"
    },
    "PayMethods": [
      {
        "Type": "ACCOUNT",
        "Amt": "120.00"
      }
    ],
    "SameTaxes": [
      {
        "NumOfItems": "1",
        "PriceBefVAT": "100.00",
        "VATRate": "20.00",
        "VATAmt": "20.00"
      }
    ]
  }
]

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`	`SupplyPeriod`	Optional	start <= end; dates 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 for P4 · <= invoice total · 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	non-negative unit price including VAT; credit notes use negative units
`units`	`number`	Erforderlich	quantity; negative for corrective invoices
`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

CancelInvoiceRequest10

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
`supplyPeriod`	`SupplyPeriod`	Optional	inherits from original invoice when omitted

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

SupplyPeriod2

Feld	Typ	Anforderung	Regeln
`start`	`string(date)`	Erforderlich	YYYY-MM-DD; must not follow end; both dates must be in the same calendar month
`end`	`string(date)`	Erforderlich	YYYY-MM-DD; must not precede start; both dates must be in the same calendar month

GetCisInvoicesRequest4

Feld	Typ	Anforderung	Regeln
`FromDate`	`string(date)`	Optional	YYYY-MM-DD at 00:00:00; defaults to first day of current month; ignored with FIC
`ToDate`	`string(date)`	Optional	YYYY-MM-DD through 23:59:59; defaults to last day of current month; must not precede FromDate; ignored with FIC
`Page`	`integer`	Optional	minimum 1; default 1; up to 1000 invoices per page; ignored with FIC
`FIC`	`string(uuid)`	Optional	UUID; returns full invoice with Items; other fields are ignored and not validated

CisInvoice61

Feld	Typ	Anforderung	Regeln
`TypeOfInv`	`string(enum)`	Optional	CASH \| NONCASH
`IsSimplifiedInv`	`string(enum)`	Optional	true \| false
`IsBadDeb`	`string(enum)`	Optional	true \| false
`TypeOfSelfIss`	`string`	Optional	Self-issue type
`IssueDateTime`	`string`	Optional	Invoice issue date and time
`SendDateTime`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`InvNum`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`InvOrdNum`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`TCRCode`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`IsIssuerInVAT`	`string(enum)`	Optional	true \| false
`TaxFreeAmt`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`MarkUpAmt`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`GoodsExAmt`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`TotPriceWoVAT`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`TotVATAmt`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`TotPrice`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`OperatorCode`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`BusinUnitCode`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`SoftCode`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`IIC`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`IICSignature`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`FIC`	`string(uuid)`	Optional	CIS scalar value; numeric and boolean values remain strings
`IsReverseCharge`	`string(enum)`	Optional	true \| false
`PayDeadline`	`string(date)`	Optional	CIS scalar value; numeric and boolean values remain strings
`IsEinvoice`	`string(enum)`	Optional	true \| false
`EIC`	`string(uuid)`	Optional	CIS scalar value; numeric and boolean values remain strings
`Seller`	`CisParty`	Optional
`Buyer`	`CisParty`	Optional
`Currency`	`object`	Optional
`Currency.Code`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`Currency.ExRate`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`Currency.IsBuying`	`string(enum)`	Optional	true \| false
`SupplyDateOrPeriod`	`object`	Optional
`SupplyDateOrPeriod.Start`	`string(date)`	Optional	CIS scalar value; numeric and boolean values remain strings
`SupplyDateOrPeriod.End`	`string(date)`	Optional	CIS scalar value; numeric and boolean values remain strings
`CorrectiveInv`	`object`	Optional
`CorrectiveInv.IICRef`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`CorrectiveInv.IssueDateTime`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`CorrectiveInv.Type`	`string(enum)`	Optional	CORRECTIVE \| DEBIT \| CREDIT
`BadDebtInv`	`object`	Optional
`BadDebtInv.IICRef`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`BadDebtInv.IssueDateTime`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`PayMethods`	`object[]`	Optional
`PayMethods[].Type`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`PayMethods[].Amt`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`PayMethods[].CompCard`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`PayMethods[].Vouchers`	`object[]`	Optional
`PayMethods[].Vouchers[].Num`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`Fees`	`object[]`	Optional
`Fees[].Type`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`Fees[].Amt`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`SameTaxes`	`object[]`	Optional
`SameTaxes[].NumOfItems`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`SameTaxes[].PriceBefVAT`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`SameTaxes[].VATRate`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`SameTaxes[].ExemptFromVAT`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`SameTaxes[].VATAmt`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`SumInvIICRefs`	`object[]`	Optional
`SumInvIICRefs[].IIC`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`SumInvIICRefs[].IssueDateTime`	`string`	Optional	CIS scalar value; numeric and boolean values remain strings
`Items`	`CisInvoiceItem[]`	Optional	Returned only for FIC lookup; omitted from date-range lists

CisParty6

Feld	Typ	Anforderung	Regeln
`IDType`	`string`	Optional	Party identifier type
`IDNum`	`string`	Optional	Party identifier
`Name`	`string`	Optional	Party name
`Address`	`string`	Optional	Party address
`Town`	`string`	Optional	Party town
`Country`	`string`	Optional	Country code as returned by CIS

CisInvoiceItem15

Feld	Typ	Anforderung	Regeln
`N`	`string`	Optional	Item name
`C`	`string`	Optional	Item code
`U`	`string`	Optional	Unit of measure as returned by CIS
`Q`	`string`	Optional	Quantity as a string
`UPB`	`string`	Optional	Unit price excluding VAT as a string
`UPA`	`string`	Optional	Unit price including VAT as a string
`R`	`string`	Optional	Discount percentage as a string
`RR`	`string(enum)`	Optional	Whether the discount reduces the base price; true \| false
`PB`	`string`	Optional	Line total excluding VAT as a string
`VR`	`string`	Optional	VAT rate (%) as a string
`VA`	`string`	Optional	Line VAT amount as a string
`PA`	`string`	Optional	Line total including VAT as a string
`EX`	`string`	Optional	VAT exemption reason
`IN`	`string(enum)`	Optional	Investment item flag; true \| false
`VS`	`object`	Optional	Sold vouchers; CIS may return additional fields

Ü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": "ALXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "name": "Shitësi SHPK",
          "bankName": "Banka XYZ",
          "swift_code": "ABCDEFGH",
          "country": "Shqipëri",
          "countryCode": "AL",
          "currency": "ALL"
        }
      ]
    }
  ]
}

Betriebliche Klarstellungen

Feld	Regeln
`Gutschriften`	price bleibt nicht negativ; negative units mit correctiveInvoice verwenden. Negative Stückpreise werden bei der Fiskalprüfung abgelehnt.
`Bargeldlose Käufer`	Den passenden Identifikatortyp verwenden. Eine Unternehmens-NIPT darf nicht als ID übermittelt werden. Bargeldlose Verkäufe an NUIS-Käufer erfordern E-Rechnungen.
`Währungssummen`	Preise und Zahlungen im Request verwenden die Rechnungswährung. totalPrice und Steuersummen der Antwort werden nach exRate in ALL ausgegeben.
`Demo-Selbstfakturierung`	Am 2026-10-10 wurde SELF vom Fiskalschema abgelehnt. AGREEMENT erfordert upstream eine E-Rechnung; diese API verbietet isEinvoice mit SELFISSUE. DOMESTIC benötigt einen geeigneten inländischen Lieferanten.
`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.