# easyPos Cloud Fiscalization API — AI integration reference

Canonical human documentation: https://easypos.al/api/cloud
OpenAPI 3.0: https://easypos.al/api/downloads/easypos-cloud-api.openapi.yaml
Postman collection: https://easypos.al/api/downloads/easypos-cloud-api.postman_collection.json

## Environments

- Development: https://api.dev.easypos.al/fiscalisation-service/v1
- Production: https://api.easypos.al/fiscalisation-service/v1

Never send development credentials to production or production credentials to development.

## Authentication

Every request uses:

Authorization: Bearer <access-token>
Content-Type: application/json
integration-app: <stable-client-name>

The bearer token identifies the business and device; do not duplicate those values in the request body. Replace <stable-client-name> with the stable identifier assigned to your integration and keep it unchanged across requests. The integration-app header is optional in the HTTP contract but recommended for traceability.

## docId and idempotent recovery

The client creates docId before its first mutating request and persists it with the immutable request body. It must be unique per business document and 5–200 characters. Reusing the same docId continues the same document and returns the same result; it must never create a second fiscal document.

Normal invoice completion: response contains fic.
Electronic invoice completion: response contains both fic and eic.
Incomplete electronic invoice: response may contain only orderId and error. It is not complete.
Balance transaction completion: response contains fcdc.

On timeout, connection loss, HTTP 502/503, or an incomplete response:

1. Keep the original docId and exact request body.
2. Ensure only one worker is operating on that docId.
3. Wait with exponential backoff and jitter, capped at 30 seconds.
4. POST /invoice/status with {"docId":"<same-docId>"}.
5. If status says the docId does not exist, replay /invoice/register with the exact same body and docId.
6. Stop only when the required completion identifiers are present or a non-retryable validation error is returned.

Do not retry validation errors or cisError.faultEnv=env:CLIENT until the request is fixed. For HTTP 401, obtain a valid token for the selected environment, then continue with the same docId. Do not issue concurrent register/status requests for one docId. Cancellation is a new fiscal document and therefore gets its own new docId; retries of that cancellation reuse the cancellation docId.

## Endpoints

All endpoints are POST and accept application/json.

- /invoice/register — create or continue an invoice, order, summary, self-issued invoice, or export invoice
- /invoice/cancel — create a corrective cancellation for an existing iic
- /invoice/status — retrieve or continue processing by docId
- /invoice/pdf — return A4 PDF, receipt PNG, or official eInvoice PDF as base64
- /balance/initiate — report opening cash balance
- /balance/deposit — report cash deposited into the till
- /balance/withdraw — report cash withdrawn from the till
- /utilities/get-taxpayers — search taxpayers by NIPT or business name
- /utilities/get-operators — list fiscalization operators

## Register invoice rules

RegisterInvoiceRequest has additionalProperties=false. Unknown top-level fields are rejected.

Required for a normal invoice:

- docId
- articles[] with articleId, name, vatCode, price, units, soldIn
- payment[] with type and amount

Important values:

- soldIn uses a UN/CEFACT unit code such as XPP, KGM, LTR, or HUR. Supported list: https://easypos.al/downloads/lista-e-njesive-matese.xlsx
- buyerCountry uses ISO 3166-1 alpha-3, such as ALB.
- buyerCountryCode uses ISO alpha-2, such as AL.
- The sum of payment amounts must equal the calculated invoice total after discounts.
- price is the unit price including VAT.
- currency defaults to {"code":"ALL","exRate":1}; a non-ALL currency requires exRate against ALL.
- operatorCode can be obtained from /utilities/get-operators and is selected automatically when omitted.

VAT code mapping depends on the business VAT status and fiscal configuration, not only on the article:

- A — 0%; business not subject to VAT
- B — 20%; standard rate
- C — 0%; exempt supply
- D — 10%
- E — 6%
- J — 0%; export of goods

The API does not expose an endpoint for this mapping. Store it in the integration configuration. Do not use other A–L codes without a confirmed fiscal configuration. For example, coffee sold at the standard 20% rate by a VAT-registered business uses B; the same article uses A when sold by a business that is not subject to VAT.

Document types when isEinvoice is false:

- NORMAL — ordinary invoice; default.
- ORDER — omit payment; the service creates an ORDER payment.
- SUMMARY — omit articles; provide summaryInvoices[] of unused ORDER iic values and exact total.
- SELFISSUE — provide selfIssueType and supplier details in buyer; only this type permits reverseCharge=true.
- EXPORT — buyer is required and cannot use NUIS; every article must use the business export VAT code.

