Fejlesztői dokumentáció

Gyors áttekintés

Kapcsolódás alapjai

Az API-kulcsot kizárólag szerveroldali programban tárold. Ne kerüljön böngészőben futó JavaScriptbe, mobilalkalmazásba, nyilvános GitHub-tárolóba vagy naplóba.

Authorization: Bearer ny_xxxxxxxxxxxxxxxxxxxxxxxxx

Idempotency-Key – duplikált nyugták elleni védelem

Nyugta létrehozásakor és sztornózáskor kötelező egy, a külső rendszer által generált egyedi kérésazonosítót küldeni az Idempotency-Key HTTP-fejlécben.

Ha egy válasz hálózati hiba miatt nem érkezik meg, ugyanaz a kérés ugyanazzal a kulccsal biztonságosan újraküldhető. Más adatok ugyanazzal a kulccsal HTTP 409 hibát eredményeznek.

Nyugta kiállítása

POST/receipts

Futtatható cURL-példa

curl --request POST 'https://nyugtazom.hu/api/v1/receipts' \
  --header 'Authorization: Bearer SAJAT_API_KULCS' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  --data-raw '{
    "service": "Géllakk készítés",
    "price": 8500,
    "payment_method": "card",
    "customer_name": "Kiss Anna",
    "customer_email": "anna@example.com",
    "print_size": "A4"
  }'

Kötelező: service, price, payment_method (cash vagy card), print_size (A4, 58mm, 80mm). A név és az e-mail opcionális. Éles módban e-mail-cím esetén a PDF automatikusan kiküldésre kerül.

Sikeres válasz – HTTP 201

{
  "success": true,
  "environment": "live",
  "receipt": {
    "id": "123",
    "number": "NY-2026-000123",
    "status": "active",
    "service": "Géllakk készítés",
    "price": 8500,
    "payment_method": "card",
    "print_size": "A4",
    "pdf_url": "https://nyugtazom.hu/api/v1/receipts/123/pdf",
    "pdf_url_expires_in": 900,
    "email": {
      "requested": true,
      "status": "sent"
    }
  },
  "warning": null
}

Nyugta lekérdezése

GET/receipts/{id}

curl --request GET 'https://nyugtazom.hu/api/v1/receipts/123' \
  --header 'Authorization: Bearer SAJAT_API_KULCS' \
  --header 'Accept: application/json'

Siker esetén HTTP 200 válasz érkezik, ugyanazzal a success, environment, receipt és warning szerkezettel, mint kiállításkor.

PDF letöltése

GET/receipts/{id}/pdf

curl --request GET 'https://nyugtazom.hu/api/v1/receipts/123/pdf' \
  --header 'Authorization: Bearer SAJAT_API_KULCS' \
  --output nyugta-123.pdf

Siker esetén HTTP 200 és közvetlenül a bináris PDF-fájl érkezik application/pdf tartalomtípussal. Ennél a végpontnál nincs JSON-válasz. A nyugta JSON-válaszában kapott pdf_url 15 percig érvényes aláírt link, ezért közvetlenül böngészőből is megnyitható. Lejárat után kérdezd le ismét a nyugtát egy új linkért.

E-mail-cím javítása és a nyugta újraküldése

POST/receipts/{id}/resend-email

Ha a nyugta kiállításakor hibás e-mail-cím érkezett, ezzel a végponttal megadható a helyes cím. A Nyugtázom a nyugtához tárolt e-mail-címet is átírja, majd éles API-módban ugyanazt az archivált PDF-nyugtát elküldi az új címre.

Futtatható cURL-példa

curl --request POST 'https://nyugtazom.hu/api/v1/receipts/123/resend-email' \
  --header 'Authorization: Bearer SAJAT_API_KULCS' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Idempotency-Key: 1bf3af42-ef60-4b51-b2cc-9655f771e45f' \
  --data-raw '{
    "customer_email": "anna.helyes@example.com"
  }'

A customer_email kötelező és érvényes e-mail-formátumú legyen. Egy újraküldési művelethez új Idempotency-Key értéket használj. Ha ugyanazt a hálózati kérést kell megismételni, ugyanazt a kulcsot küldd újra, így nem küldünk véletlenül két példányt.

Sikeres éles válasz – HTTP 200

{
  "success": true,
  "environment": "live",
  "receipt": {
    "id": "123",
    "number": "NYGTA-2026-000123"
  },
  "email": {
    "address": "anna.helyes@example.com",
    "status": "sent",
    "database_updated": true,
    "message_id": "019c-example-message-id"
  },
  "warning": null
}

Ha a küldés technikai okból nem sikerül, az e-mail-cím akkor is frissül az adatbázisban. Ilyenkor az email.status értéke failed, és egy új műveletként új Idempotency-Key használatával ismét megpróbálható az újraküldés.

Adatbázis: éles módban csak az adott nyugtához tartozó customer_email_snapshot és a kapcsolódó ügyfélhivatkozás frissül. Más, korábban kiállított nyugták e-mail-címe nem módosul. Tesztmódban az api_test_receipts.customer_email mező frissül.

Sztornózás

POST/receipts/{id}/void

curl --request POST 'https://nyugtazom.hu/api/v1/receipts/123/void' \
  --header 'Authorization: Bearer SAJAT_API_KULCS' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Idempotency-Key: 2c98f4ab-a109-43c1-b390-ced23a7230c2' \
  --data-raw '{"reason":"A foglalást lemondták"}'

Sikeres válasz – HTTP 201

{
  "success": true,
  "environment": "live",
  "receipt": {
    "id": "124",
    "number": "NY-2026-000124",
    "status": "storno",
    "service": "Géllakk készítés",
    "price": -8500,
    "payment_method": "card",
    "print_size": "A4",
    "pdf_url": "https://nyugtazom.hu/api/v1/receipts/124/pdf",
    "pdf_url_expires_in": 900,
    "email": {
      "requested": false,
      "status": "not_requested"
    }
  },
  "warning": null
}

A válaszban szereplő receipt.id és receipt.number már az új sztornóbizonylat adata.

A sikeres válasz mezői

environment: live vagy test.

status: élesben active, void vagy storno; tesztben test_active, test_void vagy test_storno.

email.status: sent, failed, not_requested vagy tesztmódban suppressed_test.

warning: éles módban null; tesztmódban jelzi, hogy a bizonylat nem minősül valódi nyugtának.

Szerveroldali PHP-példa

<?php
$payload = json_encode([
    'service' => 'Géllakk készítés',
    'price' => 8500,
    'payment_method' => 'card',
    'customer_name' => 'Kiss Anna',
    'customer_email' => 'anna@example.com',
    'print_size' => 'A4',
], JSON_UNESCAPED_UNICODE);
$idempotencyKey = bin2hex(random_bytes(16));

$curl = curl_init('https://nyugtazom.hu/api/v1/receipts');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('NYUGTAZOM_API_KEY'),
        'Content-Type: application/json',
        'Accept: application/json',
        'Idempotency-Key: ' . $idempotencyKey,
    ],
    CURLOPT_POSTFIELDS => $payload,
]);
$responseBody = curl_exec($curl);
$httpStatus = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
$response = json_decode($responseBody, true, 512, JSON_THROW_ON_ERROR);

Hibakezelés

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A megadott adatok hiányosak vagy hibásak.",
    "fields": {"payment_method": ["Engedélyezett értékek: cash, card."]}
  }
}