easyInvoice - Guida all'Integrazione

Integrazione API Locale & File

Fatturazione Elettronica

Versione 2.3.1 | Aggiornato: 04/2026

Panoramica

Questo documento fornisce una guida completa per l'integrazione con il sistema easyInvoice. Sono supportati due metodi principali:

Integrazione API Locale: Utilizzo di endpoint HTTP con payload JSON
Integrazione File: Utilizzo di file JSON nella directory monitorata

1. Introduzione

easyInvoice è un sistema di fatturazione elettronica progettato per transazioni B2B e conformità fiscale in Albania. Questa guida dimostra come integrare con easyInvoice utilizzando l'integrazione basata su file o chiamate RESTful API.

1.1 Metodi di Integrazione

Integrazione API Locale: Richieste HTTP con payload JSON
Integrazione File: Inserire file JSON nella directory monitorata

1.2 Prerequisiti

Sistema operativo Windows o MacOS (richiesto per l'installazione di easyInvoice)
Installazione e configurazione valida di easyInvoice
Stringa di autorizzazione API configurata (per integrazione API)
Servizio API locale abilitato nelle impostazioni easyInvoice (per integrazione API)
Connettività di rete al servizio locale easyInvoice (per integrazione API)
File watcher configurato (per integrazione file)

2. Integrazione API Locale

2.1 URL Base

http://[server-ip]:port/v1/...

2.2 Headers

Content-Type: application/json
Authorization: [your-authorization-string]

2.3 Endpoint API

Method	Endpoint	Descrizione
`GET`	`/v1`	Test connessione
`POST`	`/v1/invoices/new`	Crea fattura/e
`GET`	`/v1/invoices`	Ottieni tutte le fatture
`GET`	`/v1/invoices/:id`	Ottieni singola fattura
`GET`	`/v1/operators`	Ottieni operatori
`GET`	`/v1/entities`	Ottieni entità

Documentazione Postman

2.4 Formato Risposta

{
  "status": 0,
  "response": {
    "nslf": "9F01C3580F765D733529ED8C2822CA81",
    "nivf": "9775c78c-1363-4469-9b26-e9a19204a0a4",
    "eic": "aae0770c-0e44-4a0a-b8d1-004c2a6eacf4",
    "link": "https://efiskalizimi-app.tatime.gov.al/invoice-check/...",
    "text": "Sukses"
  },
  "docId": "0384a667-ea97-4e53-9e8e-5a234162ca42"
}

status: 0 = Success, 1 = Error
nslf: IIC (Internal Invoice Counter)
nivf: FIC (Fiscal Invoice Counter)
eic: EIC (Electronic Invoice Counter)
link: Invoice verification URL

3. Integrazione File

Inserire i file JSON nella directory monitorata. easyInvoice li elaborerà automaticamente.

Fattura Base con Acquirente

{
  "operatorCode": "gh537ez280",
  "buyer": {
    "buyerIDType": "NUIS",
    "buyerIDNum": "K00000000A",
    "buyerName": "GENERAL DIRECTORATE OF TAXES",
    "buyerAddress": "Rruga Gjin Bue Shpata",
    "buyerTown": "Tirana",
    "buyerCountry": "ALB"
  },
  "articles": [
    {
      "articleId": "1412134",
      "vatCode": "B",
      "name": "Water",
      "soldIn": "cope",
      "price": 150,
      "units": 195
    }
  ],
  "bankDetails": {
    "country": "Albania",
    "countryCode": "AL",
    "currency": "ALL",
    "idNumber": "AL70202310040000000011237412"
  }
}

4. Formato Fattura

Nota Importante

operatorCode - Required for all invoices
buyer - Required with valid NUIS
bankDetails - Required for ACCOUNT payment
docId - Recommended (UUIDv4)

4.1 Fattura Standard con Acquirente

{
  "app": "your-app-name",
  "operatorCode": "gh537ez280",
  "buyer": {
    "buyerIDType": "NUIS",
    "buyerIDNum": "K00000000A",
    "buyerName": "GENERAL DIRECTORATE OF TAXES",
    "buyerAddress": "Rruga Gjin Bue Shpata",
    "buyerTown": "Tirana",
    "buyerCountry": "ALB"
  },
  "articles": [
    {
      "articleId": "1412134",
      "vatCode": "B",
      "name": "Water",
      "soldIn": "cope",
      "price": 150,
      "units": 195
    },
    {
      "articleId": "2412412",
      "vatCode": "B",
      "name": "Cola",
      "soldIn": "cope",
      "price": 200,
      "units": 120
    }
  ],
  "bankDetails": {
    "country": "Albania",
    "countryCode": "AL",
    "currency": "ALL",
    "idNumber": "AL70202310040000000011237412"
  },
  "paymentDeadline": "2025-01-28",
  "supplyPeriod": {
    "start": "2025-01-01",
    "end": "2025-01-28"
  },
  "invoiceNotes": "Test note"
}

4.2 Fattura con Pagamenti Multipli

"payment": [
  {
    "type": "FACTORING",
    "amount": 23500
  },
  {
    "type": "ACCOUNT",
    "bankDetails": [{
      "country": "Albania",
      "countryCode": "AL",
      "currency": "ALL",
      "idNumber": "AL70202310040000000011237412"
    }],
    "amount": 35600
  }
]

4.3 Annullamento Fattura

{
  "invoices": [{
    "docId": "ab4f61ac-d812-4939-80f3-e964fd1a041a",
    "operatorCode": "gh537ez280",
    "invoiceType": "CANCEL",
    "iicRef": "3A0029767862ACE2DDCB70C2E4363C09"
  }]
}

4.4 Campi Specifici easyInvoice

Campo	Tipo	Descrizione
bankDetails	object	Dettagli bancari venditore
paymentDeadline	string	Scadenza pagamento (YYYY-MM-DD)
supplyPeriod	object	Periodo fornitura (start, end)
invoiceNotes	string	Note fattura

4.5 Metodi di Pagamento

Tipo	Categoria	Descrizione
`ACCOUNT`	NONCASH	Bonifico bancario
`FACTORING`	NONCASH	Factoring
`COMPENSATION`	NONCASH	Compensazione
`KIND`	NONCASH	Pagamento in natura (clearing)
`OTHER`	NONCASH	Altro, non contanti

5. Documento di Trasporto (WTN)

5.1 Struttura WTN

{
  "app": "your-app-name",
  "invoiceType": "WTN",
  "articles": [
    {
      "articleId": "12344412",
      "name": "Water",
      "soldIn": "cope",
      "cost": 50.4121,
      "units": 10.192
    },
    {
      "articleId": "2341234",
      "name": "Bread",
      "soldIn": "cope",
      "cost": 150.245,
      "units": 3.142
    }
  ],
  "wtnOptions": {
    "transaction": "TRANSFER",
    "vehicleOwnership": "OWNER",
    "vehiclePlate": "AA293BB",
    "startPoint": "STORE",
    "startAddress": "Lunder",
    "startCity": "Tirana",
    "startDate": "2025-01-12",
    "startTime": "22:55",
    "destinationPoint": "STORE",
    "destinationCity": "Durres",
    "destinationAddress": "Test Street",
    "destinationDate": "2025-01-14",
    "destinationTime": "21:32",
    "areGoodsFlammable": true,
    "isEscortRequired": false,
    "packagingType": "Box",
    "packagesNumber": "24",
    "itemsNumber": "12"
  }
}

5.2 Opzioni WTN

Campo	Valori Possibili	Descrizione
transaction	TRANSFER, SALE, EXAMINATION, DISPOSAL, RETURN	Tipo transazione
vehicleOwnership	OWNER, THIRD_PARTY	Proprietà veicolo
startPoint	STORE, WAREHOUSE, OTHER	Punto di partenza
destinationPoint	STORE, WAREHOUSE, OTHER	Punto di destinazione

6. Riferimento Campi

6.1 Dettagli Bancari

Campo	Descrizione	Esempio
country	Nome paese	Albania
countryCode	Codice ISO 2 lettere	AL
currency	Codice valuta	ALL, EUR
idNumber	IBAN	AL70202310040000000011237412

6.2 Periodo Fornitura

"supplyPeriod": {
  "start": "2025-01-01",
  "end": "2025-01-28"
}

6.3 Codici Errore

Codice	Tipo	Messaggio
E1000	NOT_FOUND_ERROR	Risorsa non trovata
E1001	ALREADY_EXISTS_ERROR	Risorsa già esistente
E1002	FIELDS_VALIDATION_ERROR	Errore validazione campi
E1300	INVOICE_ERROR	Impossibile generare fattura
E9800	CIS_ERROR	Errore da CIS

7. Best Practices

7.1 Linee Guida Generali

Validare i Dati: Validare sempre la struttura JSON prima dell'invio
Gestire gli Errori: Implementare una corretta gestione degli errori per le transazioni fallite
Salvare IIC: Conservare l'IIC restituito (nslf) per riferimento futuro e annullamenti
Affidabilità Rete: Per l'integrazione API, implementare logica di retry
Account Demo: Richiedere un account demo allo staff di supporto per testare l'integrazione
ID Documento: Utilizzare formato UUIDv4 per campi docId personalizzati per garantire unicità

7.2 Best Practices Integrazione File

Utilizzare nomi file univoci per evitare conflitti
Monitorare i file di risposta per i risultati dell'elaborazione
Implementare meccanismi di blocco file per prevenire letture parziali
Pulire regolarmente i file elaborati
Includere sempre il campo app per identificare l'applicazione

7.3 Best Practices Integrazione API Locale

Utilizzare connection pooling per migliori prestazioni
Implementare backoff esponenziale per i retry
Registrare tutte le richieste e risposte per il debug
Configurare timeout di rete appropriati
Assicurare la connettività di rete al servizio easyPos

8. Risoluzione Problemi

8.1 File Non Elaborato

Verificare i permessi del file
Verificare la validità della sintassi JSON
Assicurarsi che il file sia completamente scritto prima che easyPos lo legga
Controllare lo stato del servizio easyPos
Verificare che il campo app sia presente

8.2 Errori Connessione API

Verificare la connettività di rete al server easyPos
Controllare le impostazioni del firewall
Confermare URL e porta dell'endpoint corretti
Validare la configurazione della stringa di autorizzazione
Assicurarsi che il servizio API locale sia abilitato nelle impostazioni easyPos

8.3 Errori Dati Non Validi

Validare che tutti i campi obbligatori siano presenti
Verificare che i tipi di dati corrispondano alle specifiche
Verificare che i codici IVA siano validi
Assicurarsi che gli importi siano formattati correttamente

9. Checklist Integrazione

9.1 Setup

☐ Software installato e configurato
☐ Account demo disponibile
☐ Stringa di autorizzazione configurata
☐ Metodo di integrazione selezionato (File o API)

9.2 Sviluppo

☐ Struttura JSON implementata
☐ Gestione errori implementata
☐ Elaborazione risposta implementata

9.3 Testing

☐ Fattura base testata
☐ Fattura con acquirente testata
☐ Annullamento testato
☐ Scenari di errore testati

Nota Importante

Per testare l'integrazione, richiedere un account demo allo staff di supporto.