Electronic invoices set isEinvoice=true and require:

- buyer with buyerIDType=NUIS
- a non-cash payment: ACCOUNT, FACTORING, COMPENSATION, TRANSFER, WAIVER, KIND, or OTHER
- selectedProcess P1–P11; default P1
- ACCOUNT payment details[] containing idNumber, name, bankName, swift_code, country, countryCode, and currency

Electronic process map:

- P1 => type 380; deliveries against purchase orders under a contract
- P2 => type 380; deliveries of goods or services under a contract
- P3 => type 380; delivery against an occasional purchase order
- P4 => type 386; prepayment; prepaidAmount is greater than zero and no greater than the invoice total
- P5 => type 380; payment on the spot
- P6 => type 380; payment before delivery
- P7 => type 380; invoice referencing a despatch advice
- P8 => type 380; invoice referencing both despatch and receipt advice
- P9 => type 384; credit note or negative invoice; correctiveInvoice.iicRef references an electronic invoice with eic
- P10 => type 384; corrective invoice or cancellation; correctiveInvoice.iicRef references an electronic invoice with eic
- P11 => type 326; partial and final invoicing

Direct selectedInvoiceType values:

- 82 metered-services invoice
- 84 debit note for financial adjustments
- 325 pro forma invoice
- 326 partial invoice
- 380 commercial invoice
- 383 debit note
- 386 prepayment invoice
- 393 factored invoice
- 394 lease invoice
- 395 consignment invoice
- 575 insurer invoice
- 623 forwarder invoice
- 780 freight invoice

Values 80, 381, 384, 385, and 389 are accepted only when assigned by the process.

Payment types: CASH, BANKNOTE, CARD, CHECK, SVOUCHER, COMPANY, ORDER, ACCOUNT, FACTORING, COMPENSATION, TRANSFER, WAIVER, KIND, OTHER. CASH is an alias of BANKNOTE. The first payment determines CASH versus NONCASH invoice classification.

Buyer ID types: NUIS, ID, PASS, VAT, TAX, SOC, POINTS. Electronic invoices require NUIS. For buyerIDType=NUIS, trim and normalize buyerIDNum to uppercase, then validate one letter, eight digits, and one letter: ^[A-Za-z][0-9]{8}[A-Za-z]$. There is no alternative NUIS length for natural persons or older entities; use the appropriate ID, PASS, VAT, or TAX type for other identifiers.

## Cash balance operations

Send /balance/initiate once at the start of each workday for the relevant fiscal device, before its first cash invoice. Do not repeat it before each invoice or for every shift in the same day. If a shift change physically changes the till amount, use /balance/deposit for added cash or /balance/withdraw for removed cash. There is no separate shift-close endpoint. A cash invoice may be rejected when the opening balance was not reported.

Balance docId has no required semantic format. Use a UUID or another identifier unique to the operation, and reuse the same docId only when retrying that same request.

## Taxpayer search

/utilities/get-taxpayers accepts searchTerm with at least 3 characters. Country uses ISO 3166-1 alpha-3, for example ALB. The response does not expose active, inactive, or deregistered status, so use it for search and buyer-data completion rather than final tax-status verification. No specific numeric rate limit is published; debounce searches and do not send a request for every keystroke.

## Cancellation

POST /invoice/cancel with a new docId and correctiveInvoice.iicRef. Do not send articles or payments. The original invoice must exist and must not already be corrective. An electronic original must have eic. If isEinvoice and selectedProcess are omitted, electronic cancellation inherits its electronic status and defaults its process to P10. A normal cancellation is complete with fic; an electronic cancellation is complete only with fic and eic.

## PDF

POST /invoice/pdf with iic and one pdfType:

- A4 — base64 PDF; lang is sq or en.
- receipt — base64 PNG; paperWidth is 58, 80, or 110.
- eInvoice — official base64 PDF; source invoice must have eic.

## Field-level schema index

This section is optimized for exact lookup. Each line is:
field path :: data type :: requirement :: validation or business constraint

Array item paths use `[]`, for example `articles[].name`. Unknown top-level request fields are rejected.

### RegisterInvoiceRequest

