Krijo fature porosi (Order) (v1)

POST /api/v1/invoice/order Requires authentication Rate limited by the `api-global` limiter v1

Send a bearer token in the Authorization header.

Regjistron konsumin qe ka nisur pa e mbyllur pagesen. Perdoret ne cift me faturen permbledhese: porosia hap tavolinen, permbledhesja e paguan.

Mos dergoni payment_method: ai vendoset vete ne ORDER.
Ruani iic qe ju kthehet. Ai eshte celesi me te cilin porosia mbyllet me vone.
Nje tavoline mund te kete disa porosi te hapura njeheresh.

Zbritja mbi te gjithe faturen i perket permbledheses, jo porosise. Porosia nuk pranon invoice_discount_type dhe invoice_discount_value, sepse permbledhesja i kopjon rreshtat nga porosite dhe nje zbritje mbi te gjithe porosine nuk kalon dot tek ajo.

Zbritja per rresht kalon: lines[].discount ruhet mbi rreshtin e porosise dhe permbledhesja e merr bashke me te, keshtu qe tavolina paguan pikerisht sa tregoi porosia.

Full URL: https://fature.al/api/v1/invoice/order

Body parameters

Name	Type	Required	Description
internalId	string	yes	ID unike e fatures ne sistemin tuaj. Sherben edhe si celes idempotence.
client	object, nullable	no	Bleresi. Opsional si tek fatura cash: pa te porosia i leshohet klientit te rastit. Me `client.internal_id` merret nje klient i ruajtur, ndryshe `client.name` behet i detyrueshem sapo dergoni cdo fushe tjeter te tij.
client.internal_id	integer, nullable	no	ID e nje klienti te ruajtur ne fature.al. Kur e dergoni, fushat e tjera nuk lexohen.
client.name	string, nullable	no	Emri i bleresit.
client.id	object, nullable	no	Dokumenti i identifikimit te bleresit, si objekt me `type` dhe `id`.
client.id.type	string, nullable	no	NUIS, VAT ose TAX per kompani; ID, PASS ose SOC per person.
client.id.id	string, nullable	no	Numri i dokumentit te identifikimit.
client.address	string, nullable	no	Adresa e bleresit, kur klienti eshte i emeruar.
client.city	string, nullable	no	Qyteti i bleresit, kur klienti eshte i emeruar.
client.country	string, nullable	no	Kodi i shtetit ISO 3166-1 alpha-3. ALB kur mungon.
lines	array	yes	Rreshtat e fatures, me te njejtat fusha si tek Cash.
lines[].product_name	string	yes	Emri i produktit.
lines[].product_code	string	yes	Kodi i produktit.
lines[].unit	string	yes	Njesia matese.
lines[].quantity	number	yes
lines[].price	number	yes
lines[].total	number	yes	Totali i rreshtit, me TVSH.
lines[].discount	number, min 0, max 100, nullable	no	Zbritja e ketij rreshti, ne perqindje mbi cmimin e njesise. Eshte opsionale: pa te, ose me vlere bosh, rreshti kalon pikerisht si me pare dhe mungesa e saj nuk kthen kurre gabim. `price` mbetet cmimi i plote i njesise, ndersa `total` vjen tashme i ulur: `price` here `quantity`, me zbritjen e hequr. Nje `total` qe nuk perputhet me ate shifer e refuzon kerkesen me `400`, dhe `errors` tregon cili eshte rreshti dhe cila vlere pritej.
lines[].vat	integer	yes	Shkalla e TVSH. Kur biznesi juaj nuk eshte ne skemen e TVSH-se, rreshti regjistrohet me TVSH `0` dhe me perjashtim `TAX_FREE` sido qe ta dergoni kete fushe. Kerkesa nuk refuzohet.
lines[].vat_exempt_type	string, nullable	no	Arsyeja e perjashtimit nga TVSH, kur rreshti eshte i perjashtuar.
currency	string, nullable	no	Monedha e porosise. Pa te merret ALL.
exchange_rate	number, nullable	no	Sa leke vlen nje njesi e monedhes se porosise. Pa te merret 1.
supply_start_date	string, nullable	no	Fillimi i periudhes se furnizimit.
supply_end_date	string, nullable	no	Fundi i periudhes se furnizimit.
notes	string, nullable	no	Shenime qe shfaqen ne porosi.

