01 · Prima richiesta

Dal token alla fattura fiscale

Usa prima l’ambiente di sviluppo. Azienda e dispositivo fiscale derivano dal token; il body contiene solo i dati del documento.

01
Ottieni le credenziali
Richiedi un token registrato per ambiente, azienda e dispositivo.
02
Crea un docId
Genera e salva un identificatore stabile prima della prima richiesta.
03
Registra e verifica
Invia la fattura e controlla gli identificatori, non solo HTTP 200.

Fattura ordinaria minima

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

Risposta completata

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

02 · Accesso

Autenticazione e header

Ogni endpoint richiede un bearer token. Sostituisci il valore di esempio di integration-app con l’identificatore stabile assegnato alla tua integrazione e mantienilo invariato in ogni richiesta.

Header	Requisito	Scopo
`Authorization`	Obbligatorio	Bearer token dell’ambiente selezionato.
`Content-Type`	Obbligatorio	Usa application/json per ogni richiesta.
`integration-app`	Consigliato	Sostituisci your-client-name o erp-x con l’identificatore assegnato alla tua integrazione.

03 · Protocollo di recupero

docId è la chiave anti-duplicazione

Scegli docId nel tuo sistema prima dell’invio. Riutilizzarlo continua la stessa operazione fiscale e non deve creare una seconda fattura.

Genera una volta: 5–200 caratteri, univoco per documento.
Salva prima del POST: Salva atomicamente docId, body immutabile e ID locale.
Riusa nel recupero: Timeout, perdita connessione, 502/503 e fattura incompleta mantengono lo stesso docId.
Single flight: Non eseguire register e status in parallelo sullo stesso docId.

Sequenza di recupero sicura

same docId · same body

01
POST register
02
Ambiguo / incompleto
03
Attesa + jitter
04
POST status
05
Completo?
06
Reinvia lo stesso body

1Verifica: fattura normale richiede fic; elettronica richiede fic ed eic.
2Per timeout, rete, 502/503 o risultato incompleto usa backoff esponenziale con jitter, massimo 30 secondi.
3Chiama /invoice/status con lo stesso docId. Se non esiste, ripeti /invoice/register con body e docId identici.
4Non riprovare errori di validazione o env:CLIENT prima di correggere la richiesta.

L’annullamento è un nuovo documento fiscale: usa un nuovo docId. Ogni retry dell’annullamento riusa quel docId.

Schema decisionale del client

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 · Modello documento

Esempi delle richieste fattura

Apri un tipo di documento per vedere richiesta, risposta e identificatori di completamento.

POST NORMALArticoli, pagamenti combinati e buyer opzionale. documentType può mancare. fic

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

Body richiesta

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

Risposta di esempio

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

Campi richiesta

Campo	Tipo
`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`

Campi risposta

Campo	Tipo
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST ORDERSolo articoli; payment è omesso e generato come ORDER. fic

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

Body richiesta

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

Risposta di esempio

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

Campi richiesta

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

Campi risposta

Campo	Tipo
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST SUMMARYConsuma gli iic ORDER inutilizzati; articles è omesso. fic

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

Body richiesta

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

Risposta di esempio

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

Campi richiesta

Campo	Tipo
`docId`	`string`
`documentType`	`string`
`summaryInvoices`	`string[]`
`total`	`number`
`payment`	`object[]`
`payment[].type`	`string`
`payment[].amount`	`number`

Campi risposta

Campo	Tipo
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST SELFISSUERichiede selfIssueType e dati del fornitore in buyer. fic

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

Body richiesta

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

Risposta di esempio

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

Campi richiesta

Campo	Tipo
`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`

Campi risposta

Campo	Tipo
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST EXPORTBuyer estero obbligatorio e codice IVA export configurato. fic

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

Body richiesta

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

Risposta di esempio

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

Campi richiesta

Campo	Tipo
`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`

Campi risposta

Campo	Tipo
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST ELETTRONICA · P1Fattura elettronica standard con buyer NUIS e pagamento non contante. fic + eic

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

Body richiesta

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

Risposta di esempio

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

Campi richiesta

Campo	Tipo
`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`