docId :: string :: required :: 5–200 chars; unique per business document
operatorCode :: string :: optional :: pattern ^[a-z]{2}\d{3}[a-z]{2}\d{3}$
currency :: Currency :: optional :: defaults to ALL / 1
articles :: Article[] :: conditional :: required except SUMMARY; minItems 1
payment :: Payment[] :: conditional :: required except ORDER; minItems 1
invoiceRebate :: Rebate :: optional :: percentage or value, never both
buyer :: Buyer :: conditional :: required for electronic invoices and EXPORT
correctiveInvoice :: CorrectiveInvoiceRef :: conditional :: required for P9 and P10
invoiceNotes :: string :: optional :: maxLength 500
documentType :: string enum :: optional :: NORMAL | ORDER | SUMMARY | SELFISSUE | EXPORT
selfIssueType :: string enum :: conditional :: AGREEMENT | DOMESTIC | ABROAD | SELF | OTHER; SELFISSUE only
reverseCharge :: boolean :: optional :: true only for SELFISSUE
summaryInvoices :: string[] :: conditional :: SUMMARY only; minItems 1; each item is a 32-character hexadecimal iic
total :: number :: conditional :: SUMMARY only; exact sum of referenced ORDER totals
supplyPeriod :: object :: optional :: start and end in the same calendar month
supplyPeriod.start :: string(date) :: conditional :: YYYY-MM-DD
supplyPeriod.end :: string(date) :: conditional :: YYYY-MM-DD
isEinvoice :: boolean :: optional :: default false
selectedProcess :: string enum :: optional :: P1–P11; default P1
selectedInvoiceType :: string enum :: optional :: 82 | 84 | 325 | 326 | 380 | 383 | 386 | 393 | 394 | 395 | 575 | 623 | 780
payDeadline :: string(date) :: optional :: YYYY-MM-DD; current year; not in the past
prepaidAmount :: number :: conditional :: required for P4; >= 0; maximum 2 decimal places

### Article

articleId :: string :: required :: maxLength 100
name :: string :: required :: maxLength 100
vatCode :: string enum :: required :: A | B | C | D | E | F | G | H | I | J | K | L; must match the business fiscal configuration; confirmed mapping above
price :: number :: required :: unit price including VAT
units :: number :: required :: quantity
soldIn :: string :: required :: UN/CEFACT unit code such as XPP, KGM, LTR or HUR; supported list: https://easypos.al/downloads/lista-e-njesive-matese.xlsx
totalPrice :: number :: optional :: defaults to price × units
rebate :: Rebate :: optional :: line-level discount

### Rebate

inPercentage :: number :: conditional :: mutually exclusive with inValue
inValue :: number :: conditional :: mutually exclusive with inPercentage

### Payment

type :: string enum :: required :: CASH | BANKNOTE | CARD | CHECK | SVOUCHER | COMPANY | ORDER | ACCOUNT | FACTORING | COMPENSATION | TRANSFER | WAIVER | KIND | OTHER
amount :: number :: required :: sum of payments equals calculated invoice total
details :: PaymentDetail[] :: conditional :: required and non-empty for ACCOUNT

### PaymentDetail

idNumber :: string :: required :: IBAN or account number
name :: string :: required :: account holder
bankName :: string :: required :: bank name
swift_code :: string :: required :: SWIFT / BIC
country :: string :: required :: country name
countryCode :: string :: required :: ISO 3166-1 alpha-2; exactly 2 chars
currency :: string :: required :: ISO 4217; exactly 3 chars

### Buyer

buyerIDType :: string enum :: required :: NUIS | ID | PASS | VAT | TAX | SOC | POINTS
buyerIDNum :: string :: required :: when buyerIDType is NUIS, pattern ^[A-Za-z][0-9]{8}[A-Za-z]$ after trim and uppercase normalization
buyerName :: string :: required :: buyer legal or display name
buyerAddress :: string :: required :: buyer address
buyerTown :: string :: required :: buyer town
buyerCountry :: string :: required :: ISO 3166-1 alpha-3 such as ALB
buyerCountryCode :: string :: optional :: ISO 3166-1 alpha-2; default AL

### Currency

code :: string :: optional :: ISO 4217; default ALL
exRate :: number :: conditional :: required when code is not ALL; rate against ALL

### CorrectiveInvoiceRef

iicRef :: string :: required :: existing invoice iic; 32 hexadecimal chars
issueDateTime :: string(date) :: optional :: defaults to original invoice date

### CancelInvoiceRequest

