01 · First request

From token to fiscal invoice

Use development first. The business and fiscal device are resolved from the access token, so your request body contains only document data.

01
Get credentials
Request an access token registered for the environment, business and device you will use.
02
Create a docId
Generate and persist one stable identifier before the first request.
03
Register and verify
Send the invoice, then evaluate completion identifiers—not HTTP 200 alone.

Minimal normal invoice

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

Completed response

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

02 · Access

Authentication and request headers

Every endpoint requires a bearer token. Replace the example integration-app value with the stable identifier assigned to your integration, then keep that value unchanged across requests.

Header	Requirement	Purpose
`Authorization`	Required	Bearer access token for the selected environment.
`Content-Type`	Required	Use application/json for every request.
`integration-app`	Recommended	Replace your-client-name or erp-x with the stable identifier assigned to your integration.

03 · Recovery protocol

docId is your duplicate-prevention key

Choose docId in your system before sending a document. Reusing it continues the same fiscal operation and returns the same result; it must not create a second invoice.

Generate once: 5–200 characters, unique for each business document.
Persist before POST: Store docId, the immutable request body and your local document ID atomically.
Reuse on recovery: Timeouts, connection loss, 502/503 and incomplete electronic responses keep the same docId.
Single flight: Never run register and status concurrently for one docId.

Safe recovery sequence

same docId · same body

01
POST register
02
Ambiguous or incomplete
03
Wait + jitter
04
POST status
05
Complete?
06
Replay same body

1Check completion: normal invoices require fic; electronic invoices require both fic and eic.
2For a timeout, network error, 502/503 or incomplete result, wait with exponential backoff and jitter, capped at 30 seconds.
3Call /invoice/status with the same docId. If the API says it does not exist, replay /invoice/register with the exact same body and docId.
4Do not retry validation errors or cisError.faultEnv=env:CLIENT until the request is corrected.

Cancellation is a new fiscal document: create a new cancellation docId. Every retry of that cancellation reuses its cancellation docId.

Client-side decision outline

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 · Document model

Invoice request explorer

Open any document type to inspect a complete request, response and the exact completion identifiers your client must check.

POST NORMALArticles, split payments and optional buyer. documentType may be omitted. fic

/invoice/registerCompletion: 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
    }
  ]
}'

Example response

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

Request fields

Field	Type
`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 fields

Field	Type
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST ORDERArticles only; payment is omitted and generated as ORDER. fic

/invoice/registerCompletion: 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"
    }
  ]
}'

Example response

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

Request fields

Field	Type
`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 fields

Field	Type
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST SUMMARYConsumes unused ORDER iic values; articles are omitted. fic

/invoice/registerCompletion: 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
    }
  ]
}'

Example response

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

Request fields

Field	Type
`docId`	`string`
`documentType`	`string`
`summaryInvoices`	`string[]`
`total`	`number`
`payment`	`object[]`
`payment[].type`	`string`
`payment[].amount`	`number`

Response fields

Field	Type
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST SELFISSUERequires selfIssueType and supplier data in buyer. fic

/invoice/registerCompletion: 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
    }
  ]
}'

Example response

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

Request fields

Field	Type
`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 fields

Field	Type
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST EXPORTForeign buyer required; use the export VAT code configured for the business. fic

/invoice/registerCompletion: 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
    }
  ]
}'

Example response

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

Request fields

Field	Type
`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 fields

Field	Type
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST ELECTRONIC · P1Standard electronic invoice with NUIS buyer and non-cash payment. fic + eic

/invoice/registerCompletion: 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"
        }
      ]
    }
  ]
}'

Example response

{
  "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 fields

Field	Type
`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 fields

Field	Type
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

POST ELECTRONIC · P4Prepayment invoice; prepaidAmount must be within the total. fic + eic

/invoice/registerCompletion: 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
    }
  ]
}'

Example response

{
  "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 fields

Field	Type
`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 fields

Field	Type
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

POST ELECTRONIC · P9/P10Credit or corrective invoice referencing an electronic iic. fic + eic

/invoice/registerCompletion: 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
    }
  ]
}'

Example response

{
  "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 fields

Field	Type
`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 fields

Field	Type
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

POST ELECTRONIC · P11Partial electronic invoicing flow. fic + eic

/invoice/registerCompletion: 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
    }
  ]
}'

Example response

{
  "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 fields

Field	Type
`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 fields

Field	Type
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

POST CANCELLATION · NORMALNew cancellation docId referencing the original invoice iic. fic

/invoice/cancelCompletion: 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"
}'

Example response

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

Request fields

Field	Type
`docId`	`string`
`correctiveInvoice`	`object`
`correctiveInvoice.iicRef`	`string`
`invoiceNotes`	`string`

