easyPos - Integrationsleitfaden

1. Einführung

easyPos ist eine Fiskalisierungssoftware für normale und einfache Rechnungen in Albanien. Diese Anleitung zeigt, wie Sie mit easyPos über dateibasierte Integration oder RESTful-API-Aufrufe integrieren können.

1.1 Integrationsmethoden

1. Lokale API-Integration: HTTP-Anfragen mit JSON-Payloads
2. Datei-Integration: JSON- oder TXT-Dateien im überwachten Verzeichnis ablegen

1.2 Voraussetzungen

• Windows- oder MacOS-Betriebssystem (erforderlich für easyPos-Installation)
• Gültige easyPos-Installation und -Konfiguration
• API-Autorisierungsstring konfiguriert (für API-Integration)
• Lokaler API-Dienst in easyPos-Einstellungen aktiviert (für API-Integration)
• Netzwerkverbindung zum lokalen easyPos-Dienst (für API-Integration)
• Datei-Watcher konfiguriert (für Datei-Integration)

2. Lokale API-Integration

2.1 Basis-URL

2.2 Headers

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

2.3 API-Endpunkte

Postman Dokumentation

2.4 Antwortformat

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

• status: 0 = Erfolg, 1 = Fehler, 2 = Ausstehend
• nslf: NSLF - Interner Rechnungszähler (IIC)
• nivf: NIVF - Fiskalische Rechnungsnummer (FIC)
• link: Rechnungsverifizierungs-URL

3. Datei-Integration

3.1 JSON-Format

Legen Sie JSON-Dateien im überwachten Verzeichnis ab. easyPos verarbeitet sie automatisch.

Basisrechnung

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

Rechnung mit Käufer

{
  "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 TXT-Formate

easyPos unterstützt zwei TXT-Dateiformate für die Integration mit Legacy-Fiskalgeräten:

3.2.1 AED-Format

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 IVA-Format

Das IVA-Format verwendet eine strukturierte zeilenbasierte Syntax mit spezifischen Präfixen:

Basisrechnung:

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

Rechnung mit Käufer (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,______,_,__;

Kartenzahlung:

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

Mit Rabatt:

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

4. Zahlungsmethoden

Beispiel mit OTHER-Zahlung

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

5. Feldreferenz

5.1 MwSt-Codes

5.2 ID-Typen

5.4 Rechnungstypen

6. Beispiele

6.1 Rechnung mit mehreren Zahlungen

{
  "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 Rechnung mit Fremdwährung

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

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

6.4 Rechnung mit Banküberweisung

{
  "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 Rechnung mit Artikelrabatt

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

© ESDP - easyPos Integrationsleitfaden v2.3.1