Krijo klient (v2) (v2) — fature.al API

POST /api/v2/clients Requires authentication Rate limited by the `api-global` limiter v2

Send a bearer token in the Authorization header.

Trupi eshte nje bashkim i diskriminuar nga fusha type, e cila pranon company ose person. Plotesohet vetem objekti qe i perket llojit.

`type`	Objekti	Fushat e detyrueshme
`company`	`company`	`name`, `id`
`person`	`person`	`first_name`, `last_name`, `id`

Identifikuesi#

Jepet gjithmone si objekt id me type dhe value, dhe vlerat e lejuara varen nga lloji:

kompani: nuis, vat, tax;
person: id, passport, social.

Objektet e perbashketa#

address (line, city, country me tre shkronja) dhe contact (phone, email) jane opsionale dhe vlejne per te dy llojet. company.category pranon business, bank ose exchange.

Full URL: https://fature.al/api/v2/clients

Changed since v1

no longer accepts the body parameter nationality_code
no longer accepts the body parameter nationality_id
no longer accepts the body parameter telephone
no longer accepts the body parameter email
no longer accepts the body parameter gender
no longer accepts the body parameter birthday
requires a new body parameter type
requires a new body parameter company
requires a new body parameter person
201 no longer returns data.client.name
201 no longer returns data.client.client_type
201 no longer returns data.client.company_name
201 no longer returns data.client.company_type
201 no longer returns data.client.nipt
201 no longer returns data.client.first_name
201 no longer returns data.client.surname
201 no longer returns data.client.birthday
201 no longer returns data.client.id_type
201 no longer returns data.client.id_num
201 no longer returns data.client.nationality_code
201 no longer returns data.client.nationality_id
201 no longer returns data.client.telephone
201 no longer returns data.client.email
201 data.client.address changed from string, nullable to object
201 no longer returns data.client.city
accepts a new optional body parameter address
accepts a new optional body parameter contact
201 data.client.address is now never null
201 now returns data.client.type
201 now returns data.client.company
201 now returns data.client.company.name
201 now returns data.client.company.category
201 now returns data.client.company.id
201 now returns data.client.company.id.type
201 now returns data.client.company.id.value
201 now returns data.client.person
201 now returns data.client.person.first_name
201 now returns data.client.person.last_name
201 now returns data.client.person.birthday
201 now returns data.client.person.id
201 now returns data.client.person.id.type
201 now returns data.client.person.id.value
201 now returns data.client.address.line
201 now returns data.client.address.city
201 now returns data.client.address.country
201 now returns data.client.contact
201 now returns data.client.contact.phone
201 now returns data.client.contact.email
201 now returns data.client.verified
201 now returns data.client.updated_at

Body parameters

Name	Type	Required	Description
type	string	yes	Lloji i klientit, i cili vendos se cili objekt plotesohet: `company` ose `person`. Ne editim eshte i pandryshueshem, prandaj nje `type` i ndryshem nga ai ekzistues refuzohet me `422`.
company	object	yes	Required depending on type.
company.name	string, maxLength 255, nullable	yes	Required depending on type.
company.category	string, nullable	no
company.id	object	yes	Required depending on type.
company.id.type	string	yes	Required when company.id is present.
company.id.value	string, maxLength 20	yes	Required when company.id is present.
person	object	yes	Required depending on type.
person.first_name	string, maxLength 255, nullable	yes	Required depending on type.
person.last_name	string, maxLength 255, nullable	yes	Required depending on type.
person.birthday	string<date-time>, nullable	no
person.id	object	yes	Required depending on type.
person.id.type	string	yes	Required when person.id is present.
person.id.value	string, maxLength 255	yes	Required when person.id is present.
address	object, nullable	no	Adresa e klientit. Opsionale, dhe e njejta per te dy llojet.
address.line	string, maxLength 255, nullable	no
address.city	string, maxLength 50, nullable	no
address.country	string, minLength 3, maxLength 3, nullable	no
contact	object, nullable	no	Kontaktet e klientit: telefoni dhe email-i. Opsionale.
contact.phone	string, maxLength 255, nullable	no
contact.email	string<email>, maxLength 255, nullable	no
customer_number	string, maxLength 30, nullable	no	Numri juaj i klientit, nese e mbani nje te tille ne sistemin tuaj.

Responses

201 Created

