Dokumentacioni i API-t (v1)

Hyrje

LlogariPro ekspozon një API REST me të cilën sistemet e jashtme lexojnë dhe shkruajnë librat e një kompanie pa hyrje me përdorues. Kompania përcaktohet nga çelësi API, ndaj URL-të nuk mbajnë ID kompanie.

Të gjitha kërkesat dhe përgjigjet janë JSON (UTF-8). Datat janë ISO 8601 (YYYY-MM-DD), shumat kthehen si tekst dhjetor (p.sh. "1250.00") që të mos humbin saktësi, dhe listat faqosen me page/per_page.

URL bazë: https://books.konsulence.al/api/v1

Merr çelësin te Integrime › Çelësat API pas hyrjes në sistem.

Autentikimi

Çdo kërkesë mban çelësin e kompanisë në header-in X-API-Key ose si Authorization: Bearer <çelës>. Çelësi krijohet nga një administrator ose kontabilist te Integrime › Çelësat API dhe shfaqet i plotë vetëm një herë.

Çelësi mban të drejta (scopes). Një çelës vetëm-lexim nuk mund të krijojë asgjë; çelësi i importit fiskal mund vetëm të importojë fatura.

X-API-Key: lp_a1b2c3d4.dGhpc19pc19hX3NlY3JldF9rZXk…
# ose
Authorization: Bearer lp_a1b2c3d4.dGhpc19pc19hX3NlY3JldF9rZXk…

Të drejtat (scopes)

Scope
`read`	Lexon gjithçka: kompaninë, planin kontabël, partnerët, faturat, pagesat, ditarin, projektet, dimensionet, raportet.
`write`	Krijon partnerë, fatura, pagesa dhe veprime kontabël. Përfshin read dhe invoices:import.
`invoices:import`	Vetëm importin e faturave fiskale te POST /import/invoices (çelësat e platformave të fiskalizimit).

Konventat

Faqosja	?page=1&per_page=50 (maks. 200). Përgjigja mban meta: {page, per_page, total, pages}.
Filtrat sipas datës	from / to për fatura, pagesa dhe ditar; start / end për raporte; as_of për gjendje.
Shumat	Tekst dhjetor me dy shifra ("1250.00"). Në kërkesa pranohen edhe numra.
Idempotenca	external_id te faturat dhe veprimet kontabël parandalon dublikimet; partnerët njihen nga NIPT-i ose emri.
Kufizimi	Deri në 120 kërkesa në minutë për çelës. Përgjigje 429 kur tejkalohet.

Gabimet

Gabimet kthehen me kod HTTP dhe trup JSON {"error": "mesazh", "code": "kod"}.