Response fields

Field	Type
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST CANCELLATION · ELECTRONICP10 corrective cancellation of an invoice that already has eic. fic + eic

/invoice/cancelCompletion: 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"
}'

Example response

{
  "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 fields

Field	Type
`docId`	`string`
`isEinvoice`	`boolean`
`selectedProcess`	`string`
`correctiveInvoice`	`object`
`correctiveInvoice.iicRef`	`string`
`invoiceNotes`	`string`

Response fields

Field	Type
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

Electronic invoice process map

Electronic invoices may take longer because fiscalization and eInvoice delivery are separate stages. Treat them as complete only when both identifiers are present.

Process	Default invoice type	Extra rule
`P1`	`380`	Deliveries against purchase orders under a contract.
`P2`	`380`	Deliveries of goods or services under a contract.
`P3`	`380`	Delivery against an occasional purchase order.
`P4`	`386`	Prepayment; prepaidAmount must be greater than 0 and no greater than total.
`P5`	`380`	Payment on the spot.
`P6`	`380`	Payment before delivery.
`P7`	`380`	Invoice referencing a despatch advice.
`P8`	`380`	Invoice referencing both despatch and receipt advice.
`P9`	`384`	Credit note or negative invoice; correctiveInvoice.iicRef must reference an invoice with eic.
`P10`	`384`	Corrective invoice or cancellation; correctiveInvoice.iicRef must reference an invoice with eic.
`P11`	`326`	Partial and final invoicing.

Direct UNTDID invoice type codes

Use selectedInvoiceType only when you need a specific document classification. If omitted, selectedProcess chooses the default shown above.

Code	Meaning
`82`	Metered-services invoice
`84`	Debit note for financial adjustments
`325`	Pro forma invoice
`326`	Partial invoice
`380`	Commercial invoice
`383`	Debit note
`386`	Prepayment invoice
`393`	Factored invoice
`394`	Lease invoice
`395`	Consignment invoice
`575`	Insurer invoice
`623`	Forwarder invoice
`780`	Freight invoice

Codes 80, 381, 384, 385 and 389 are reserved for process-assigned document types and cannot be selected directly.

05 · HTTP reference

Endpoints

All endpoints use POST with JSON and the same authentication headers.

POST/invoice/registerRegister invoice · Create a new fiscal document or continue the document identified by docId.

Invoices#register-invoice

Required: docId · articles[]* · payment[]*
Rules: NORMAL | ORDER | SUMMARY | SELFISSUE | EXPORT | eInvoice

Request fields

Field	Type
`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 fields

Field	Type
`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
    }
  ]
}'

Example response

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

POST/invoice/cancelCancel invoice · Create a corrective cancellation for an existing invoice iic.

Invoices#cancel-invoice

Required: new docId · correctiveInvoice.iicRef
Rules: no articles · no payment

Request fields

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

Response fields

Field	Type
`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"
}'

Example response

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

POST/invoice/statusInvoice status · Read status by docId and continue an incomplete operation.

Invoices#invoice-status

Required: docId
Rules: same docId · may continue processing

Request fields

Field	Type
`docId`	`string`

Response fields

Field	Type
`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"
}'

Example response

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

POST/invoice/pdfInvoice PDF · Generate an A4 PDF, receipt PNG or official electronic invoice PDF as base64.

Invoices#invoice-pdf

Required: iic
Rules: A4 | receipt | eInvoice

Request fields

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

Response fields

Field	Type
`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"
}'

Example response

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

POST/balance/initiateInitiate balance · Report the opening cash balance in ALL.

Cash balance#initiate-balance

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

Request fields

Field	Type
`docId`	`string`
`amount`	`number`
`notes`	`string?`
`operatorCode`	`string?`

Response fields

Field	Type
`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
}'

Example response

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

POST/balance/depositDeposit cash · Report cash added to the till in ALL.

Cash balance#deposit-balance

Required: docId · amount
Rules: amount in ALL

Request fields

Field	Type
`docId`	`string`
`amount`	`number`
`notes`	`string?`
`operatorCode`	`string?`

Response fields

Field	Type
`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"
}'

Example response

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

POST/balance/withdrawWithdraw cash · Report cash removed from the till in ALL.

Cash balance#withdraw-balance

Required: docId · amount
Rules: amount in ALL

Request fields

Field	Type
`docId`	`string`
`amount`	`number`
`notes`	`string?`
`operatorCode`	`string?`

Response fields

Field	Type
`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"
}'

Example response

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

POST/utilities/get-taxpayersSearch taxpayers · Search Albanian taxpayers by NIPT or business name.

