Regjistro një kompani (v1): fature.al API

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

Send a bearer token, plus the X-Client-Id and X-Client-Secret headers in the Authorization header.

Krijon një kompani të re në fature.al, me përdoruesin e parë, njësinë e parë të biznesit, klientin e rastit, monedhat dhe një abonim aktiv. Është hapi i parë i regjistrimit; hapat e tjerë thirren me token-in që kthen.

Përdoreni vetëm për biznese që nuk janë ende në fature.al. Për një kompani ekzistuese përdorni drejtpërdrejt endpoint-et POST /on-boarding/* me token-in e saj.

Llogaria e token-it duhet të jetë e autorizuar për regjistrim; ndryshe kërkesa refuzohet me 200 dhe status: false.
nuis duhet të jetë një NIPT i paregjistruar në fature.al dhe i njohur nga administrata tatimore. Shkronjat e vogla pranohen dhe kthehen në të mëdha.
email bëhet email-i dhe emri i përdoruesit të parë, ndaj duhet të jetë i papërdorur në fature.al.
lastNonCashEInvoiceNumber vendos numrin nga i cili vazhdon numërimi i faturave jo-cash dhe i e-faturave për vitin aktual.

Përgjigja mban user.token, token-in API të përdoruesit të parë, dhe branch.id, id-në e njësisë së biznesit. Ruajini të dyja: token-i shfaqet vetëm këtu dhe përdoret për të gjithë hapat e tjerë, kurse id-ja e njësisë duhet te POST /on-boarding/branch/{id}, POST /on-boarding/user dhe POST /on-boarding/fiscal-device.

Sandbox#

Në sandbox, NIPT-i L62221018T kalon në një rrjedhë prove: nuk krijohet kompani e re, por një përdorues dhe një njësi biznesi nën kompaninë sandbox, dhe user.token është një token real për hapat e tjerë. Email-it i shtohet prapashtesa +sandbox-XXXXXXXX, kështu që të njëjtin email mund ta dërgoni sa herë të doni. Në live ky NIPT trajtohet si çdo NIPT tjetër.

URL-ja e plotë: https://fature.al/api/v1/register

Body parameters

Name	Tipi	E detyrueshme	Përshkrimi
nuis	string	yes	NIPT-i i kompanisë që regjistrohet: një shkronjë, tetë shifra, një shkronjë. I detyrueshëm. Kontrollohet në regjistrin fiskal, dhe një NIPT i regjistruar tashmë në fature.al refuzohet.
name	string, maxLength 255	yes	Emri i kompanisë. I detyrueshëm.
address	string, maxLength 255	yes	Adresa e selisë së kompanisë, siç është regjistruar. E detyrueshme.
administrator	string, maxLength 255	yes	Administratori i kompanisë. I detyrueshëm.
phone	string, maxLength 50	yes	Telefoni i kontaktit të kompanisë. I detyrueshëm.
email	string<email>, maxLength 255	yes	Email-i i përdoruesit të parë, ai që do të administrojë llogarinë. I detyrueshëm.
issuerInVat	boolean, nullable	no	A është kompania në skemën e TVSH-së. Boolean; pa të merret `false`, dhe faturat dalin pa TVSH.
lastNonCashEInvoiceNumber	string, maxLength 50, nullable	no	Numri i fundit i faturës jo-cash ose e-faturës i lëshuar në sistemin e mëparshëm, që numërimi të vazhdojë prej tij dhe të mos rifillojë nga 1.

Përgjigjet

200 Kur llogaria nuk është e autorizuar për regjistrim, kur NIPT-i është i regjistruar tashmë ose nuk gjendet te administrata tatimore, ose kur email-i është në përdorim, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message`.

Field	Tipi	Përshkrimi
status	boolean
data	object
data.user	object
data.user.token	string	Token-i API i përdoruesit të parë, 96 shkronja dhe shifra. Shfaqet vetëm këtu; me të bëhen të gjithë hapat e tjerë të regjistrimit
data.user.id	integer	Id-ja e përdoruesit në fature.al; duhet te `POST /on-boarding/user/{id}`
data.branch	object
data.branch.id	integer	Id-ja e njësisë së biznesit; duhet te `POST /on-boarding/branch/{id}`, `POST /on-boarding/user` dhe `POST /on-boarding/fiscal-device`
data.branch.name	string	Emri i njësisë, i formuar nga emri i kompanisë dhe `Selia Qendrore`

401 Unauthenticated

Field	Tipi	Përshkrimi
message	string

422 Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.

Field	Tipi	Përshkrimi
success	boolean	Gjithmonë false
message	string	Një rresht përmbledhës, i njëjtë për çdo dështim validimi
errors	object	Fushat që nuk kaluan validimin, secila me mesazhet e veta. Çelësat me pikë tregojnë brenda objekteve dhe elementëve të array-ve, p.sh. `lines.0.quantity`

Shembull kërkese

cURL

curl -X POST 'https://fature.al/api/v1/register' \
  -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 '{
    "nuis": "L62221018T",
    "name": "Ei3 Software Solution shpk",
    "address": "Rruga e Kavajes 12, Tirane",
    "administrator": "Festim Peposhi",
    "phone": "+355 69 000 0000",
    "email": "[email protected]",
    "issuerInVat": true,
    "lastNonCashEInvoiceNumber": 412
}'

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/register', [
    'nuis' => 'L62221018T',
    'name' => 'Ei3 Software Solution shpk',
    'address' => 'Rruga e Kavajes 12, Tirane',
    'administrator' => 'Festim Peposhi',
    'phone' => '+355 69 000 0000',
    'email' => '[email protected]',
    'issuerInVat' => true,
    'lastNonCashEInvoiceNumber' => 412,
]);

$data = $response->json();

PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client();

$response = $client->request('POST', 'https://fature.al/api/v1/register', [
    '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' => [
        'nuis' => 'L62221018T',
        'name' => 'Ei3 Software Solution shpk',
        'address' => 'Rruga e Kavajes 12, Tirane',
        'administrator' => 'Festim Peposhi',
        'phone' => '+355 69 000 0000',
        'email' => '[email protected]',
        'issuerInVat' => true,
        'lastNonCashEInvoiceNumber' => 412,
    ],
]);

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

JavaScript

const response = await fetch('https://fature.al/api/v1/register', {
  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({
      "nuis": "L62221018T",
      "name": "Ei3 Software Solution shpk",
      "address": "Rruga e Kavajes 12, Tirane",
      "administrator": "Festim Peposhi",
      "phone": "+355 69 000 0000",
      "email": "[email protected]",
      "issuerInVat": true,
      "lastNonCashEInvoiceNumber": 412
  })
});

const data = await response.json();

Shembull përgjigjeje

200

{
    "status": true,
    "data": {
        "user": {
            "token": "k7Qm2ZpX9vL4rT1nB8wJ3cH6yF0sD5aG2eV7uN4iK9oP1lM8qR3tW6xY0zA5bC2dE7fH4gJ1hK9jL6mN3pQ8rS5tU2vW7xZ0",
            "id": 7
        },
        "branch": {
            "id": 12,
            "name": "Alpha SHPK - Selia Qendrore"
        }
    }
}

401

{
    "message": "Unauthenticated."
}

422

{
    "success": false,
    "message": "Te dhena jo te sakta",
    "errors": []
}