Responses

201 Created

Field	Type	Description
status	boolean
data	object
data.invoice	object
data.invoice.isOrderInvoice	boolean	Always true. The key marks the invoice as an Order
data.invoice.summaryInvoiceId	integer, nullable	Id of the Summary invoice that settled this Order. The key appears only once it has been settled, so a freshly issued Order does not carry it

400 Te dhena te paplota ose te pavlefshme. `errors` thote sakte cfare duhet plotesuar.

Field	Type	Description
status	boolean	Always false. A successful response carries `status: true` and a `data` object instead
message	string	The exception message. Empty when the failure carries no exception of its own
errors	array	Messages to show the operator or to log. Absent when the failure has nothing to add beyond `message`

403 Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.

Field	Type	Description
status	boolean	Always false. A successful response carries `status: true` and a `data` object instead
message	string	The exception message. Empty when the failure carries no exception of its own
errors	array	Messages to show the operator or to log. Absent when the failure has nothing to add beyond `message`

409 Nje fature me kete `internalId` po procesohet ose ekziston tashme per kete vit.

Field	Type	Description
status	boolean	Always false. A successful response carries `status: true` and a `data` object instead
message	string	The exception message. Empty when the failure carries no exception of its own
errors	array	Messages to show the operator or to log. Absent when the failure has nothing to add beyond `message`

