01 · Panoramica API
Fiscalizzazione, vendite e acquisti in una API
Integra la fiscalizzazione e la fatturazione elettronica in Albania con easyPos. Crea fatture, gestisci la cassa e accedi alle vendite e agli acquisti della tua azienda tramite una sola API REST.
- 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
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
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
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; il fornitore in buyer diventa il venditore e l’attività diventa l’acquirente. fic
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
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
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
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
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
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
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
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 | SupplyPeriod? · start <= end · same calendar month |
isEinvoice | boolean? |
selectedProcess | P1 | P2 | P3 | P4 | P5 | P6 | P7 | P8 | P9 | P10 | P11? |
selectedInvoiceType | UNTDID code? |
payDeadline | string(date)? |
prepaidAmount | number (conditional) |
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? |
supplyPeriod | SupplyPeriod? (inherits from original when omitted) |
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"
}
]POST/utilities/cis-invoices/salesVendite CIS · Recupera le fatture di vendita dell’attività registrate in CIS. Le date coprono giorni interi; ToDate non può precedere FromDate. Senza date usa il mese corrente; FIC restituisce anche gli articoli.
Utility#cis-sales
- Obbligatori
- none · body optional
- Regole
- current month by default · up to 1000/page · FIC returns Items · CIS scalar values are strings
Campi richiesta
| Campo | Tipo |
|---|---|
FromDate | string(date)? · YYYY-MM-DD · default: first day of current month |
ToDate | string(date)? · YYYY-MM-DD · default: last day of current month |
Page | integer? · minimum: 1 · default: 1 |
FIC | string(uuid)? · ignores FromDate, ToDate and Page |
Campi risposta
| Campo | Tipo |
|---|---|
[] | CisInvoice[] · empty when no invoice is found |
[].TypeOfInv | CASH | NONCASH? |
[].IsSimplifiedInv | 'true' | 'false'? |
[].IsBadDeb | 'true' | 'false'? |
[].TypeOfSelfIss | string? |
[].IssueDateTime | string? |
[].SendDateTime | string? |
[].InvNum | string? |
[].InvOrdNum | string? |
[].TCRCode | string? |
[].IsIssuerInVAT | 'true' | 'false'? |
[].TaxFreeAmt | string? |
[].MarkUpAmt | string? |
[].GoodsExAmt | string? |
[].TotPriceWoVAT | string? |
[].TotVATAmt | string? |
[].TotPrice | string? |
[].OperatorCode | string? |
[].BusinUnitCode | string? |
[].SoftCode | string? |
[].IIC | string? |
[].IICSignature | string? |
[].FIC | string(uuid)? |
[].IsReverseCharge | 'true' | 'false'? |
[].PayDeadline | string(date)? |
[].PayMethods | { Type?: string; Amt?: string; CompCard?: string; Vouchers?: object[] }[]? |
[].Seller | CisParty? |
[].Buyer | CisParty? |
[].Currency | { Code?: string; ExRate?: string; IsBuying?: string }? |
[].SupplyDateOrPeriod | { Start?: string(date); End?: string(date) }? |
[].CorrectiveInv | { IICRef?: string; IssueDateTime?: string; Type?: string }? |
[].BadDebtInv | { IICRef?: string; IssueDateTime?: string }? |
[].IsEinvoice | 'true' | 'false'? |
[].EIC | string(uuid)? |
[].SameTaxes | object[]? · numeric values are strings |
[].Fees | { Type?: string; Amt?: string }[]? |
[].SumInvIICRefs | { IIC?: string; IssueDateTime?: string }[]? |
[].Items | CisInvoiceItem[]? · returned only for FIC lookup |
Body richiesta
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/utilities/cis-invoices/sales' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"FromDate": "2026-09-01",
"ToDate": "2026-09-30",
"Page": 1
}'Risposta di esempio
[
{
"TypeOfInv": "NONCASH",
"IssueDateTime": "2026-09-15T12:41:32+02:00",
"InvNum": "12/2026/xx123xx123",
"InvOrdNum": "12",
"TotPriceWoVAT": "100.00",
"TotVATAmt": "20.00",
"TotPrice": "120.00",
"IIC": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"FIC": "2ed48eff-f3d0-4315-a2a5-16618c63ad0b",
"IsIssuerInVAT": "true",
"IsEinvoice": "false",
"Seller": {
"IDType": "NUIS",
"IDNum": "BUSINESS_NIPT",
"Name": "Business Demo SHPK"
},
"Buyer": {
"IDType": "NUIS",
"IDNum": "BUYER_NIPT",
"Name": "Buyer Demo SHPK"
},
"PayMethods": [
{
"Type": "ACCOUNT",
"Amt": "120.00"
}
],
"SameTaxes": [
{
"NumOfItems": "1",
"PriceBefVAT": "100.00",
"VATRate": "20.00",
"VATAmt": "20.00"
}
]
}
]POST/utilities/cis-invoices/purchasesAcquisti CIS · Recupera le fatture dei fornitori registrate in CIS in cui l’attività è l’acquirente. Fino a 1.000 fatture per pagina; nessun risultato restituisce un array vuoto. FIC ignora date e Page.
Utility#cis-purchases
- Obbligatori
- none · body optional
- Regole
- current month by default · up to 1000/page · FIC returns Items · CIS scalar values are strings
Campi richiesta
| Campo | Tipo |
|---|---|
FromDate | string(date)? · YYYY-MM-DD · default: first day of current month |
ToDate | string(date)? · YYYY-MM-DD · default: last day of current month |
Page | integer? · minimum: 1 · default: 1 |
FIC | string(uuid)? · ignores FromDate, ToDate and Page |
Campi risposta
| Campo | Tipo |
|---|---|
[] | CisInvoice[] · empty when no invoice is found |
[].TypeOfInv | CASH | NONCASH? |
[].IsSimplifiedInv | 'true' | 'false'? |
[].IsBadDeb | 'true' | 'false'? |
[].TypeOfSelfIss | string? |
[].IssueDateTime | string? |
[].SendDateTime | string? |
[].InvNum | string? |
[].InvOrdNum | string? |
[].TCRCode | string? |
[].IsIssuerInVAT | 'true' | 'false'? |
[].TaxFreeAmt | string? |
[].MarkUpAmt | string? |
[].GoodsExAmt | string? |
[].TotPriceWoVAT | string? |
[].TotVATAmt | string? |
[].TotPrice | string? |
[].OperatorCode | string? |
[].BusinUnitCode | string? |
[].SoftCode | string? |
[].IIC | string? |
[].IICSignature | string? |
[].FIC | string(uuid)? |
[].IsReverseCharge | 'true' | 'false'? |
[].PayDeadline | string(date)? |
[].PayMethods | { Type?: string; Amt?: string; CompCard?: string; Vouchers?: object[] }[]? |
[].Seller | CisParty? |
[].Buyer | CisParty? |
[].Currency | { Code?: string; ExRate?: string; IsBuying?: string }? |
[].SupplyDateOrPeriod | { Start?: string(date); End?: string(date) }? |
[].CorrectiveInv | { IICRef?: string; IssueDateTime?: string; Type?: string }? |
[].BadDebtInv | { IICRef?: string; IssueDateTime?: string }? |
[].IsEinvoice | 'true' | 'false'? |
[].EIC | string(uuid)? |
[].SameTaxes | object[]? · numeric values are strings |
[].Fees | { Type?: string; Amt?: string }[]? |
[].SumInvIICRefs | { IIC?: string; IssueDateTime?: string }[]? |
[].Items | CisInvoiceItem[]? · returned only for FIC lookup |
Body richiesta
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/utilities/cis-invoices/purchases' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"FromDate": "2026-09-01",
"ToDate": "2026-09-30",
"Page": 1
}'Risposta di esempio
[
{
"TypeOfInv": "NONCASH",
"IssueDateTime": "2026-09-15T12:41:32+02:00",
"InvNum": "12/2026/xx123xx123",
"InvOrdNum": "12",
"TotPriceWoVAT": "100.00",
"TotVATAmt": "20.00",
"TotPrice": "120.00",
"IIC": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"FIC": "2ed48eff-f3d0-4315-a2a5-16618c63ad0b",
"IsIssuerInVAT": "true",
"IsEinvoice": "false",
"Seller": {
"IDType": "NUIS",
"IDNum": "SUPPLIER_NIPT",
"Name": "Supplier Demo SHPK"
},
"Buyer": {
"IDType": "NUIS",
"IDNum": "BUSINESS_NIPT",
"Name": "Business Demo SHPK"
},
"PayMethods": [
{
"Type": "ACCOUNT",
"Amt": "120.00"
}
],
"SameTaxes": [
{
"NumOfItems": "1",
"PriceBefVAT": "100.00",
"VATRate": "20.00",
"VATAmt": "20.00"
}
]
}
]06 · 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 | SupplyPeriod | Opzionale | start <= end; dates 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 for P4 · <= invoice total · 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 | non-negative unit price including VAT; credit notes use negative units |
units | number | Obbligatorio | quantity; negative for corrective invoices |
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 |
CancelInvoiceRequest10
| 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 |
supplyPeriod | SupplyPeriod | Opzionale | inherits from original invoice when omitted |
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 |
SupplyPeriod2
| Campo | Tipo | Requisito | Regole |
|---|---|---|---|
start | string(date) | Obbligatorio | YYYY-MM-DD; must not follow end; both dates must be in the same calendar month |
end | string(date) | Obbligatorio | YYYY-MM-DD; must not precede start; both dates must be in the same calendar month |
GetCisInvoicesRequest4
| Campo | Tipo | Requisito | Regole |
|---|---|---|---|
FromDate | string(date) | Opzionale | YYYY-MM-DD at 00:00:00; defaults to first day of current month; ignored with FIC |
ToDate | string(date) | Opzionale | YYYY-MM-DD through 23:59:59; defaults to last day of current month; must not precede FromDate; ignored with FIC |
Page | integer | Opzionale | minimum 1; default 1; up to 1000 invoices per page; ignored with FIC |
FIC | string(uuid) | Opzionale | UUID; returns full invoice with Items; other fields are ignored and not validated |
CisInvoice61
| Campo | Tipo | Requisito | Regole |
|---|---|---|---|
TypeOfInv | string(enum) | Opzionale | CASH | NONCASH |
IsSimplifiedInv | string(enum) | Opzionale | true | false |
IsBadDeb | string(enum) | Opzionale | true | false |
TypeOfSelfIss | string | Opzionale | Self-issue type |
IssueDateTime | string | Opzionale | Invoice issue date and time |
SendDateTime | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
InvNum | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
InvOrdNum | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
TCRCode | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
IsIssuerInVAT | string(enum) | Opzionale | true | false |
TaxFreeAmt | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
MarkUpAmt | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
GoodsExAmt | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
TotPriceWoVAT | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
TotVATAmt | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
TotPrice | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
OperatorCode | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
BusinUnitCode | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
SoftCode | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
IIC | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
IICSignature | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
FIC | string(uuid) | Opzionale | CIS scalar value; numeric and boolean values remain strings |
IsReverseCharge | string(enum) | Opzionale | true | false |
PayDeadline | string(date) | Opzionale | CIS scalar value; numeric and boolean values remain strings |
IsEinvoice | string(enum) | Opzionale | true | false |
EIC | string(uuid) | Opzionale | CIS scalar value; numeric and boolean values remain strings |
Seller | CisParty | Opzionale | |
Buyer | CisParty | Opzionale | |
Currency | object | Opzionale | |
Currency.Code | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
Currency.ExRate | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
Currency.IsBuying | string(enum) | Opzionale | true | false |
SupplyDateOrPeriod | object | Opzionale | |
SupplyDateOrPeriod.Start | string(date) | Opzionale | CIS scalar value; numeric and boolean values remain strings |
SupplyDateOrPeriod.End | string(date) | Opzionale | CIS scalar value; numeric and boolean values remain strings |
CorrectiveInv | object | Opzionale | |
CorrectiveInv.IICRef | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
CorrectiveInv.IssueDateTime | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
CorrectiveInv.Type | string(enum) | Opzionale | CORRECTIVE | DEBIT | CREDIT |
BadDebtInv | object | Opzionale | |
BadDebtInv.IICRef | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
BadDebtInv.IssueDateTime | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
PayMethods | object[] | Opzionale | |
PayMethods[].Type | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
PayMethods[].Amt | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
PayMethods[].CompCard | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
PayMethods[].Vouchers | object[] | Opzionale | |
PayMethods[].Vouchers[].Num | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
Fees | object[] | Opzionale | |
Fees[].Type | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
Fees[].Amt | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
SameTaxes | object[] | Opzionale | |
SameTaxes[].NumOfItems | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
SameTaxes[].PriceBefVAT | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
SameTaxes[].VATRate | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
SameTaxes[].ExemptFromVAT | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
SameTaxes[].VATAmt | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
SumInvIICRefs | object[] | Opzionale | |
SumInvIICRefs[].IIC | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
SumInvIICRefs[].IssueDateTime | string | Opzionale | CIS scalar value; numeric and boolean values remain strings |
Items | CisInvoiceItem[] | Opzionale | Returned only for FIC lookup; omitted from date-range lists |
CisParty6
| Campo | Tipo | Requisito | Regole |
|---|---|---|---|
IDType | string | Opzionale | Party identifier type |
IDNum | string | Opzionale | Party identifier |
Name | string | Opzionale | Party name |
Address | string | Opzionale | Party address |
Town | string | Opzionale | Party town |
Country | string | Opzionale | Country code as returned by CIS |
CisInvoiceItem15
| Campo | Tipo | Requisito | Regole |
|---|---|---|---|
N | string | Opzionale | Item name |
C | string | Opzionale | Item code |
U | string | Opzionale | Unit of measure as returned by CIS |
Q | string | Opzionale | Quantity as a string |
UPB | string | Opzionale | Unit price excluding VAT as a string |
UPA | string | Opzionale | Unit price including VAT as a string |
R | string | Opzionale | Discount percentage as a string |
RR | string(enum) | Opzionale | Whether the discount reduces the base price; true | false |
PB | string | Opzionale | Line total excluding VAT as a string |
VR | string | Opzionale | VAT rate (%) as a string |
VA | string | Opzionale | Line VAT amount as a string |
PA | string | Opzionale | Line total including VAT as a string |
EX | string | Opzionale | VAT exemption reason |
IN | string(enum) | Opzionale | Investment item flag; true | false |
VS | object | Opzionale | Sold vouchers; CIS may return additional fields |
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": "ALXXXXXXXXXXXXXXXXXXXXXXXXXX",
"name": "Shitësi SHPK",
"bankName": "Banka XYZ",
"swift_code": "ABCDEFGH",
"country": "Shqipëri",
"countryCode": "AL",
"currency": "ALL"
}
]
}
]
}Chiarimenti operativi
| Campo | Regole |
|---|---|
Note di credito | Mantieni price non negativo e usa units negative con correctiveInvoice. I prezzi unitari negativi sono rifiutati dalla validazione fiscale. |
Acquirenti non contanti | Usa il tipo di identificatore corretto. Il NIPT aziendale non va inviato come ID. Le vendite non contanti ad acquirenti NUIS richiedono fatturazione elettronica. |
Totali in valuta | Prezzi e pagamenti della richiesta sono nella valuta della fattura. totalPrice e totali fiscali della risposta sono in ALL dopo exRate. |
Autofatturazione demo | Il 2026-10-10, SELF è stato rifiutato dallo schema fiscale. AGREEMENT richiede eInvoice a monte, ma questa API vieta isEinvoice con SELFISSUE. DOMESTIC richiede un fornitore nazionale idoneo. |
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. |
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. |
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. |
08 · File sorgente
Lo stesso contratto nei tuoi strumenti
La pagina è il riferimento leggibile; questi file sono download diretti per generatori, client API e agenti.
OpenAPI 3.1.2 JSONJSON
Lo stesso contratto YAML, generato automaticamente per client API e agenti AI.
ScaricaOpenAPI 3.1.2 YAMLYAML
Path, schemi, enum, esempi e server sviluppo/produzione.
ScaricaCollection Postman JSONJSON
Richieste importabili per tutti gli endpoint e tipi di fattura. Solo download.
ScaricaTesto di riferimento AITXT
Regole operative, mappa endpoint e retry per agenti di programmazione.
ScaricaCodici delle unità di misuraXLSX
Scarica l’elenco delle unità di misura supportate e usa il valore del codice come soldIn, per esempio XPP, KGM, LTR o HUR.
ScaricaRichiedi credenziali