28
Back to Home

easyInvoice - Integration Guide

Local API & File Integration

Electronic Invoicing

Version 2.3.1 | Updated: 04/2026

Overview

This document provides comprehensive guidance for integrating with the easyInvoice system. Two main methods are supported:

  • Local API Integration: Using HTTP endpoints with JSON payloads
  • File Integration: Using JSON files in the watched directory

Table of Contents

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

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

2.2 Headers

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

2.3 API Endpoints

Method Endpoint Description
GET/v1Test connection
POST/v1/invoices/newCreate invoice(s)
GET/v1/invoicesGet all invoices
GET/v1/invoices/:idGet single invoice
GET/v1/operatorsGet operators
GET/v1/entitiesGet entities
Postman Documentation

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

Important Note

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

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

FieldTypeDescription
bankDetailsobjectSeller's bank details
paymentDeadlinestringPayment deadline (YYYY-MM-DD)
supplyPeriodobjectSupply period (start, end)
invoiceNotesstringInvoice notes

4.5 Payment Methods

TypeCategoryDescription
ACCOUNTNONCASHBank transfer
FACTORINGNONCASHFactoring
COMPENSATIONNONCASHCompensation
KINDNONCASHPayment in kind (clearing)
OTHERNONCASHOther, non-cash

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

FieldPossible ValuesDescription
transactionTRANSFER, SALE, EXAMINATION, DISPOSAL, RETURNTransaction type
vehicleOwnershipOWNER, THIRD_PARTYVehicle ownership
startPointSTORE, WAREHOUSE, OTHERStarting point
destinationPointSTORE, WAREHOUSE, OTHERDestination point

6. Field Reference

6.1 Bank Details

FieldDescriptionExample
countryCountry nameAlbania
countryCodeISO 2-letter codeAL
currencyCurrency codeALL, EUR
idNumberIBANAL70202310040000000011237412

6.2 Supply Period

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

6.3 Error Codes

CodeTypeMessage
E1000NOT_FOUND_ERRORResource not found
E1001ALREADY_EXISTS_ERRORResource already exists
E1002FIELDS_VALIDATION_ERRORField validation error
E1300INVOICE_ERRORCould not generate invoice
E9800CIS_ERRORError from CIS

7. Best Practices

7.1 General Guidelines

  • Validate Data: Always validate JSON structure before sending
  • Handle Errors: Implement proper error handling for failed transactions
  • Store IIC: Save the returned IIC (nslf) for future reference and cancellations
  • Network Reliability: For API integration, implement retry logic
  • Demo Account: Request a demo account from support staff to test your integration
  • Document ID: Use UUIDv4 format for custom docId fields to ensure uniqueness

7.2 File Integration Best Practices

  • Use unique filenames to avoid conflicts
  • Monitor the response files for processing results
  • Implement file locking mechanisms to prevent partial reads
  • Clean up processed files regularly
  • Always include the app field to identify your application

7.3 Local API Integration Best Practices

  • Use connection pooling for better performance
  • Implement exponential backoff for retries
  • Log all requests and responses for debugging
  • Configure proper network timeouts
  • Ensure local network connectivity to easyPos service

8. Troubleshooting

8.1 File Not Processing

  • Check file permissions
  • Verify JSON syntax validity
  • Ensure file is completely written before easyPos reads it
  • Check easyPos service status
  • Verify the app field is present

8.2 API Connection Errors

  • Verify network connectivity to easyPos server
  • Check firewall settings
  • Confirm correct endpoint URL and port
  • Validate authorization string configuration
  • Ensure local API service is enabled in easyPos settings

8.3 Invalid Data Errors

  • Validate all required fields are present
  • Check data types match specifications
  • Verify VAT codes are valid
  • Ensure amounts are properly formatted

9. Integration Checklist

9.1 Setup

  • ☐ Software installed and configured
  • ☐ Demo account available
  • ☐ Authorization string configured
  • ☐ Integration method selected (File or API)

9.2 Development

  • ☐ JSON structure implemented
  • ☐ Error handling implemented
  • ☐ Response processing implemented

9.3 Testing

  • ☐ Basic invoice tested
  • ☐ Invoice with buyer tested
  • ☐ Cancellation tested
  • ☐ Error scenarios tested

Important Note

To test the integration, request a demo account from support staff.

© ESDP - easyInvoice Integration Guide v2.3.1