Choose your integration approach
The Cloud REST API suits server-based ERP, POS backends and ecommerce applications. The integration guide also documents local APIs and file integration for the easyPos and easyInvoice desktop products.
Choose the interface that matches where your software runs and the documents you need. Local and cloud interfaces have separate contracts; confirm the matching schema before reusing request bodies.
Prepare the business and development environment
Request credentials for the development environment and confirm which business and fiscal device they identify. The Cloud API resolves these from the access token, leaving document data in the request body.
- Confirm the business fiscal setup and electronic certificate.
- Map articles, VAT codes, measurement units, buyers and payment methods.
- Agree which normal, electronic and corrective documents your workflow needs.
- Keep access tokens on your server, outside browser code and public logs.
Authentication and environments
Documented endpoints use POST with JSON. Send Authorization: Bearer and Content-Type: application/json. The current reference recommends a stable integration-app header assigned to your integration.
Development and production use separate base URLs and credentials. Validate the document lifecycle in development before connecting production business data.
Register an invoice and verify completion
Generate and persist a unique docId with the immutable request body before POST /invoice/register. An HTTP 200 response alone does not confirm that the fiscal operation is complete.
- Normal invoices require fic, the fiscal confirmation identifier (NIVF).
- ELECTRONIC invoices require both fic and eic.
- Store iic (NSLF), the invoice number and the response alongside your internal order.
- Use /invoice/pdf for the supported PDF or receipt representation.
Recover safely from timeouts
A timeout can occur after the server has processed a document. Wait with exponential backoff and jitter, then call /invoice/status using the same docId. If the API confirms that it does not exist, replay the identical registration body and docId.
Never run register and status concurrently for one docId. Correct validation failures before retrying. A cancellation creates a new fiscal document with its own docId; retries of that cancellation reuse the cancellation identifier.
Validate data and test before going live
Use UN/CEFACT soldIn codes such as XPP, KGM, LTR and HUR, and ISO three-letter buyer country codes such as ALB. VAT codes depend on the business configuration. Payment amounts must reconcile with the calculated total after discounts.
The electronic invoice schema includes the buyer and the selected business process. Fiscal confirmation, electronic delivery and payment tracking are separate concerns; do not mark an invoice paid merely because fic and eic are present.
- Test normal and electronic invoices, cancellation and document output.
- Simulate network failure after registration and verify duplicate prevention.
- Handle incomplete electronic responses and validation failures.
- Agree operational ownership of pending documents and production activation.
API endpoints and base URLs
Development: https://api.dev.easypos.al/fiscalisation-service/v1
Production: https://api.easypos.al/fiscalisation-service/v1
| Endpoint | Purpose |
|---|---|
/invoice/register | Register or continue a document |
/invoice/status | Check or continue by docId |
/invoice/cancel | Create a corrective cancellation |
/invoice/pdf | Generate document output |
/balance/initiate | Opening cash balance |
/balance/deposit | Cash deposit |
/balance/withdraw | Cash withdrawal |
/utilities/get-taxpayers | Search taxpayers |
/utilities/get-operators | List operators |
Frequently asked questions
Does the API support Albanian electronic invoices?
Yes. The current Cloud reference documents ELECTRONIC invoices and their business processes. Completion requires both fic and eic, with buyer and process fields validated against the schema.
Is this the tax authority API?
This is the easyPos integration interface for your application. Use the easyPos contract for requests and the Albanian tax authority guidance for fiscal obligations.
Where are full request examples?
The integration documentation contains request and response examples, field schemas and a Postman collection.
Documentation and further reading
Contact us for a complete solution for your business: +355 4 453 7777or +355 69 404 1322