Idempotencia

Nyugta beküldésekor hálózati hiba esetén biztonságosan újrapróbálkozhatsz anélkül, hogy véletlenül duplikált nyugtát hoznál létre.

Idempotency-Key fejléc

A POST /v1/receipts végpont kötelezően megköveteli az Idempotency-Key fejlécet — egy általad generált, kérésenként egyedi azonosítót (pl. UUID):

curl -X POST https://api.fiscon.hu/v1/receipts \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx" \
    -H "Idempotency-Key: 6f1e2c2a-2a3b-4d3e-9c1a-8b2f6e6c2b21" \
    -H "Content-Type: application/json" \
    -d '{ "...": "..." }'

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

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode(['...' => '...']),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
        'Idempotency-Key: '.Str::uuid(),
        'Content-Type: application/json',
    ],
]);

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

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;

$response = Http::withToken(config('services.fiscon.key'))
    ->withHeader('Idempotency-Key', (string) Str::uuid())
    ->post('https://api.fiscon.hu/v1/receipts', [
        // ...
    ]);

const response = await fetch('https://api.fiscon.hu/v1/receipts', {
    method: 'POST',
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
        'Idempotency-Key': crypto.randomUUID(),
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({ /* ... */ }),
});

Viselkedés

• Ugyanazzal a kulccsal és ugyanazzal a kérés-törzzsel érkező ismételt kérés az eredeti válasszal tér vissza, új nyugta létrehozása nélkül.
• Ugyanazzal a kulccsal, de eltérő kérés-törzzsel érkező kérés 409 IDEMPOTENCY_CONFLICT hibát ad.
• A kulcs hatóköre szervezet + környezet + végpont + kulcs kombinációra vonatkozik — más szervezet vagy környezet ugyanazt a kulcsot újra felhasználhatja.
• Az Idempotency-Key fejléc jelenleg csak a POST /v1/receipts végponton kötelező; hiányában a kérés 422 VALIDATION_FAILED hibát ad.
• Egy idempotencia-rekord 24 óráig érvényes a létrehozásától számítva. Ezután ugyanaz a kulcs újra felhasználható, és egy új, önálló nyugtát fog létrehozni.

Javaslat

Generálj egy új, egyedi Idempotency-Key-t minden logikai nyugta-beküldési kísérlethez (pl. egy fizikai tranzakcióhoz), és hálózati hiba vagy időtúllépés esetén ugyanazzal a kulccsal próbálkozz újra. Ne generálj új kulcsot minden újrapróbálkozáshoz — az pont a duplikáció-védelem célját hiúsítaná meg.