easyPos - Guida all'Integrazione

1. Introduzione

easyPos è un software di fiscalizzazione per fatture normali e semplici in Albania. Questa guida dimostra come integrare con easyPos utilizzando l'integrazione basata su file o chiamate RESTful API.

1.1 Metodi di Integrazione

1. Integrazione API Locale: Richieste HTTP con payload JSON
2. Integrazione File: Inserire file JSON o TXT nella directory monitorata

1.2 Prerequisiti

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

2. Integrazione API Locale

2.1 URL Base

2.2 Headers

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

2.3 Endpoint API

Documentazione Postman

2.4 Formato Risposta

{
  "status": 0,
  "response": {
    "nslf": "C352A1442630779BD016323CB4765331",
    "nivf": "19d7cf18-9f2f-4501-b0d1-48830dfc0750",
    "link": "https://efiskalizimi-app.tatime.gov.al/...",
    "text": "Sukses"
  }
}

• status: 0 = Successo, 1 = Errore, 2 = In attesa
• nslf: NSLF - Contatore Interno Fattura (IIC)
• nivf: NIVF - Numero Fiscale Fattura (FIC)
• link: URL verifica fattura

3. Integrazione File

3.1 Formato JSON

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

Fattura Base

{
  "app": "",
  "articles": [
    {
      "articleId": "ART001",
      "vatCode": "B",
      "name": "Product",
      "soldIn": "cope",
      "price": 500,
      "units": 2
    }
  ]
}

Fattura con Acquirente

{
  "app": "",
  "buyer": {
    "buyerIDType": "NUIS",
    "buyerIDNum": "L12345678A",
    "buyerName": "Test Company",
    "buyerAddress": "Test Street 123",
    "buyerTown": "Tirana",
    "buyerCountry": "ALB"
  },
  "articles": [
    {
      "articleId": "ART001",
      "vatCode": "B",
      "name": "Service",
      "soldIn": "cope",
      "price": 1000,
      "units": 1
    }
  ]
}

3.2 Formati TXT

easyPos supporta due formati file TXT per l'integrazione con dispositivi fiscali legacy:

3.2.1 Formato AED

CLEAR
KEY REG
SALE DPT=1,QTY=1,PRICE=500,DES='Product'
SALE DPT=1,QTY=2,PRICE=300,DES='Service'
SUBTOT
CLOSE TENDER=1

3.2.2 Formato IVA

Il formato IVA utilizza una sintassi strutturata basata su righe con prefissi specifici:

Fattura Base:

H,1,______,_,__;
S,1,______,_,__;"Artikull";500.00;2.00;1;1;1;
T,1,______,_,__;
F,1,______,_,__;

Fattura con Acquirente (NUIS):

H,1,______,_,__;
B,1,______,_,__;"NUIS";"L00000000B";"Buyer Name";"Address";"Tirane";"ALB";
S,1,______,_,__;"Artikull";500.00;2.00;1;1;1;
T,1,______,_,__;
F,1,______,_,__;

Pagamento Carta:

H,1,______,_,__;
$ISWITHCARD=1
S,1,______,_,__;"Artikull";500.00;2.00;1;1;1;
T,1,______,_,__;
F,1,______,_,__;

Con Sconto:

H,1,______,_,__;
S,1,______,_,__;"Product";150.00;2.00;1;1;2;
C,1,______,_,__;2;15.0;
T,1,______,_,__;
F,1,______,_,__;

4. Metodi di Pagamento

Esempio con Pagamento OTHER

{
  "app": "",
  "articles": [
    {
      "articleId": "ART001",
      "vatCode": "B",
      "name": "Product",
      "soldIn": "cope",
      "price": 500,
      "units": 2
    }
  ],
  "payment": {
    "type": "OTHER"
  }
}

5. Riferimento Campi

5.1 Codici IVA

5.2 Tipi ID

5.4 Tipi di Fattura

6. Esempi

6.1 Fattura con Pagamenti Multipli

{
  "app": "",
  "articles": [
    {
      "articleId": "ART001",
      "vatCode": "B",
      "name": "Product",
      "soldIn": "cope",
      "price": 1000,
      "units": 1
    }
  ],
  "payment": [
    { "type": "CASH", "amount": 600 },
    { "type": "CARD", "amount": 400 }
  ]
}

6.2 Fattura con Valuta Estera

{
  "app": "",
  "currency": {
    "code": "EUR",
    "exRate": 100.5
  },
  "articles": [
    {
      "articleId": "ART001",
      "vatCode": "B",
      "name": "Product",
      "soldIn": "cope",
      "price": 50,
      "units": 2
    }
  ],
  "payment": { "type": "CASH" }
}

6.3 Annullamento Fattura

{
  "app": "",
  "invoiceType": "CANCEL",
  "iicRef": "3CA552F6475201847CF63E3499E74727"
}

6.4 Fattura con Bonifico Bancario

{
  "app": "",
  "buyer": {
    "buyerIDType": "NUIS",
    "buyerIDNum": "L12345678A",
    "buyerName": "Company",
    "buyerTown": "Tirana",
    "buyerCountry": "ALB"
  },
  "articles": [
    {
      "articleId": "ART001",
      "vatCode": "B",
      "name": "Service",
      "soldIn": "cope",
      "price": 5000,
      "units": 1
    }
  ],
  "payment": {
    "type": "ACCOUNT",
    "bankDetails": {
      "country": "Albania",
      "countryCode": "AL",
      "currency": "ALL",
      "idNumber": "AL123456789012345678"
    }
  }
}

6.5 Fattura con Sconto Articolo

{
  "app": "",
  "articles": [
    {
      "articleId": "PROD001",
      "vatCode": "B",
      "name": "Product with % Discount",
      "soldIn": "cope",
      "price": 1000,
      "units": 5,
      "rebate": {
        "inPercentage": 10
      }
    }
  ],
  "payment": { "type": "CASH" }
}

© ESDP - easyPos Guida all'Integrazione v2.3.1