easyPos - Integration Guide

1. Introduction

easyPos is fiscalization software for normal and simple invoices in Albania. This guide demonstrates how to integrate with easyPos 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 or TXT files into a watched directory

1.2 Prerequisites

• Windows or MacOS operating system (required for easyPos installation)
• Valid easyPos installation and configuration
• API authorization string configured (for API integration)
• Local API service enabled in easyPos settings (for API integration)
• Network connectivity to easyPos 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": "C352A1442630779BD016323CB4765331",
    "nivf": "19d7cf18-9f2f-4501-b0d1-48830dfc0750",
    "link": "https://efiskalizimi-app.tatime.gov.al/...",
    "text": "Sukses"
  }
}

• status: 0 = Success, 1 = Error, 2 = Pending
• nslf: NSLF - Internal Invoice Counter (IIC)
• nivf: NIVF - Fiscal Invoice Number (FIC)
• link: Invoice verification URL

3. File Integration

3.1 JSON Format

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

Basic Invoice

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

Invoice with Buyer

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

easyPos supports two TXT file formats for legacy fiscal device integration:

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

The IVA format uses a structured line-based syntax with specific prefixes:

Basic Invoice:

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

Invoice with Buyer (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,______,_,__;

Card Payment:

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

With Discount:

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

4. Payment Methods

Example with OTHER Payment

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

5. Field Reference

5.1 VAT Codes

5.2 ID Types

5.4 Invoice Types

6. Examples

6.1 Invoice with Multiple Payments

{
  "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 Invoice with Foreign Currency

{
  "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 Invoice Cancellation

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

6.4 Invoice with Bank Transfer

{
  "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 Invoice with Article Rebate

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

© ESDP - easyPos Integration Guide v2.3.0