easyInvoice - Integrationsleitfaden

1. Einführung

easyInvoice ist ein elektronisches Rechnungssystem für B2B-Transaktionen und Steuerkonformität in Albanien. Diese Anleitung zeigt, wie Sie mit easyInvoice ü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-Dateien im überwachten Verzeichnis ablegen

1.2 Voraussetzungen

• Windows- oder MacOS-Betriebssystem (erforderlich für easyInvoice-Installation)
• Gültige easyInvoice-Installation und -Konfiguration
• API-Autorisierungsstring konfiguriert (für API-Integration)
• Lokaler API-Dienst in easyInvoice-Einstellungen aktiviert (für API-Integration)
• Netzwerkverbindung zum lokalen easyInvoice-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": "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. Datei-Integration

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

Basisrechnung mit Käufer

{
  "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. Rechnungsformat

4.1 Standardrechnung mit Käufer

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

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

4.3 Rechnungsstornierung

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

4.4 easyInvoice-spezifische Felder

4.5 Zahlungsmethoden

5. Warenbegleitschein (WTN)

5.1 WTN-Struktur

{
  "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 WTN-Optionen

6. Feldreferenz

6.1 Bankdaten

6.2 Lieferzeitraum

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

6.3 Fehlercodes

© ESDP - easyInvoice Integrationsleitfaden v2.3.1