422 Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`. `internalId` qe mungon kthehet me zarfin standard te gabimit.

Field	Type	Description
success	boolean	Always false
message	string	A single summary line, the same for every validation failure
errors	object	The failing fields, each with the messages for it. Dotted keys point into nested objects and array items, e.g. `lines.0.quantity`

429 Kufiri i kerkesave u arrit. Kufiri per endpoint kthen zarfin standard te gabimit; kufiri i pergjithshem kthen vetem `message` bashke me header-in `Retry-After`.

Field	Type	Description
status	boolean	Always false. A successful response carries `status: true` and a `data` object instead
message	string	The exception message. Empty when the failure carries no exception of its own
errors	array	Messages to show the operator or to log. Absent when the failure has nothing to add beyond `message`

500 Gabim i papritur ne server.

Field	Type	Description
status	boolean	Always false. A successful response carries `status: true` and a `data` object instead
message	string	The exception message. Empty when the failure carries no exception of its own
errors	array	Messages to show the operator or to log. Absent when the failure has nothing to add beyond `message`

503 Sherbimi i fiskalizimit eshte i paarritshem. Fatura ruhet dhe fiskalizohet automatikisht me vone.

Field	Type	Description
status	boolean	Always false. A successful response carries `status: true` and a `data` object instead
message	string	The exception message. Empty when the failure carries no exception of its own
errors	array	Messages to show the operator or to log. Absent when the failure has nothing to add beyond `message`

Example request

cURL

curl -X POST 'https://fature.al/api/v1/invoice/order' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'X-Client-Id: YOUR_CLIENT_ID' \
  -H 'X-Client-Secret: YOUR_CLIENT_SECRET' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "internalId": "ORD-001",
    "client": {
        "internal_id": 1,
        "name": "Klient i rastit",
        "id": {
            "type": "type",
            "id": "L62221018T"
        },
        "address": "1 Example Street",
        "city": "Berlin",
        "country": "US"
    },
    "lines": [
        {
            "product_name": "Kafe",
            "product_code": "KAF-001",
            "unit": "cope",
            "quantity": 2,
            "price": 1999,
            "total": 4200,
            "discount": 10,
            "vat": 20,
            "vat_exempt_type": "vat exempt type"
        }
    ],
    "currency": "ALL",
    "exchange_rate": 100.5,
    "supply_start_date": "2026-09-01",
    "supply_end_date": "2026-09-30",
    "notes": "Tavolina 4"
}'

PHP (Laravel)

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'Authorization' => 'Bearer YOUR_TOKEN',
    'X-Client-Id' => 'YOUR_CLIENT_ID',
    'X-Client-Secret' => 'YOUR_CLIENT_SECRET',
    'Accept' => 'application/json',
    'Content-Type' => 'application/json',
])->post('https://fature.al/api/v1/invoice/order', [
    'internalId' => 'ORD-001',
    'client' => [
        'internal_id' => 1,
        'name' => 'Klient i rastit',
        'id' => [
            'type' => 'type',
            'id' => 'L62221018T',
        ],
        'address' => '1 Example Street',
        'city' => 'Berlin',
        'country' => 'US',
    ],
    'lines' => [
        [
            'product_name' => 'Kafe',
            'product_code' => 'KAF-001',
            'unit' => 'cope',
            'quantity' => 2,
            'price' => 1999,
            'total' => 4200,
            'discount' => 10,
            'vat' => 20,
            'vat_exempt_type' => 'vat exempt type',
        ],
    ],
    'currency' => 'ALL',
    'exchange_rate' => 100.5,
    'supply_start_date' => '2026-09-01',
    'supply_end_date' => '2026-09-30',
    'notes' => 'Tavolina 4',
]);

$data = $response->json();

PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client();

$response = $client->request('POST', 'https://fature.al/api/v1/invoice/order', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_TOKEN',
        'X-Client-Id' => 'YOUR_CLIENT_ID',
        'X-Client-Secret' => 'YOUR_CLIENT_SECRET',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'internalId' => 'ORD-001',
        'client' => [
            'internal_id' => 1,
            'name' => 'Klient i rastit',
            'id' => [
                'type' => 'type',
                'id' => 'L62221018T',
            ],
            'address' => '1 Example Street',
            'city' => 'Berlin',
            'country' => 'US',
        ],
        'lines' => [
            [
                'product_name' => 'Kafe',
                'product_code' => 'KAF-001',
                'unit' => 'cope',
                'quantity' => 2,
                'price' => 1999,
                'total' => 4200,
                'discount' => 10,
                'vat' => 20,
                'vat_exempt_type' => 'vat exempt type',
            ],
        ],
        'currency' => 'ALL',
        'exchange_rate' => 100.5,
        'supply_start_date' => '2026-09-01',
        'supply_end_date' => '2026-09-30',
        'notes' => 'Tavolina 4',
    ],
]);

$data = json_decode((string) $response->getBody(), true);

JavaScript

const response = await fetch('https://fature.al/api/v1/invoice/order', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'X-Client-Id': 'YOUR_CLIENT_ID',
    'X-Client-Secret': 'YOUR_CLIENT_SECRET',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "internalId": "ORD-001",
      "client": {
          "internal_id": 1,
          "name": "Klient i rastit",
          "id": {
              "type": "type",
              "id": "L62221018T"
          },
          "address": "1 Example Street",
          "city": "Berlin",
          "country": "US"
      },
      "lines": [
          {
              "product_name": "Kafe",
              "product_code": "KAF-001",
              "unit": "cope",
              "quantity": 2,
              "price": 1999,
              "total": 4200,
              "discount": 10,
              "vat": 20,
              "vat_exempt_type": "vat exempt type"
          }
      ],
      "currency": "ALL",
      "exchange_rate": 100.5,
      "supply_start_date": "2026-09-01",
      "supply_end_date": "2026-09-30",
      "notes": "Tavolina 4"
  })
});

const data = await response.json();

Example response

201

{
    "status": true,
    "data": {
        "invoice": {
            "isOrderInvoice": true,
            "summaryInvoiceId": 1
        }
    }
}

400

{
    "status": true,
    "message": "Hello there",
    "errors": [
        "errors"
    ]
}

403

{
    "status": true,
    "message": "Hello there",
    "errors": [
        "errors"
    ]
}

409

{
    "status": true,
    "message": "Hello there",
    "errors": [
        "errors"
    ]
}

422

{
    "success": true,
    "message": "Hello there",
    "errors": []
}

429

{
    "status": true,
    "message": "Hello there",
    "errors": [
        "errors"
    ]
}

500

{
    "status": true,
    "message": "Hello there",
    "errors": [
        "errors"
    ]
}

503

{
    "status": true,
    "message": "Hello there",
    "errors": [
        "errors"
    ]
}