Utilities#get-taxpayers

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

Request fields

Field	Type
`searchTerm`	`string (3–200)`

Response fields

Field	Type
`[]`	`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"
}'

Example response

[
  {
    "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-operatorsList operators · Return operators available to the authenticated business and device.

Utilities#get-operators

Required: none
Rules: authenticated business + device

Request fields

Field	Type
`body`	`{}`

Response fields

Field	Type
`[]`	`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 '{}'

Example response

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

06 · Field reference

API schema catalog

Expand a schema to inspect every field, exact data type, requirement level and validation constraint.

RegisterInvoiceRequest22

Field	Type	Requirement	Rules
`docId`	`string`	Required	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[]`	Conditional	required except SUMMARY · minItems: 1
`payment`	`Payment[]`	Conditional	required except ORDER · minItems: 1
`invoiceRebate`	`Rebate`	Optional	percentage or value, never both
`buyer`	`Buyer`	Conditional	required for eInvoice and EXPORT
`correctiveInvoice`	`CorrectiveInvoiceRef`	Conditional	required for P9 / P10
`invoiceNotes`	`string`	Optional	maxLength: 500
`documentType`	`enum`	Optional	NORMAL \| ORDER \| SUMMARY \| SELFISSUE \| EXPORT
`selfIssueType`	`enum`	Conditional	AGREEMENT \| DOMESTIC \| ABROAD \| SELF \| OTHER
`reverseCharge`	`boolean`	Optional	true only for SELFISSUE
`summaryInvoices`	`string[]`	Conditional	SUMMARY only · minItems: 1 · each iic is 32 hex chars
`total`	`number`	Conditional	SUMMARY only · exact referenced ORDER total
`supplyPeriod`	`object`	Optional	start/end in one calendar month
`supplyPeriod.start`	`string(date)`	Conditional	YYYY-MM-DD
`supplyPeriod.end`	`string(date)`	Conditional	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`	Conditional	required for P4 · >= 0 · max 2 decimals

Article8

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

Rebate2

Field	Type	Requirement	Rules
`inPercentage`	`number`	Conditional	mutually exclusive with inValue
`inValue`	`number`	Conditional	mutually exclusive with inPercentage

Payment3

Field	Type	Requirement	Rules
`type`	`string(enum)`	Required	CASH \| BANKNOTE \| CARD \| CHECK \| SVOUCHER \| COMPANY \| ORDER \| ACCOUNT \| FACTORING \| COMPENSATION \| TRANSFER \| WAIVER \| KIND \| OTHER
`amount`	`number`	Required	payment sum must equal calculated invoice total
`details`	`PaymentDetail[]`	Conditional	required and non-empty for ACCOUNT

PaymentDetail7

Field	Type	Requirement	Rules
`idNumber`	`string`	Required	IBAN or account number
`name`	`string`	Required	account holder
`bankName`	`string`	Required	bank name
`swift_code`	`string`	Required	SWIFT / BIC
`country`	`string`	Required	country name
`countryCode`	`string`	Required	ISO 3166-1 alpha-2 · exactly 2 chars
`currency`	`string`	Required	ISO 4217 · exactly 3 chars

Buyer7

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

Currency2

Field	Type	Requirement	Rules
`code`	`string`	Optional	ISO 4217 · default: ALL
`exRate`	`number`	Conditional	required when code != ALL · rate against ALL

CorrectiveInvoiceRef2

Field	Type	Requirement	Rules
`iicRef`	`string`	Required	existing invoice iic · 32 hex chars
`issueDateTime`	`string(date)`	Optional	defaults to original invoice date

CancelInvoiceRequest9

Field	Type	Requirement	Rules
`docId`	`string`	Required	new cancellation id · 5–200 chars
`operatorCode`	`string`	Optional	^[a-z]{2}\d{3}[a-z]{2}\d{3}$
`correctiveInvoice`	`CorrectiveInvoiceRef`	Required	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

Field	Type	Requirement	Rules
`docId`	`string`	Required	same invoice docId · 5–200 chars

InvoicePdfRequest4

Field	Type	Requirement	Rules
`iic`	`string`	Required	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

Field	Type	Requirement	Rules
`docId`	`string`	Required	5–200 chars · unique per balance operation · no prescribed naming convention
`amount`	`number`	Required	amount in ALL
`notes`	`string`	Optional	operation note
`operatorCode`	`string`	Optional	^[a-z]{2}\d{3}[a-z]{2}\d{3}$

GetTaxpayersRequest1

Field	Type	Requirement	Rules
`searchTerm`	`string`	Required	NIPT or business name · 3–200 chars

InvoiceResponse21

