Referenca e API-së

API REST me të njëjtat të dhëna që i shihni në Zen365. 42 endpoint-e, të ndara sipas punës që bëjnë.

Baza dhe versioni

Të gjitha kërkesat shkojnë te /api, në adresën e Zen365. Kërkesat dhe përgjigjet janë në JSON.

Autentikimi

Çdo kërkesë e dërgon çelësin tuaj personal në header-in x-api-key. Çelësi punon me të drejtat e personit që e krijoi, në të gjitha organizatat ku ky person është anëtar.

Çelësat i krijoni dhe i fshini brenda Zen365, te llogaria juaj.
Çelësi i plotë shfaqet vetëm një herë, kur e krijoni. Ruajeni menjëherë.
Më pas shfaqet i fshehur pjesërisht, si api_xxxx...yyyy.
Çdo çelës ka datë skadimi.

Mos e vendosni çelësin në kod që ekzekutohet në browser ose në një repository publik. Kush e ka çelësin, ka të njëjtën qasje si ju.

cURL

curl "https://<baza>/api/account/me" \
  -H "x-api-key: $ZEN365_API_KEY"

Organizata

Një çelës nuk lidhet me vetëm një organizatë. Prandaj shumica e endpoint-eve e kërkojnë organizationId si parametër, që të dihet për cilin biznes po pyetni.

cURL

curl "https://<baza>/api/organization" \
  -H "x-api-key: $ZEN365_API_KEY"

Listat dhe faqet

Listat kthehen në faqe, me kursor. Jepni vetëm njërin nga first ose last, jo të dy, me maksimum 100.

cURL

curl "https://<baza>/api/sale?organizationId=<uuid>&first=20" \
  -H "x-api-key: $ZEN365_API_KEY"

Gabimet

400 kërkesa nuk u pranua: mungon një parametër ose një vlerë nuk është e vlefshme.
401 çelësi mungon, është i gabuar ose ka skaduar.
403 çelësi është në rregull, por personi nuk ka të drejtë për këtë veprim ose për këtë organizatë.
404 ajo që kërkoni nuk ekziston në këtë organizatë.
429 shumë kërkesa: numri i kërkesave për minutë është i kufizuar.

Krijimi i thjeshtë

Çdo dokument mund të krijohet në dy mënyra. Endpoint-i i plotë kërkon id-të e të gjitha palëve. Endpoint-i /light/create pranon emra dhe kode artikujsh, që të mos keni nevojë t'i kërkoni id-të më parë.

Datat lexohen sipas formatit të organizatës. Nëse s'është ndryshuar, formati është DD/MM/YYYY.

Llogaria

Kush jeni dhe cilat organizata ju takojnë.

GET/api/account/me#

Merr të dhënat e llogarisë

curl -X GET "https://<baza>/api/account/me" \
  -H "x-api-key: $ZEN365_API_KEY"

GET/api/organization#

Listo organizatat

curl -X GET "https://<baza>/api/organization" \
  -H "x-api-key: $ZEN365_API_KEY"

GET/api/organization/:organizationId#

Merr organizatën sipas id-së

curl -X GET "https://<baza>/api/organization/:organizationId" \
  -H "x-api-key: $ZEN365_API_KEY"

Shitjet

Faturat: krijimi, finalizimi, dërgimi dhe PDF-ja.

GET/api/sale#

Listo shitjet

Parametra

organizationId{{organizationId}}
first20

curl -X GET "https://<baza>/api/sale?organizationId=<organization uuid>&first=20" \
  -H "x-api-key: $ZEN365_API_KEY"

GET/api/sale/:id#

Merr shitjen sipas id-së

curl -X GET "https://<baza>/api/sale/:id" \
  -H "x-api-key: $ZEN365_API_KEY"

POST/api/sale/light/create#

Krijo shitje (me emra, pa id)

Fushat e trupit

organizationNamestring
organizationUnitNamestring
buyerNamestring
issueDatestring
dueDatestring
itemslistë

curl -X POST "https://<baza>/api/sale/light/create" \
  -H "x-api-key: $ZEN365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationName": "<emri i organizatës>",
    "organizationUnitName": "<organization unit name>",
    "buyerName": "<existing buyer name>",
    "issueDate": "<DD/MM/YYYY>",
    "dueDate": "<DD/MM/YYYY>",
    "items": [
      {
        "qty": 2,
        "unitPriceWithVat": 3.54,
        "itemCode": "<item code>",
        "vatRate": 18
      }
    ]
  }'

POST/api/sale#

Krijo shitje (me id të plota)

Fushat e trupit

typestring
organizationIdstring
entityIdstring
organizationUnitIdstring
issueDatestring
dueDatestring
itemslistë