`400 bad_request`	JSON i pavlefshëm ose parametër i gabuar
`401 unauthorized`	Çelës që mungon, i pavlefshëm ose i çaktivizuar
`403 insufficient_scope`	Çelësi s'ka të drejtën e kërkuar
`404 not_found`	Burimi nuk ekziston në këtë kompani
`409 conflict`	Konflikt (p.sh. NIPT i kompanisë s'përputhet me çelësin)
`422 unprocessable`	Të dhëna të pavlefshme kontabël: veprim i pabalancuar, llogari që mungon, dimension i detyrueshëm
`207 multi-status`	Importi u krye pjesërisht; shiko results për çdo faturë

Plani kontabël

GET/accounts read

Lista e llogarive. Me with_balance=1 kthen gjendjen (opsionalisht as_of).

Parametrat
`class`	1–9
`active`	1 (default) \| 0
`with_balance`	1 për gjendje
`as_of`	YYYY-MM-DD

Përgjigja

{"data": [{"code": "411", "name": "Klientë", "class": "4", "normal_side": "debit", "balance": "125000.00"}], "meta": {"total": 96}}

GET/exchange-rates read

Kurset e këmbimit sipas datës (1 valutë = kurs × ALL), siç ruhen për kompaninë: nga Banka e Shqipërisë (source boa), manuale ose rivlerësimi.

Parametrat
`currency`	EUR, USD…
`from, to`	YYYY-MM-DD

Përgjigja

{"home_currency": "ALL", "data": [{"currency": "EUR", "rate_date": "2026-09-04", "rate": "92.120000", "source": "boa"}], "meta": {…}}

GET/tax-rates read

Normat e TVSH-së dhe taksave.

Përgjigja

{"data": [{"id": "…", "code": "VAT20", "name": "TVSH 20%", "kind": "vat", "rate": "20.00"}]}

GET/dimensions read

Tre dimensionet (qendra kostoje, projekte, njësi biznesi) me vlerat dhe mënyrën (off/optional/mandatory).

Përgjigja

{"data": [{"kind": "cost_center", "name": "Qendra e kostos", "mode": "optional", "values": [{"id": "…", "code": "ADM", "name": "Administrata"}]}]}

Partnerët (klientë / donatorë / furnitorë)

GET/partners read

Lista e partnerëve me faqosje.

Parametrat
`type`	customer \| supplier
`q`	kërkim në emër/NIPT/email
`nipt`	përputhje e saktë
`page, per_page`	faqosja

Përgjigja

{"data": [{"id": "…", "name": "Klienti Sh.p.k.", "nipt": "L91234567B", "is_customer": true, "payment_terms_days": 30}], "meta": {"page": 1, "per_page": 50, "total": 1, "pages": 1}}

GET/partners/{id} read

Kartela e partnerit: të dhënat, të arkëtueshmet/pagueshmet (faturuar, paguar, hapur, në vonesë) dhe gjendjet në 411/401.

Përgjigja

{"id": "…", "name": "…", "receivable": {"invoiced": "90000.00", "paid": "60000.00", "open": "30000.00", "overdue": "0.00"}, "ledger_balances": {"411": "30000.00"}}

POST/partners write

Krijon një partner. Idempotent: nëse NIPT-i ose emri ekziston, kthen partnerin ekzistues (200) duke zgjeruar rolin.

Kërkesa

{"name": "Klienti Sh.p.k.", "nipt": "L91234567B", "is_customer": true, "is_supplier": false, "email": "info@klienti.al", "city": "Tiranë", "payment_terms_days": 30}

Përgjigja

201 → {"id": "…", "name": "Klienti Sh.p.k.", "nipt": "L91234567B", …}

Faturat dhe pagesat

GET/invoices read

Lista e faturave me filtra dhe faqosje.

Parametrat
`direction`	sale \| purchase
`status`	draft \| issued \| paid \| cancelled
`state`	open \| overdue \| partial \| paid (i llogaritur nga pagesat/afati)
`partner_id, number, external_id`	filtra të saktë
`from, to`	data e lëshimit

Përgjigja

{"data": [{"id": "…", "direction": "sale", "number": "45/2026", "issue_date": "2026-09-01", "due_date": "2026-10-01", "total": "60000.00", "amount_paid": "0.00", "balance_due": "60000.00", "status": "issued", "state": "open"}], "meta": {…}}

GET/invoices/{id} read

Fatura me rreshtat, dimensionet dhe pagesat.

Përgjigja

{"id": "…", "number": "45/2026", "lines": [{"description": "…", "quantity": "1.000", "unit_price": "50000.0000", "vat_rate": "20.00", "account_code": "701", "line_total": "60000.00"}], "payments": []}

POST/invoices write

Krijon dhe kontabilizon një faturë (statusi issued). Partneri gjendet nga NIPT-i ose krijohet. Struktura më poshtë.

Kërkesa

(shiko strukturën e faturës / see invoice structure)

Përgjigja

201 → fatura e plotë / the full invoice · 200 nëse external_id ekzistonte / if external_id already existed

POST/import/invoices invoices:import

Import në grup nga platformat e fiskalizimit: {"source": "devsync", "company_nipt": "…", "invoices": [ … ]}. Çdo faturë raportohet veçmas; 207 kur ka gabime.

Kërkesa

{"source": "devsync", "company_nipt": "L12345678A", "invoices": [ {…}, {…} ]}

Përgjigja

{"company": "…", "summary": {"created": 2, "skipped": 0, "error": 0}, "results": [{"external_id": "EIC-…", "number": "45/2026", "status": "created", "invoice_id": "…"}]}

GET/payments read

Arkëtimet dhe pagesat e faturave.

Parametrat
`partner_id`
`direction`	sale (arkëtime) \| purchase (pagesa)
`from, to`	data e pagesës

Përgjigja

{"data": [{"id": "…", "invoice_id": "…", "invoice_number": "45/2026", "pay_date": "2026-09-15", "amount": "60000.00", "account_code": "512", "realized_fx": "0.00"}], "meta": {…}}

POST/invoices/{id}/payments write

Regjistron dhe kontabilizon një pagesë (të plotë ose të pjesshme) te një faturë e postuar. account_code është arka/banka (klasa 5).

Kërkesa

{"amount": 60000, "account_code": "512", "pay_date": "2026-09-15", "exchange_rate": null}

Përgjigja

201 → {"id": "…", "amount": "60000.00", "journal_entry_id": "…"}

Shpenzimet (Expense manager)

GET/expense-categories read

Llogaritë e shpenzimeve (klasa 6) dhe hartëzimi i kategorive që kompania ka vendosur — për t'ua shfaqur punonjësve në sistemin e shpenzimeve.

Përgjigja

{"data": [{"code": "625", "name": "Udhëtime e dieta"}], "category_map": {"Udhëtime": {"account": "625"}}, "default_account": "601"}

POST/import/expenses expenses:import

Import shpenzimesh të miratuara: {"expenses": [ … ]}. Të rimbursueshmet bëhen detyrim ndaj punonjësit (Për pagesë); të paguarat nga firma shlyhen nga llogaria e hartëzuar për paid_with. Idempotent me external_id; dëshmia (receipt, base64) bashkangjitet.

Kërkesa

{"expenses": [{"external_id": "EXP-42", "date": "2026-09-05", "amount": 12000, "vat_amount": 2000, "category": "Udhëtime", "description": "Hotel 2 net", "employee": {"name": "Ardit Hoxha", "email": "ardit@firma.al"}, "merchant": {"name": "Hotel Tirana"}, "payment": "reimbursable", "receipt": {"filename": "hotel.pdf", "content_base64": "…"}}]}

Përgjigja

{"company": "…", "summary": {"created": 1}, "results": [{"external_id": "expman:EXP-42", "number": "EXP-EXP-42", "status": "created", "invoice_id": "…"}], "receipts_attached": 1}

Ditari

GET/journal-entries read

Veprimet kontabël; with_lines=1 përfshin rreshtat.

Parametrat
`source`	manual \| invoice \| bank \| payroll \| payment \| revaluation \| api
`from, to`
`with_lines`	1

Përgjigja

{"data": [{"id": "…", "entry_no": "202609-0001", "entry_date": "2026-09-01", "memo": "Shitje - Klienti #45/2026", "source": "invoice", "total_debit": "60000.00"}], "meta": {…}}

GET/journal-entries/{id} read

Veprimi me rreshtat, partnerin dhe dimensionet.

Përgjigja

{"id": "…", "lines": [{"account_code": "411", "debit": "60000.00", "credit": "0.00", "partner_id": "…", "dimensions": [{"kind": "cost_center", "value": "Administrata"}]}]}

POST/journal-entries write

Poston një veprim manual të balancuar. Zbatohen të gjitha rregullat: debi = kredi, llogaritë duhet të ekzistojnë, dimensionet e detyrueshme te 6/7.

Kërkesa

{"entry_date": "2026-09-30", "memo": "Qira shtator", "external_id": "ERP-JE-1001", "lines": [{"account_code": "613", "debit": 50000, "description": "Qira", "dimension_ids": ["<cost-centre-value-id>"]}, {"account_code": "512", "credit": 50000}]}

Përgjigja

201 → {"id": "…", "entry_no": "202609-0042", "posted": true, "lines": [ … ]}

Projektet

GET/projects read

Projektet (grante/kontrata); with_actuals=1 shton realizimin.

Parametrat
`status`	planned \| active \| closed
`partner_id`
`with_actuals`	1

Përgjigja

{"data": [{"id": "…", "code": "P-01", "name": "Granti UNDP 2026", "partner_name": "UNDP", "status": "active", "budget_expense": "1000000.00", "actuals": {"income": "500000.00", "expense": "300000.00", "expense_pct": "30.0"}}]}

GET/projects/{id} read

Projekti me buxhet vs realitet sipas llogarive.

Përgjigja

{"id": "…", "budget_vs_actual": [{"account_code": "601", "budget": "1000000.00", "actual": "300000.00", "variance": "700000.00", "pct": "30.0"}]}

Raportet

GET/reports/income-statement read

PASH për periudhën, me grupime SKK; dimension_value_id filtron sipas një qendre kostoje, projekti ose njësie.

Parametrat
`start, end`	YYYY-MM-DD (default: viti aktual)
`dimension_value_id`

Përgjigja

{"period": {…}, "income": [ … ], "expense": [ … ], "total_income": "…", "total_expense": "…", "result_before_tax": "…", "profit_tax": "…", "result_after_tax": "…"}

GET/reports/balance-sheet read

Bilanci në datën as_of.

Parametrat
`as_of`	YYYY-MM-DD (default: sot)

Përgjigja

{"as_of": "2026-09-30", "assets": …, "liabilities": …, "equity": …}

GET/reports/partner-balances read

Gjendjet sipas partnerit në 411 (klientë) ose 401 (furnitorë).

Parametrat
`account`	411 (default) \| 401
`as_of`

Përgjigja

{"account": "411", "data": [{"partner_id": "…", "partner": "Klienti Sh.p.k.", "nipt": "…", "debit": "…", "credit": "…", "balance": "30000.00"}]}

Zyra (çelës zyre)

GET/practice/ping monitor

Verifikon çelësin e zyrës (lpo_…). Çelësat e kompanive nuk hapin këto rrugë, dhe anasjelltas.

Përgjigja

{"ok": true, "version": "1.4", "practice": "KONSULENCE.AL", "nipt": "L32327017S", "scopes": ["monitor", "offers"], "billing_company": {"id": "…", "name": "KONSULENCE.AL shpk", "nipt": "…", "currency": "ALL", "charges_vat": true}}

GET/practice/companies monitor

Kompanitë që mban zyra (edhe të arkivuarat, me archived: true) dhe kush ka akses te secila.

Përgjigja

{"data": [{"id": "…", "name": "Alfa shpk", "nipt": "L11111111A", "archived": false, "members": [{"user_id": "…", "role": "admin"}]}]}

GET/practice/members monitor

Ekipi i zyrës.

Përgjigja

{"data": [{"id": "…", "email": "ana@zyra.al", "name": "Ana K.", "practice_role": "member"}]}

GET/practice/status monitor

Gjendja e librave për çdo klient aktiv: lëvizjet bankare pa kategorizuar, dokumentet e hapura/me vonesë, fiskalizimi, kyçja e periudhës, detyrat dhe aktiviteti i fundit.

Përgjigja

{"as_of": "2026-10-23", "data": [{"company_id": "…", "bank": {"pending_lines": 12, "oldest_pending_date": "2026-09-02"}, "books": {"last_entry_date": "2026-10-21", "lock_date": "2026-08-31"}, "invoices": {"overdue_sales": 3, "overdue_sales_amount": "48000.00"}, "fiscal": {"errors": 0, "certificate": "ok"}, "tasks": {"open": 2, "overdue": 0}}]}

GET/practice/activity monitor

Kush punoi ku: një rresht për ditë × kompani × përdorues, me minutat aktive dhe veprimet (me dorë / në masë). Pa përdorues = API, cron, webhook.

Parametrat
`from, to`	YYYY-MM-DD (deri në 93 ditë; parazgjedhur 30 ditët e fundit)

Përgjigja

{"from": "2026-10-01", "to": "2026-10-23", "users": [{"id": "…", "email": "ana@zyra.al", "name": "Ana K."}], "data": [{"date": "2026-10-20", "company_id": "…", "user_id": "…", "active_minutes": 95, "actions": 41, "manual_actions": 33, "bulk_actions": 8, "by_type": {"JournalEntry": 20}, "first_at": "…", "last_at": "…"}]}

GET/practice/tasks monitor

Detyrat e hapura të Punës; me done_since edhe ato të kryera që nga ajo datë.

Parametrat
`done_since`	YYYY-MM-DD

Përgjigja

{"data": [{"id": "…", "title": "TVSH shtator", "company_id": "…", "status": "in_progress", "assigned_to": "…", "due_date": "2026-10-15"}]}

POST/practice/offers offers

Ofertë për një klient të zyrës (p.sh. koha e punuar nga Portali i Klientëve), te kompania që faturon klientët (Zyra → Portali i Klientëve). Klienti bëhet partner sipas NIPT-it. Krijohet e pa dërguar; i njëjti external_id e ndërron sa është e pa dërguar, pastaj kthen 409 offer_locked.

Parametrat
`external_id, partner {nipt, name, email}, issue_date, valid_until, notes, lines [{description, quantity, unit_price, vat_rate}]`	vat_rate parazgjedhur 20; TVSH vetëm kur kompania e llogarit

Përgjigja

{"status": "created", "offer": {"id": "…", "external_id": "portal-offer-…", "number": "OF-2026-0007", "state": "draft", "subtotal": "6500.00", "vat_total": "1300.00", "total": "7800.00", "url": "https://books.konsulence.al/invoices/…", "invoice": null}}

GET/practice/offers offers

Gjendja e ofertave sipas external_id (dërguar, pranuar, kthyer në faturë me numrin e faturës).

Parametrat
`external_id`	id-të e ndara me presje

Përgjigja

{"billing_company": {…}, "data": [{"external_id": "portal-offer-…", "number": "OF-2026-0007", "state": "converted", "invoice": {"number": "SH-2026-0042", "status": "draft"}}]}

Struktura e faturës (POST /invoices dhe /import/invoices)

{
  "external_id": "EIC-2026-000123",        // idempotency key (optional but recommended)
  "direction": "sale",                     // sale | purchase
  "number": "45/2026",
  "issue_date": "2026-09-01",
  "due_date": "2026-10-01",
  "currency": "ALL",                       // ISO code; exchange_rate for foreign currency
  "payment_method": "noncash",             // cash | card | noncash
  "tcr_code": "xh123abc45",                // fiscal cash register (optional)
  "nivf": "<UUID>", "nslf": "<32 hex>",    // fiscal codes (optional): NIVF = FIC, NSLF = IIC
  "qr": "…",
  "partner": {"nipt": "L91234567B", "name": "Klienti Sh.p.k."},
  "pdf_base64": "JVBERi0xLjQK…", "pdf_filename": "Fatura_45-2026.pdf",   // optional: PDF attached to the invoice
  "lines": [
    {"description": "Shërbim konsulence", "quantity": 1, "unit_price": 50000,
     "vat_rate": 20, "account_code": "701", "dimension_ids": ["<value-id>"]}
  ]
}

Fusha
`direction`	sale (shitje) ose purchase (blerje) — i detyrueshëm
`partner`	nipt dhe/ose name; partneri gjendet nga NIPT-i, pastaj nga emri, përndryshe krijohet me rolin e duhur
`lines[]`	description, quantity, unit_price (pa TVSH), vat_rate (%), account_code (7xx për shitje, 6xx për blerje; parazgjedhja 701/601), dimension_ids
`payment_method`	cash/card kontabilizohen te arka e TCR-së (hartëzimi TCR → arkë); noncash te 411/401
`currency, exchange_rate`	Për monedhë të huaj; pa kurs përdoret tabela e kurseve sipas datës
`external_id`	Çelës idempotence: e njëjta faturë s'importohet dy herë (status skipped)

curl

curl -H "X-API-Key: lp_a1b2c3d4.…" https://books.konsulence.al/api/v1/ping

curl -H "X-API-Key: $KEY" "https://books.konsulence.al/api/v1/invoices?direction=sale&state=open&per_page=100"

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  https://books.konsulence.al/api/v1/invoices \
  -d '{"external_id":"ERP-45","direction":"sale","number":"45/2026","issue_date":"2026-09-01",
       "partner":{"nipt":"L91234567B","name":"Klienti Sh.p.k."},
       "lines":[{"description":"Konsulencë","quantity":1,"unit_price":50000,"vat_rate":20,"account_code":"701"}]}'

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  https://books.konsulence.al/api/v1/invoices/<id>/payments -d '{"amount":60000,"account_code":"512","pay_date":"2026-09-15"}'