Field	Type	Requirement	Rules
`orderId`	`string`	Required	echoes request docId
`fic`	`string`	Conditional	normal completion identifier
`eic`	`string`	Conditional	required with fic for electronic completion
`iic`	`string`	Conditional	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

Field	Type	Requirement	Rules
`orderId`	`string`	Required	echoes request docId
`error`	`FiscalError`	Required	fiscalization or eInvoice delivery has not completed

Error2

Field	Type	Requirement	Rules
`message`	`string`	Required	validation, authorization or domain error message
`field`	`string`	Optional	field that failed validation

CisError3

Field	Type	Requirement	Rules
`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

Field	Type	Requirement	Rules
`cisError`	`CisError`	Optional	tax platform error
`otherError`	`string`	Optional	temporary processing error

PdfResponse2

Field	Type	Requirement	Rules
`base64`	`string`	Required	base64 PDF or PNG
`lang`	`string`	Optional	document language

EinvoicePdfResponse2

Field	Type	Requirement	Rules
`base64`	`string`	Required	official eInvoice PDF encoded as base64
`eic`	`string`	Required	electronic invoice identifier

BalanceResponse3

Field	Type	Requirement	Rules
`orderId`	`string`	Required	echoes request docId
`fcdc`	`string`	Conditional	balance-operation completion identifier
`error`	`FiscalError`	Optional	processing error

Taxpayer5

Field	Type	Requirement	Rules
`Tin`	`string`	Required	taxpayer NIPT
`Name`	`string`	Required	registered name
`Address`	`string`	Required	registered address
`Town`	`string`	Required	registered town
`Country`	`string`	Required	ISO 3166-1 alpha-3

Operator2

Field	Type	Requirement	Rules
`name`	`string`	Required	operator display name
`opCode`	`string`	Required	use as operatorCode in fiscal requests

VAT code map

vatCode depends on the business VAT status and fiscal configuration, not only on the article. For a VAT-registered business, the standard 20% category is B; A is the 0% category for a business that is not subject to VAT.

Code	Rate	Fiscal treatment
`A`	`0%`	Business not subject to VAT
`B`	`20%`	Standard rate
`C`	`0%`	Exempt supply
`D`	`10%`	Reduced rate
`E`	`6%`	Reduced rate
`J`	`0%`	Export of goods

The API does not currently return this mapping. Store it in your integration configuration. Do not use other A–L codes without a confirmed fiscal configuration.

Complete ACCOUNT payment

details must be a non-empty array. Every entry describes one seller bank account and requires all seven fields shown here.

Payment fragment

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

Operational clarifications

Field	Rules
`buyerIDNum · NUIS`	Accepted shape: one letter, eight digits, one letter (^[A-Za-z][0-9]{8}[A-Za-z]$). Normalize to uppercase. No alternative legacy NIPT shape is part of this contract.
`get-taxpayers`	Country uses ISO 3166-1 alpha-3 (ALB for Albania). The response has no active, inactive or deregistered status field; use this endpoint to search and populate buyer data, not as final verification of tax status.
`Rate limiting`	No numeric quota is currently published. Debounce searches and do not send a request for every keystroke.
`balance/initiate`	Send one successful opening balance per business day and authenticated fiscal device/TCR, before its first cash invoice. An application shift is not the fiscal boundary, and there is no balance-close endpoint.
`balance docId`	The SHIFT-… values are examples only. Use any stable unique identifier of 5–200 characters and reuse it only to recover the same balance operation.

Measurement unit codesDownload the supported measurement-unit list and use its code value as soldIn, for example XPP, KGM, LTR or HUR.Download unit-code list (.xlsx)

Canonical 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 · Completion contract

Read identifiers before declaring success

A successful HTTP response can still describe an unfinished external fiscalization operation. Persist the body and decide from the identifiers.

Operation	Complete when	If incomplete
Normal invoice / cancellation	`fic is present`	Recover with the same docId.
Electronic invoice / cancellation	`fic and eic are both present`	Poll status with the same docId.
Balance transaction	`fcdc is present`	Retry the same operation and docId.
PDF	`base64 is present`	Retry after the source invoice is complete.

Error decision table

Error	Retryable	Action
`400 validation / field`	No	Fix the request; unknown top-level fields are rejected.
`401 Unauthorized`	After credentials	Renew the correct environment token, then preserve docId.
`cisError env:CLIENT`	No	Correct the fiscal or request data first.
`cisError env:SERVER / otherError`	Yes	Back off and recover with the same docId.
`Timeout / connection / 502 / 503`	Yes	Status first; replay the immutable request only if not found.
`Another request is processing`	Yes, later	Stop parallel work, wait, then query status.