Hitelesítés

Az API minden kérését Bearer tokennel kell hitelesíteni, az admin felületen generált API-kulccsal.

API-kulcs formátuma

Egy API-kulcs mindig a következő alakú:

fis_{live|sandbox}_<secret>

Az előtag (fis_live_ vagy fis_sandbox_) határozza meg, hogy a kulcs melyik környezethez tartozik. Ez a besorolás nem módosítható utólag — ha másik környezethez van szükséged, generálj egy új kulcsot.

A kulcs egy szervezet (organization) egészéhez tartozik, nem egyetlen adóalanyhoz — egy kulccsal a szervezet összes adóalanyának adatai elérhetők. Ha adóalanyonként szeretnéd elkülöníteni a hozzáférést, hozz létre külön szervezetet adóalanyonként.

A titkos érték (secret) csak létrehozáskor jelenik meg egyszer, visszafejtve tárolva sosem kérdezhető le újra — a Fiscon csak a hash-elt értéket tárolja. Ha elveszik, vonj vissza egy kulcsot és generálj helyette újat.

Kérés hitelesítése

Csatold a kulcsot minden kérés Authorization fejlécében:

curl https://api.fiscon.hu/v1/receipts \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx"

$curl = curl_init('https://api.fiscon.hu/v1/receipts');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

use Illuminate\Support\Facades\Http;

$response = Http::withToken(config('services.fiscon.key'))
    ->get('https://api.fiscon.hu/v1/receipts');

$receipts = $response->json();

const response = await fetch('https://api.fiscon.hu/v1/receipts', {
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
    },
});

const receipts = await response.json();

Aldomain és környezet egyezése

A kulcs környezete rögzíti, melyik aldomainen fogadható el: egy fis_live_... kulcs csak az api.fiscon.hu, egy fis_sandbox_... kulcs csak a sandbox.fiscon.hu host felé küldött kérésekben érvényes. Ha a kettő nem egyezik, a kérés 401 UNAUTHENTICATED hibával elutasításra kerül, még akkor is, ha maga a kulcs egyébként érvényes — ez a leggyakoribb hiba sandbox-integráció közben.

Érvénytelen vagy hiányzó kulcs

A kérés 401 UNAUTHENTICATED választ kap az egységes hibaborítékban a következő esetekben:

• Az Authorization fejléc hiányzik, vagy nem Bearer fis_live_.../fis_sandbox_... formátumú.
• A kulcs nem létezik (törölve vagy elgépelve).
• A kulcs vissza lett vonva (revoked_at ki van töltve).
• A kulcsnak lejárati dátuma van, és az már elmúlt.
• A kulcs környezete nem egyezik a hívott aldomainnel — lásd fent.

Lásd a Hibakezelés oldalt a teljes hibaboríték formátumáért.

Kulcskezelés

Az API-kulcsokat az admin felület API kulcsok oldalán hozhatod létre, tekintheted meg és vonhatod vissza. Egy kulcs titkos értékét csak létrehozáskor mutatjuk meg egyszer — utána csak az előtag és az utolsó néhány karakter látható.

Minden kulcshoz opcionálisan lejárati dátum is beállítható; lejárat után a kulcs automatikusan érvénytelenné válik, visszavonás nélkül is. A kulcs utolsó használatának időpontját (last_used_at) minden sikeres hitelesített kérés frissíti — ez segít beazonosítani a már nem használt, biztonságosan visszavonható kulcsokat.