Cilin integrim duhet të zgjidhni?
Cloud API përshtatet me aplikacione web, ERP dhe sisteme tregtie elektronike që komunikojnë nga serveri. Udhëzuesi i integrimit përmban edhe API lokale dhe integrim me skedarë për aplikacionet desktop easyPos dhe easyInvoice.
Zgjidhni sipas vendit ku funksionon aplikacioni, llojit të dokumentit dhe nevojës për pajisje lokale. Kontratat e Cloud API dhe integrimit lokal janë të ndryshme; mos përdorni të njëjtin payload pa kontrolluar referencën përkatëse.
Çfarë duhet përpara kërkesës së parë?
Kërkoni kredenciale për mjedisin e zhvillimit dhe konfirmoni biznesin e pajisjen fiskale që përfaqësojnë. Sipas kontratës së Cloud API, këto zgjidhen nga token-i; trupi i kërkesës përmban të dhënat e dokumentit.
- Përcaktoni faturat normale, elektronike dhe rastet e korrigjimit që ju nevojiten.
- Konfirmoni konfigurimin fiskal të biznesit dhe certifikatën elektronike.
- Hartëzoni artikujt, kodet e TVSH-së, njësitë matëse, blerësit dhe pagesat.
- Ruani token-in në server dhe mbajeni jashtë kodit të shfletuesit e regjistrave publikë.
Autentikimi dhe mjediset
Të gjitha endpoint-et e dokumentuara përdorin POST me JSON dhe Authorization: Bearer. Dërgoni Content-Type: application/json. Header-i integration-app rekomandohet në referencën aktuale dhe duhet të mbetet identifikues i qëndrueshëm i integrimit tuaj.
Mjedisi development shërben për testim; kalimi në production kërkon URL-në dhe kredencialet përkatëse. Mos përzieni dokumentet apo token-at e dy mjediseve.
Nga regjistrimi te konfirmimi i faturës
Gjeneroni një docId unik për dokumentin dhe ruajeni bashkë me trupin e kërkesës përpara dërgimit. POST /invoice/register nis ose vazhdon veprimin për atë docId. HTTP 200, i vetëm, nuk mjafton për ta shënuar faturën të përfunduar.
- Për faturë normale, kontrolloni praninë e fic (NIVF).
- Për dokument ELECTRONIC, kërkohen si fic ashtu edhe eic.
- Ruani iic (NSLF), numrin e faturës dhe përgjigjen pranë porosisë tuaj.
- Përdorni /invoice/pdf për paraqitjen e dokumentit sipas opsioneve të referencës.
Si të shmangni faturat e dyfishta
Një timeout nuk provon se fatura dështoi. Prisni me interval në rritje dhe vonesë të rastësishme, pastaj përdorni /invoice/status me të njëjtin docId. Nëse API konfirmon se dokumenti nuk ekziston, ridërgoni trupin identik me të njëjtin docId.
Mos kryeni register dhe status njëkohësisht për të njëjtin dokument. Gabimet e validimit kërkojnë korrigjim të të dhënave, jo përsëritje automatike. Anulimi është dokument i ri: krijoni docId të ri për anulimin dhe ripërdoreni atë vetëm gjatë riprovimeve të anulimit.
Kontrollet e të dhënave dhe testimi
Përdorni kode UN/CEFACT për soldIn, si XPP, KGM, LTR dhe HUR. Vendi i blerësit përdor kodin ISO me tre shkronja, për shembull ALB. Kodet e TVSH-së duhen marrë nga konfigurimi i biznesit; mos supozoni se një kod vlen për çdo subjekt.
- Kontrolloni që shuma e pagesave përputhet me totalin pas zbritjeve.
- Testoni faturë normale, elektronike, anulim dhe PDF.
- Simuloni timeout dhe verifikoni që riprovimi nuk krijon faturë tjetër.
- Kontrolloni përgjigje elektronike të paplota dhe gabime validimi.
- Përcaktoni kush ndjek dokumentet në pritje dhe kush miraton kalimin në prodhim.
Endpoint-et dhe adresat bazë
Development: https://api.dev.easypos.al/fiscalisation-service/v1
Production: https://api.easypos.al/fiscalisation-service/v1
| Endpoint | Përdorimi |
|---|---|
/invoice/register | Regjistrim ose vazhdim dokumenti |
/invoice/status | Kontroll ose vazhdim sipas docId |
/invoice/cancel | Krijim i dokumentit të anulimit |
/invoice/pdf | Gjenerim i paraqitjes së dokumentit |
/balance/initiate | Gjendja fillestare e arkës |
/balance/deposit | Shtim parash në arkë |
/balance/withdraw | Tërheqje parash nga arka |
/utilities/get-taxpayers | Kërkim tatimpaguesish |
/utilities/get-operators | Lista e operatorëve |
Pyetje të shpeshta
A mbështet Cloud API faturë elektronike?
Po. Referenca aktuale dokumenton ELECTRONIC dhe proceset përkatëse. Përfundimi kërkon fic dhe eic; të dhënat e blerësit dhe procesi kontrollohen sipas skemës.
A mund ta përdor API-në direkt nga shfletuesi?
Integrimi duhet të kalojë nga serveri juaj për të mbrojtur token-in. Shfletuesi komunikon me backend-in tuaj, i cili kryen kërkesat fiskale.
Ku gjenden payload-et e plota?
Te dokumentacioni i integrimit gjenden skemat, shembujt e kërkesave dhe përgjigjeve dhe koleksioni Postman.
Dokumentacion dhe burime të lidhura
Na kontaktoni për një zgjidhje të plotë për biznesin tuaj: +355 4 453 7777ose +355 69 404 1322