docId :: string :: required :: new cancellation id; 5–200 chars
operatorCode :: string :: optional :: pattern ^[a-z]{2}\d{3}[a-z]{2}\d{3}$
correctiveInvoice :: CorrectiveInvoiceRef :: required :: iicRef points to original invoice
invoiceNotes :: string :: optional :: maxLength 500
isEinvoice :: boolean :: optional :: inherits from original when omitted
selectedProcess :: string enum :: optional :: P1–P11; electronic default P10
selectedInvoiceType :: string enum :: optional :: same values as RegisterInvoiceRequest
payDeadline :: string(date) :: optional :: YYYY-MM-DD
prepaidAmount :: number :: optional :: >= 0; maximum 2 decimal places

### StatusInvoiceRequest

docId :: string :: required :: same invoice docId; 5–200 chars

### InvoicePdfRequest

iic :: string :: required :: exactly 32 hexadecimal chars
pdfType :: string enum :: optional :: A4 | receipt | eInvoice; default A4
paperWidth :: integer enum :: optional :: 58 | 80 | 110; receipt only; default 80
lang :: string enum :: optional :: sq | en

### BalanceRequest

docId :: string :: required :: 5–200 chars; unique per balance operation; no required semantic format; reuse only to retry the same operation
amount :: number :: required :: amount in ALL
notes :: string :: optional :: operation note
operatorCode :: string :: optional :: pattern ^[a-z]{2}\d{3}[a-z]{2}\d{3}$

### GetTaxpayersRequest

searchTerm :: string :: required :: NIPT or business name; 3–200 chars

### InvoiceResponse

orderId :: string :: required :: echoes request docId
fic :: string :: conditional :: normal and cancellation completion identifier
eic :: string :: conditional :: required with fic for electronic completion
iic :: string :: conditional :: invoice identifier; 32 hexadecimal chars
link :: string(uri) :: optional :: public verification URL
error :: FiscalError :: optional :: present when incomplete or failed
invoiceNumber :: string :: optional :: fiscal invoice number
invoiceOrderNumber :: integer :: optional :: fiscal sequence number
invoiceType :: string enum :: optional :: CASH | NONCASH
totalPrice :: number :: optional :: gross total
totalPriceWithoutVat :: number :: optional :: net total
totalVatAmount :: number :: optional :: VAT total
taxFreeAmount :: number :: optional :: tax-free total
goodsExport :: number :: optional :: export amount
markUpAmount :: number :: optional :: markup amount
operatorCode :: string :: optional :: fiscal operator code
businessUnitCode :: string :: optional :: fiscal business-unit code
tcrCode :: string :: optional :: empty for electronic invoices
sellerName :: string :: optional :: seller name
sellerNuis :: string :: optional :: seller NIPT
sellerAddress :: string :: optional :: seller address

### InvoiceIncompleteResponse

orderId :: string :: required :: echoes request docId
error :: FiscalError :: required :: fiscalization or eInvoice delivery has not completed

### Error

message :: string :: required :: validation, authorization or domain error message
field :: string :: optional :: field that failed validation

### CisError

faultEnv :: string enum :: optional :: env:CLIENT | env:SERVER
faultString :: string :: optional :: message returned by the tax platform
faultCode :: string :: optional :: tax-platform error code

### FiscalError

cisError :: CisError :: optional :: tax platform error
otherError :: string :: optional :: temporary processing error

### PdfResponse

base64 :: string :: required :: base64 PDF or PNG
lang :: string :: optional :: document language

### EinvoicePdfResponse

base64 :: string :: required :: official eInvoice PDF encoded as base64
eic :: string :: required :: electronic invoice identifier

### BalanceResponse

orderId :: string :: required :: echoes request docId
fcdc :: string :: conditional :: completion identifier
error :: FiscalError :: optional :: processing error

### Taxpayer

Tin :: string :: required :: taxpayer NIPT
Name :: string :: required :: registered name
Address :: string :: required :: registered address
Town :: string :: required :: registered town
Country :: string :: required :: ISO 3166-1 alpha-3

### Operator

name :: string :: required :: operator display name
opCode :: string :: required :: use as operatorCode in fiscal requests

## Error handling

- HTTP 400 with message/field: request validation or domain rule; fix before retrying.
- HTTP 401: missing, invalid, revoked, wrong-environment, or server-unrecognized token; renew credentials, then preserve the original docId.
- cisError.faultEnv=env:CLIENT: non-retryable until corrected.
- cisError.faultEnv=env:SERVER, otherError, timeout, connection failure, HTTP 502 or HTTP 503: retryable using the docId recovery procedure.
- "Një kërkesë tjetër po përpunohet!": another request is processing that docId; stop parallel work, wait, then query status.

The OpenAPI document linked above is the canonical machine-readable source for code generation. This text index mirrors its field paths for direct AI lookup.