curl -X POST "https://<baza>/api/sale" \
  -H "x-api-key: $ZEN365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SALE",
    "organizationId": "<organization uuid>",
    "entityId": "<buyer entity uuid>",
    "organizationUnitId": "<organization unit uuid>",
    "issueDate": "<DD/MM/YYYY>",
    "dueDate": "<DD/MM/YYYY>",
    "items": [
      {
        "itemId": "<item uuid>",
        "uomId": "<uom uuid>",
        "vatRateId": "<vat rate uuid>",
        "qty": 1,
        "unitPrice": 3,
        "itemName": "<item name>",
        "itemCode": "<item code>",
        "vatRate": 18,
        "uomName": "<uom name>"
      }
    ]
  }'

PATCH/api/sale/:id#

Përditëso shitjen

Fushat e trupit

organizationIdstring
versionnumber
memostring

curl -X PATCH "https://<baza>/api/sale/:id" \
  -H "x-api-key: $ZEN365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "<organization uuid>",
    "version": 1,
    "memo": "<shënim>"
  }'

GET/api/sale/:id/download-link#

Merr linkun e PDF-së së faturës

curl -X GET "https://<baza>/api/sale/:id/download-link" \
  -H "x-api-key: $ZEN365_API_KEY"

POST/api/sale/:id/send#

Dërgo faturën me email

Fushat e trupit

connectorIdstring
tostring
subjectstring
bodystring

curl -X POST "https://<baza>/api/sale/:id/send" \
  -H "x-api-key: $ZEN365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorId": "<mail connector uuid>",
    "to": "customer@example.com",
    "subject": "Fatura juaj",
    "body": "Të nderuar, gjeni faturën bashkëngjitur."
  }'

POST/api/sale/:id/copy#

Kopjo shitjen

curl -X POST "https://<baza>/api/sale/:id/copy" \
  -H "x-api-key: $ZEN365_API_KEY"

POST/api/sale/:id/finalize#

Finalizo shitjen

Fushat e trupit

versionnumber

curl -X POST "https://<baza>/api/sale/:id/finalize" \
  -H "x-api-key: $ZEN365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1
  }'

POST/api/sale/:id/cancel#

Anulo shitjen

Fushat e trupit

reasonstring

curl -X POST "https://<baza>/api/sale/:id/cancel" \
  -H "x-api-key: $ZEN365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "<arsyeja e anulimit>"
  }'

DELETE/api/sale/:id#

Fshi shitjen në draft

curl -X DELETE "https://<baza>/api/sale/:id" \
  -H "x-api-key: $ZEN365_API_KEY"

Profaturat

Të njëjtat kërkesa si te shitjet, me `type: QUOTE`.

GET/api/sale#

Listo profaturat

Parametra

organizationId{{organizationId}}
first20
typeQUOTE

curl -X GET "https://<baza>/api/sale?organizationId=<organization uuid>&first=20&type=QUOTE" \
  -H "x-api-key: $ZEN365_API_KEY"

POST/api/sale/light/create#

Krijo profaturë (me emra, pa id)

Fushat e trupit

typestring
organizationNamestring
organizationUnitNamestring
buyerNamestring
issueDatestring
dueDatestring
itemslistë

curl -X POST "https://<baza>/api/sale/light/create" \
  -H "x-api-key: $ZEN365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "QUOTE",
    "organizationName": "<emri i organizatës>",
    "organizationUnitName": "<organization unit name>",
    "buyerName": "<existing buyer name>",
    "issueDate": "<DD/MM/YYYY>",
    "dueDate": "<DD/MM/YYYY>",
    "items": [
      {
        "qty": 2,
        "unitPriceWithVat": 3.54,
        "itemCode": "<item code>",
        "vatRate": 18
      }
    ]
  }'

POST/api/sale#

Krijo profaturë (me id të plota)

Fushat e trupit

typestring
organizationIdstring
entityIdstring
organizationUnitIdstring
issueDatestring
dueDatestring
itemslistë

curl -X POST "https://<baza>/api/sale" \
  -H "x-api-key: $ZEN365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "QUOTE",
    "organizationId": "<organization uuid>",
    "entityId": "<buyer entity uuid>",
    "organizationUnitId": "<organization unit uuid>",
    "issueDate": "<DD/MM/YYYY>",
    "dueDate": "<DD/MM/YYYY>",
    "items": [
      {
        "itemId": "<item uuid>",
        "uomId": "<uom uuid>",
        "vatRateId": "<vat rate uuid>",
        "qty": 1,
        "unitPrice": 3,
        "itemName": "<item name>",
        "itemCode": "<item code>",
        "vatRate": 18,
        "uomName": "<uom name>"
      }
    ]
  }'

PATCH/api/sale/:id#

Përditëso profaturën

Fushat e trupit