Campi risposta

Campo	Tipo
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

POST ELETTRONICA · P4Fattura anticipata; prepaidAmount non supera il totale. fic + eic

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

Body richiesta

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

Risposta di esempio

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

Campi richiesta

Campo	Tipo
`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`

Campi risposta

Campo	Tipo
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

POST ELETTRONICA · P9/P10Nota di credito o rettifica riferita a un iic elettronico. fic + eic

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

Body richiesta

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

Risposta di esempio

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

Campi richiesta

Campo	Tipo
`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`

Campi risposta

Campo	Tipo
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

POST ELETTRONICA · P11Flusso di fatturazione elettronica parziale. fic + eic

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

Body richiesta

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

Risposta di esempio

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

Campi richiesta

Campo	Tipo
`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`

Campi risposta

Campo	Tipo
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

POST ANNULLAMENTO · NORMALENuovo docId di annullamento riferito all’iic originale. fic

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

Body richiesta

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

Risposta di esempio

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

Campi richiesta

Campo	Tipo
`docId`	`string`
`correctiveInvoice`	`object`
`correctiveInvoice.iicRef`	`string`
`invoiceNotes`	`string`

Campi risposta

Campo	Tipo
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST ANNULLAMENTO · ELETTRONICOAnnullamento correttivo P10 di una fattura che dispone già di eic. fic + eic

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

Body richiesta

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

Risposta di esempio

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

Campi richiesta

Campo	Tipo
`docId`	`string`
`isEinvoice`	`boolean`
`selectedProcess`	`string`
`correctiveInvoice`	`object`
`correctiveInvoice.iicRef`	`string`
`invoiceNotes`	`string`

Campi risposta

Campo	Tipo
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

Mappa dei processi elettronici

Fiscalizzazione e consegna eInvoice sono fasi separate. La fattura è completa solo con entrambi gli identificatori.

Processo	Tipo predefinito	Regola aggiuntiva
`P1`	`380`	Consegne contro ordini di acquisto basati su un contratto.
`P2`	`380`	Consegne di beni o servizi basate su un contratto.
`P3`	`380`	Consegna contro un ordine di acquisto occasionale.
`P4`	`386`	Pagamento anticipato; prepaidAmount deve essere positivo e non superare il totale.
`P5`	`380`	Pagamento sul posto.
`P6`	`380`	Pagamento prima della consegna.
`P7`	`380`	Fattura con riferimento al documento di spedizione.
`P8`	`380`	Fattura con riferimenti ai documenti di spedizione e ricezione.
`P9`	`384`	Nota di credito o fattura negativa; correctiveInvoice.iicRef deve riferire una fattura con eic.
`P10`	`384`	Correzione o annullamento; correctiveInvoice.iicRef deve riferire una fattura con eic.
`P11`	`326`	Fatturazione parziale e finale.

Codici UNTDID del tipo di fattura

Usa selectedInvoiceType solo quando serve una classificazione specifica. Se omesso, selectedProcess sceglie il codice predefinito indicato sopra.

Codice	Significato
`82`	Fattura per servizi misurati
`84`	Nota di debito per rettifiche finanziarie
`325`	Fattura pro forma
`326`	Fattura parziale
`380`	Fattura commerciale
`383`	Nota di debito
`386`	Fattura di pagamento anticipato
`393`	Fattura ceduta a factoring
`394`	Fattura di leasing
`395`	Fattura di consegna
`575`	Fattura dell’assicuratore
`623`	Fattura dello spedizioniere
`780`	Fattura di trasporto merci

I codici 80, 381, 384, 385 e 389 sono riservati ai tipi assegnati automaticamente dal processo e non possono essere scelti direttamente.

05 · Riferimento HTTP

Endpoint

Tutti gli endpoint usano POST con JSON e gli stessi header.

POST/invoice/registerRegistra fattura · Crea o continua il documento identificato da docId.

Fatture#register-invoice

Obbligatori: docId · articles[]* · payment[]*
Regole: NORMAL | ORDER | SUMMARY | SELFISSUE | EXPORT | eInvoice

Campi richiesta

Campo	Tipo
`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)`

