easyInvoice - Integration Guide

1. Introduction

easyInvoice is an electronic invoicing system designed for B2B transactions and fiscal compliance in Albania. This guide demonstrates how to integrate with easyInvoice using either file-based integration or RESTful API calls.

1.1 Integration Methods

1. Local API Integration: HTTP requests with JSON payloads
2. File Integration: Drop JSON files into a watched directory

1.2 Prerequisites

• Windows or MacOS operating system (required for easyInvoice installation)
• Valid easyInvoice installation and configuration
• API authorization string configured (for API integration)
• Local API service enabled in easyInvoice settings (for API integration)
• Network connectivity to easyInvoice local service (for API integration)
• File watcher configured (for file integration)

2. Local API Integration

2.1 Base URL

2.2 Headers

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

2.3 API Endpoints

2.4 Response Format

{
  "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. File Integration

Place JSON files in the watched directory. easyInvoice will process them automatically.

Basic Invoice with Buyer

{
  "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. Invoice Format

4.1 Standard Invoice with Buyer

{
  "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 Invoice with Multiple Payments

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

4.3 Invoice Cancellation

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

4.4 easyInvoice-Specific Fields

4.5 Payment Methods

5. Warehouse Transfer Note (WTN)

5.1 WTN Structure

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

6. Field Reference

6.1 Bank Details

6.2 Supply Period

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

6.3 Error Codes

© ESDP - easyInvoice Integration Guide v2.3.0