organizationIdstring
versionnumber
memostring

curl -X PATCH "https://<baza>/api/sale/:id" \
  -H "x-api-key: $ZEN365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "<organization uuid>",
    "version": 1,
    "memo": "<shënim>"
  }'

GET/api/sale/:id/download-link#

Merr linkun e PDF-së së profaturës

curl -X GET "https://<baza>/api/sale/:id/download-link" \
  -H "x-api-key: $ZEN365_API_KEY"

Blerjet

Faturat e furnitorëve.

GET/api/purchase#

Listo blerjet

Parametra

organizationId{{organizationId}}
first20

curl -X GET "https://<baza>/api/purchase?organizationId=<organization uuid>&first=20" \
  -H "x-api-key: $ZEN365_API_KEY"

GET/api/purchase/:id#

Merr blerjen sipas id-së

curl -X GET "https://<baza>/api/purchase/:id" \
  -H "x-api-key: $ZEN365_API_KEY"

POST/api/purchase/light/create#

Krijo blerje (me emra, pa id)

Fushat e trupit

organizationNamestring
organizationUnitNamestring
supplierNamestring
issueDatestring
dueDatestring
referenceNrstring
itemslistë

curl -X POST "https://<baza>/api/purchase/light/create" \
  -H "x-api-key: $ZEN365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationName": "<emri i organizatës>",
    "organizationUnitName": "<organization unit name>",
    "supplierName": "<existing supplier name>",
    "issueDate": "<DD/MM/YYYY>",
    "dueDate": "<DD/MM/YYYY>",
    "referenceNr": "F-2026-0001",
    "items": [
      {
        "qty": 10,
        "unitPriceWithVat": 2.95,
        "code": "<item code>",
        "vatRate": 18
      }
    ]
  }'

POST/api/purchase#

Krijo blerje (me id të plota)

Fushat e trupit

typestring
organizationIdstring
entityIdstring
organizationUnitIdstring
issueDatestring
dueDatestring
referenceNrstring
itemslistë

curl -X POST "https://<baza>/api/purchase" \
  -H "x-api-key: $ZEN365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SIMPLE",
    "organizationId": "<organization uuid>",
    "entityId": "<supplier entity uuid>",
    "organizationUnitId": "<organization unit uuid>",
    "issueDate": "<DD/MM/YYYY>",
    "dueDate": "<DD/MM/YYYY>",
    "referenceNr": "F-2026-0001",
    "items": [
      {
        "itemId": "<item uuid>",
        "uomId": "<uom uuid>",
        "vatRateId": "<vat rate uuid>",
        "qty": 10,
        "unitPrice": 2.5,
        "itemName": "<item name>",
        "itemCode": "<item code>",
        "vatRate": 18,
        "uomName": "<uom name>"
      }
    ]
  }'

POST/api/purchase/:id/finalize#

Finalizo blerjen

curl -X POST "https://<baza>/api/purchase/:id/finalize" \
  -H "x-api-key: $ZEN365_API_KEY"

POST/api/purchase/:id/cancel#

Anulo blerjen

Fushat e trupit

reasonstring

curl -X POST "https://<baza>/api/purchase/:id/cancel" \
  -H "x-api-key: $ZEN365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "<arsyeja e anulimit>"
  }'

DELETE/api/purchase/:id#

Fshi blerjen në draft

curl -X DELETE "https://<baza>/api/purchase/:id" \
  -H "x-api-key: $ZEN365_API_KEY"

Klientët dhe furnitorët

Palët me të cilat punoni: blerësit dhe furnitorët.

GET/api/entity#

Listo blerësit dhe furnitorët

Parametra

organizationId{{organizationId}}
first20

curl -X GET "https://<baza>/api/entity?organizationId=<organization uuid>&first=20" \
  -H "x-api-key: $ZEN365_API_KEY"

GET/api/entity/by-name#

Gjej palën sipas emrit

Parametra

organizationId{{organizationId}}
name<name>
exactMatchfalse

curl -X GET "https://<baza>/api/entity/by-name?organizationId=<organization uuid>&name=<name>&exactMatch=false" \
  -H "x-api-key: $ZEN365_API_KEY"

POST/api/entity#

Krijo palë

Fushat e trupit

organizationIdstring
namestring
typestring
metaobject

curl -X POST "https://<baza>/api/entity" \
  -H "x-api-key: $ZEN365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "<organization uuid>",
    "name": "Acme Sh.p.k.",
    "type": "BUYER",
    "meta": {
      "vatNumber": "810123456",
      "email": "info@acme.com",
      "phone": "+38344123456"
    }
  }'

PATCH/api/entity/:id#

Përditëso palën

Fushat e trupit

organizationIdstring
metaobject