Field	Type	Description
status	boolean
data	object
data.client	object
data.client.id	integer
data.client.type	string	`company` or `person`
data.client.company	object, nullable	Filled when `type` is `company`, null otherwise
data.client.company.name	string, nullable
data.client.company.category	string, nullable	`business`, `bank` or `exchange`, or null when unclassified
data.client.company.id	object
data.client.company.id.type	any	`nuis`, `vat` or `tax` on a company; `id`, `passport` or `social` on a person
data.client.company.id.value	any	The identifier itself, null when the client has none recorded
data.client.person	object, nullable	Filled when `type` is `person`, null otherwise
data.client.person.first_name	string, nullable
data.client.person.last_name	string, nullable
data.client.person.birthday	string, nullable	Date of birth (YYYY-MM-DD)
data.client.person.id	object
data.client.person.id.type	any	`nuis`, `vat` or `tax` on a company; `id`, `passport` or `social` on a person
data.client.person.id.value	any	The identifier itself, null when the client has none recorded
data.client.address	object
data.client.address.line	string, nullable	Street address
data.client.address.city	string, nullable
data.client.address.country	string, nullable	ISO 3166-1 alpha-3 country code
data.client.contact	object
data.client.contact.phone	string, nullable
data.client.contact.email	string, nullable
data.client.customer_number	string, nullable	Your own reference for this client, when one was given
data.client.verified	boolean	Whether the identifier was confirmed against the fiscal register
data.client.created_at	string, nullable	Creation timestamp, ISO 8601
data.client.updated_at	string, nullable	Last update timestamp, ISO 8601

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 Ekziston tashme nje regjistrim me te njejtat te dhena.

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`.

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`

Example request

cURL

curl -X POST 'https://fature.al/api/v2/clients' \
  -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 '{
    "type": "company",
    "company": {
        "name": "Jane Doe",
        "category": "category",
        "id": {
            "type": "type",
            "value": "value"
        }
    },
    "person": {
        "first_name": "Jane",
        "last_name": "Doe",
        "birthday": "2026-01-15T09:30:00Z",
        "id": {
            "type": "type",
            "value": "value"
        }
    },
    "address": {
        "line": "line",
        "city": "Berlin",
        "country": "USx"
    },
    "contact": {
        "phone": "+15551234567",
        "email": "[email protected]"
    },
    "customer_number": "CL-00412"
}'

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/v2/clients', [
    'type' => 'company',
    'company' => [
        'name' => 'Jane Doe',
        'category' => 'category',
        'id' => [
            'type' => 'type',
            'value' => 'value',
        ],
    ],
    'person' => [
        'first_name' => 'Jane',
        'last_name' => 'Doe',
        'birthday' => '2026-01-15T09:30:00Z',
        'id' => [
            'type' => 'type',
            'value' => 'value',
        ],
    ],
    'address' => [
        'line' => 'line',
        'city' => 'Berlin',
        'country' => 'USx',
    ],
    'contact' => [
        'phone' => '+15551234567',
        'email' => '[email protected]',
    ],
    'customer_number' => 'CL-00412',
]);

$data = $response->json();

PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client();

$response = $client->request('POST', 'https://fature.al/api/v2/clients', [
    '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' => [
        'type' => 'company',
        'company' => [
            'name' => 'Jane Doe',
            'category' => 'category',
            'id' => [
                'type' => 'type',
                'value' => 'value',
            ],
        ],
        'person' => [
            'first_name' => 'Jane',
            'last_name' => 'Doe',
            'birthday' => '2026-01-15T09:30:00Z',
            'id' => [
                'type' => 'type',
                'value' => 'value',
            ],
        ],
        'address' => [
            'line' => 'line',
            'city' => 'Berlin',
            'country' => 'USx',
        ],
        'contact' => [
            'phone' => '+15551234567',
            'email' => '[email protected]',
        ],
        'customer_number' => 'CL-00412',
    ],
]);

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

JavaScript

const response = await fetch('https://fature.al/api/v2/clients', {
  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({
      "type": "company",
      "company": {
          "name": "Jane Doe",
          "category": "category",
          "id": {
              "type": "type",
              "value": "value"
          }
      },
      "person": {
          "first_name": "Jane",
          "last_name": "Doe",
          "birthday": "2026-01-15T09:30:00Z",
          "id": {
              "type": "type",
              "value": "value"
          }
      },
      "address": {
          "line": "line",
          "city": "Berlin",
          "country": "USx"
      },
      "contact": {
          "phone": "+15551234567",
          "email": "[email protected]"
      },
      "customer_number": "CL-00412"
  })
});

const data = await response.json();

Example response

201

{
    "status": true,
    "data": {
        "client": {
            "id": 1,
            "type": "type",
            "company": {
                "name": "Jane Doe",
                "category": "category",
                "id": {
                    "type": "type",
                    "value": "value"
                }
            },
            "person": {
                "first_name": "Jane",
                "last_name": "Doe",
                "birthday": "birthday",
                "id": {
                    "type": "type",
                    "value": "value"
                }
            },
            "address": {
                "line": "line",
                "city": "Berlin",
                "country": "US"
            },
            "contact": {
                "phone": "+15551234567",
                "email": "[email protected]"
            },
            "customer_number": "customer number",
            "verified": true,
            "created_at": "created at",
            "updated_at": "updated at"
        }
    }
}

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"
    ]
}