Campi risposta

Campo	Tipo
`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?`

Body richiesta

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

Risposta di esempio

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

POST/invoice/cancelAnnulla fattura · Crea un annullamento correttivo per un iic esistente.

Fatture#cancel-invoice

Obbligatori: new docId · correctiveInvoice.iicRef
Regole: no articles · no payment

Campi richiesta

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

Campi risposta

Campo	Tipo
`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?`

Body richiesta

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

Risposta di esempio

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

POST/invoice/statusStato fattura · Legge lo stato per docId e continua un’operazione incompleta.

Fatture#invoice-status

Obbligatori: docId
Regole: same docId · may continue processing

Campi richiesta

Campo	Tipo
`docId`	`string`

Campi risposta

Campo	Tipo
`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?`

Body richiesta

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

Risposta di esempio

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

POST/invoice/pdfPDF fattura · Genera A4 PDF, ricevuta PNG o eInvoice PDF in base64.

Fatture#invoice-pdf

Obbligatori: iic
Regole: A4 | receipt | eInvoice

Campi richiesta

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

Campi risposta

Campo	Tipo
`base64`	`string`
`lang`	`string?`
`eic`	`string?`

Body richiesta

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

Risposta di esempio

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

POST/balance/initiateInizializza cassa · Registra il saldo iniziale in ALL.

Cassa#initiate-balance

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

Campi richiesta

Campo	Tipo
`docId`	`string`
`amount`	`number`
`notes`	`string?`
`operatorCode`	`string?`

Campi risposta

Campo	Tipo
`orderId`	`string`
`fcdc`	`string?`
`error`	`FiscalError?`

Body richiesta

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

Risposta di esempio

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

POST/balance/depositDeposita contante · Registra contante aggiunto alla cassa in ALL.

Cassa#deposit-balance

Obbligatori: docId · amount
Regole: amount in ALL

Campi richiesta

Campo	Tipo
`docId`	`string`
`amount`	`number`
`notes`	`string?`
`operatorCode`	`string?`

Campi risposta

Campo	Tipo
`orderId`	`string`
`fcdc`	`string?`
`error`	`FiscalError?`

Body richiesta

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

Risposta di esempio

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

POST/balance/withdrawPreleva contante · Registra contante rimosso dalla cassa in ALL.

Cassa#withdraw-balance

Obbligatori: docId · amount
Regole: amount in ALL

Campi richiesta

Campo	Tipo
`docId`	`string`
`amount`	`number`
`notes`	`string?`
`operatorCode`	`string?`

Campi risposta

Campo	Tipo
`orderId`	`string`
`fcdc`	`string?`
`error`	`FiscalError?`

Body richiesta

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

Risposta di esempio

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

POST/utilities/get-taxpayersCerca contribuenti · Cerca per NIPT o ragione sociale.

Utility#get-taxpayers

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

Campi richiesta

Campo	Tipo
`searchTerm`	`string (3–200)`

Campi risposta

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

Body richiesta

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

Risposta di esempio