Hyr në sistem →

Dokumentacioni i API-t (v1)

Hyrje

Autentikimi

Të drejtat (scopes)

Konventat

Gabimet

Meta

GET/ping —

GET/company read

Plani kontabël

GET/accounts read

GET/exchange-rates read

GET/tax-rates read

GET/dimensions read

Partnerët (klientë / donatorë / furnitorë)

GET/partners read

GET/partners/{id} read

POST/partners write

Faturat dhe pagesat

GET/invoices read

GET/invoices/{id} read

POST/invoices write

POST/import/invoices invoices:import

GET/payments read

POST/invoices/{id}/payments write

Shpenzimet (Expense manager)

GET/expense-categories read

POST/import/expenses expenses:import

Ditari

GET/journal-entries read

GET/journal-entries/{id} read

POST/journal-entries write

Projektet

GET/projects read

GET/projects/{id} read

Raportet

GET/reports/income-statement read

GET/reports/balance-sheet read

GET/reports/partner-balances read

Zyra (çelës zyre)

GET/practice/ping monitor

GET/practice/companies monitor

GET/practice/members monitor

GET/practice/status monitor

GET/practice/activity monitor

GET/practice/tasks monitor

POST/practice/offers offers

GET/practice/offers offers

Struktura e faturës (POST /invoices dhe /import/invoices)

curl