curl -X PATCH "https://<baza>/api/entity/:id" \
  -H "x-api-key: $ZEN365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "<organization uuid>",
    "meta": {
      "email": "billing@acme.com"
    }
  }'

DELETE/api/entity/:id#

Fshi palën

curl -X DELETE "https://<baza>/api/entity/:id" \
  -H "x-api-key: $ZEN365_API_KEY"

Artikujt

Katalogu i produkteve dhe shërbimeve.

GET/api/item#

Listo artikujt

Parametra

organizationId{{organizationId}}
first20

curl -X GET "https://<baza>/api/item?organizationId=<organization uuid>&first=20" \
  -H "x-api-key: $ZEN365_API_KEY"

GET/api/item/:id#

Merr artikullin sipas id-së

curl -X GET "https://<baza>/api/item/:id" \
  -H "x-api-key: $ZEN365_API_KEY"

POST/api/item/light/create#

Krijo artikuj (me emra, disa njëherësh)

Fushat e trupit

0object

curl -X POST "https://<baza>/api/item/light/create" \
  -H "x-api-key: $ZEN365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "organizationName": "<emri i organizatës>",
      "unitOfMeasure": "<uom name, e.g. COPE>",
      "vatRateName": "<vat rate name, e.g. TVSH 18%>",
      "code": "<item code>",
      "name": "<item name>"
    }
  ]'

POST/api/item#

Krijo artikull (me id të plota)

Fushat e trupit

organizationIdstring
namestring
typestring
codestring
baseUomIdstring
vatRateIdstring

curl -X POST "https://<baza>/api/item" \
  -H "x-api-key: $ZEN365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "<organization uuid>",
    "name": "<item name>",
    "type": "SIMPLE",
    "code": "<item code>",
    "baseUomId": "<uom uuid from /api/unit-of-measure>",
    "vatRateId": "<vat rate uuid from /api/vat-rate>"
  }'

PATCH/api/item/:id#

Përditëso artikullin

Fushat e trupit

organizationIdstring
namestring

curl -X PATCH "https://<baza>/api/item/:id" \
  -H "x-api-key: $ZEN365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "<organization uuid>",
    "name": "<new name>"
  }'

DELETE/api/item/:id#

Fshi artikullin

curl -X DELETE "https://<baza>/api/item/:id" \
  -H "x-api-key: $ZEN365_API_KEY"

Të dhëna ndihmëse

Njësitë, normat e TVSH-së, vitet fiskale dhe njësitë organizative.

GET/api/unit-of-measure#

Listo njësitë matëse

Parametra

organizationId{{organizationId}}

curl -X GET "https://<baza>/api/unit-of-measure?organizationId=<organization uuid>" \
  -H "x-api-key: $ZEN365_API_KEY"

GET/api/vat-rate#

Listo normat e TVSH-së

Parametra

organizationId{{organizationId}}

curl -X GET "https://<baza>/api/vat-rate?organizationId=<organization uuid>" \
  -H "x-api-key: $ZEN365_API_KEY"

GET/api/fiscal-year#

Listo vitet fiskale

Parametra

organizationId{{organizationId}}

curl -X GET "https://<baza>/api/fiscal-year?organizationId=<organization uuid>" \
  -H "x-api-key: $ZEN365_API_KEY"

GET/api/organization-unit#

Listo njësitë organizative

Parametra

organizationId{{organizationId}}

curl -X GET "https://<baza>/api/organization-unit?organizationId=<organization uuid>" \
  -H "x-api-key: $ZEN365_API_KEY"

POS-i

Shitje nga POS-i. E njëjta kërkesa nuk regjistrohet dy herë (idempotente).

POST/api/pos/sale#

Krijo shitje nga POS-i (idempotente)

Fushat e trupit

organizationNamestring
organizationUnitNamestring
buyerNamestring
issueDatestring
dueDatestring
itemslistë
amountSplitByPaymentMethodobject
hasFiscalReceiptboolean
posobject

curl -X POST "https://<baza>/api/pos/sale" \
  -H "x-api-key: $ZEN365_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationName": "<emri i organizatës>",
    "organizationUnitName": "<organization unit name>",
    "buyerName": "<existing buyer name>",
    "issueDate": "<DD/MM/YYYY>",
    "dueDate": "<DD/MM/YYYY>",
    "items": [
      {
        "qty": 1,
        "unitPriceWithVat": 2.5,
        "itemCode": "<item code>"
      }
    ],
    "amountSplitByPaymentMethod": {
      "cash": 2.5,
      "pos": 0
    },
    "hasFiscalReceipt": false,
    "pos": {
      "localSaleId": "<id lokale e shitjes>",
      "operation": "sale"
    }
  }'

Pyetje për integrimin? Na shkruani te contact@zen365.ai.