[
  {
    "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-operatorsElenca operatori · Restituisce gli operatori disponibili.

Utility#get-operators

Obbligatori: none
Regole: authenticated business + device

Campi richiesta

Campo	Tipo
`body`	`{}`

Campi risposta

Campo	Tipo
`[]`	`Operator[]`
`[].name`	`string`
`[].opCode`	`string`

Body richiesta

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

Risposta di esempio

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

06 · Riferimento campi

Catalogo degli schemi API

Espandi uno schema per vedere ogni campo, tipo esatto, requisito e vincolo di validazione.

RegisterInvoiceRequest22

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

Article8

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

Rebate2

Campo	Tipo	Requisito	Regole
`inPercentage`	`number`	Condizionale	mutually exclusive with inValue
`inValue`	`number`	Condizionale	mutually exclusive with inPercentage

Payment3

Campo	Tipo	Requisito	Regole
`type`	`string(enum)`	Obbligatorio	CASH \| BANKNOTE \| CARD \| CHECK \| SVOUCHER \| COMPANY \| ORDER \| ACCOUNT \| FACTORING \| COMPENSATION \| TRANSFER \| WAIVER \| KIND \| OTHER
`amount`	`number`	Obbligatorio	payment sum must equal calculated invoice total
`details`	`PaymentDetail[]`	Condizionale	required and non-empty for ACCOUNT

PaymentDetail7

Campo	Tipo	Requisito	Regole
`idNumber`	`string`	Obbligatorio	IBAN or account number
`name`	`string`	Obbligatorio	account holder
`bankName`	`string`	Obbligatorio	bank name
`swift_code`	`string`	Obbligatorio	SWIFT / BIC
`country`	`string`	Obbligatorio	country name
`countryCode`	`string`	Obbligatorio	ISO 3166-1 alpha-2 · exactly 2 chars
`currency`	`string`	Obbligatorio	ISO 4217 · exactly 3 chars

Buyer7

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

Currency2

Campo	Tipo	Requisito	Regole
`code`	`string`	Opzionale	ISO 4217 · default: ALL
`exRate`	`number`	Condizionale	required when code != ALL · rate against ALL

CorrectiveInvoiceRef2

Campo	Tipo	Requisito	Regole
`iicRef`	`string`	Obbligatorio	existing invoice iic · 32 hex chars
`issueDateTime`	`string(date)`	Opzionale	defaults to original invoice date

CancelInvoiceRequest9

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

StatusInvoiceRequest1

Campo	Tipo	Requisito	Regole
`docId`	`string`	Obbligatorio	same invoice docId · 5–200 chars

InvoicePdfRequest4

Campo	Tipo	Requisito	Regole
`iic`	`string`	Obbligatorio	exactly 32 hexadecimal chars
`pdfType`	`string(enum)`	Opzionale	A4 \| receipt \| eInvoice · default: A4
`paperWidth`	`integer(enum)`	Opzionale	58 \| 80 \| 110 · receipt only · default: 80
`lang`	`string(enum)`	Opzionale	sq \| en

BalanceRequest4

Campo	Tipo	Requisito	Regole
`docId`	`string`	Obbligatorio	5–200 chars · unique per balance operation · no prescribed naming convention
`amount`	`number`	Obbligatorio	amount in ALL
`notes`	`string`	Opzionale	operation note
`operatorCode`	`string`	Opzionale	^[a-z]{2}\d{3}[a-z]{2}\d{3}$

GetTaxpayersRequest1

Campo	Tipo	Requisito	Regole
`searchTerm`	`string`	Obbligatorio	NIPT or business name · 3–200 chars

InvoiceResponse21

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

InvoiceIncompleteResponse2

Campo	Tipo	Requisito	Regole
`orderId`	`string`	Obbligatorio	echoes request docId
`error`	`FiscalError`	Obbligatorio	fiscalization or eInvoice delivery has not completed

Error2

Campo	Tipo	Requisito	Regole
`message`	`string`	Obbligatorio	validation, authorization or domain error message
`field`	`string`	Opzionale	field that failed validation

CisError3

Campo	Tipo	Requisito	Regole
`faultEnv`	`string(enum)`	Opzionale	env:CLIENT \| env:SERVER
`faultString`	`string`	Opzionale	message returned by the tax platform
`faultCode`	`string`	Opzionale	tax-platform error code

FiscalError2

Campo	Tipo	Requisito	Regole
`cisError`	`CisError`	Opzionale	tax platform error
`otherError`	`string`	Opzionale	temporary processing error

PdfResponse2

Campo	Tipo	Requisito	Regole
`base64`	`string`	Obbligatorio	base64 PDF or PNG
`lang`	`string`	Opzionale	document language

EinvoicePdfResponse2

Campo	Tipo	Requisito	Regole
`base64`	`string`	Obbligatorio	official eInvoice PDF encoded as base64
`eic`	`string`	Obbligatorio	electronic invoice identifier

BalanceResponse3

Campo	Tipo	Requisito	Regole
`orderId`	`string`	Obbligatorio	echoes request docId
`fcdc`	`string`	Condizionale	balance-operation completion identifier
`error`	`FiscalError`	Opzionale	processing error

Taxpayer5

Campo	Tipo	Requisito	Regole
`Tin`	`string`	Obbligatorio	taxpayer NIPT
`Name`	`string`	Obbligatorio	registered name
`Address`	`string`	Obbligatorio	registered address
`Town`	`string`	Obbligatorio	registered town
`Country`	`string`	Obbligatorio	ISO 3166-1 alpha-3

Operator2

Campo	Tipo	Requisito	Regole
`name`	`string`	Obbligatorio	operator display name
`opCode`	`string`	Obbligatorio	use as operatorCode in fiscal requests

Mappa dei codici IVA

vatCode dipende dallo stato IVA e dalla configurazione fiscale dell’attività, non solo dall’articolo. Per un’attività soggetta a IVA, la categoria standard al 20% è B; A è la categoria 0% per un’attività non soggetta a IVA.

Codice	Aliquota	Trattamento fiscale
`A`	`0%`	Attività non soggetta a IVA
`B`	`20%`	Aliquota ordinaria
`C`	`0%`	Fornitura esente
`D`	`10%`	Aliquota ridotta
`E`	`6%`	Aliquota ridotta
`J`	`0%`	Esportazione di beni

L’API non restituisce attualmente questa mappatura. Memorizzala nella configurazione dell’integrazione. Non usare altri codici A–L senza una configurazione fiscale confermata.

Pagamento ACCOUNT completo

details deve essere un array non vuoto. Ogni elemento descrive un conto bancario del venditore e richiede tutti i sette campi mostrati qui.

Frammento pagamento

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

Chiarimenti operativi

Campo	Regole
`buyerIDNum · NUIS`	Formato accettato: una lettera, otto cifre, una lettera (^[A-Za-z][0-9]{8}[A-Za-z]$). Normalizza in maiuscolo. Nessun formato NIPT alternativo precedente fa parte del contratto.
`get-taxpayers`	Country usa ISO 3166-1 alpha-3 (ALB per l’Albania). La risposta non include lo stato attivo, passivo o cancellato; usa l’endpoint per cercare e compilare i dati dell’acquirente, non per la verifica finale dello stato fiscale.
`Limiti di frequenza`	Attualmente non è pubblicato un limite numerico. Applica debounce alle ricerche e non inviare una richiesta a ogni tasto premuto.
`balance/initiate`	Invia un solo saldo di apertura riuscito per giorno lavorativo e dispositivo fiscale/TCR autenticato, prima della prima fattura in contanti. Il turno applicativo non è il confine fiscale e non esiste un endpoint di chiusura del saldo.
`docId del saldo`	I valori SHIFT-… sono solo esempi. Usa un identificatore univoco stabile di 5–200 caratteri e riutilizzalo esclusivamente per recuperare la stessa operazione di saldo.

Codici delle unità di misuraScarica l’elenco delle unità di misura supportate e usa il valore del codice come soldIn, per esempio XPP, KGM, LTR o HUR.Scarica l’elenco delle unità (.xlsx)

Enum canonici

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 · Contratto di completamento

Leggi gli identificatori prima di dichiarare successo

Una risposta HTTP positiva può descrivere un’operazione fiscale ancora incompleta. Decidi in base agli identificatori.

Operazione	Completa quando	Se incompleta
Fattura normale / annullamento	`fic presente`	Recupera con lo stesso docId.
Fattura elettronica / annullamento	`fic ed eic presenti`	Interroga status con lo stesso docId.
Transazione cassa	`fcdc presente`	Ripeti operazione e docId.
PDF	`base64 presente`	Ripeti dopo il completamento della fattura.

Tabella decisionale errori

Error	Riprovabile	Azione
`400 validazione / campo`	No	Correggi la richiesta.
`401 Unauthorized`	Dopo le credenziali	Rinnova il token corretto e conserva docId.
`cisError env:CLIENT`	No	Correggi prima i dati fiscali.
`cisError env:SERVER / otherError`	Sì	Backoff e stesso docId.
`Timeout / rete / 502 / 503`	Sì	Prima status; reinvia solo se non trovato.
`Altra richiesta in elaborazione`	Sì, dopo	Ferma il parallelismo, attendi e interroga status.