API i webhooki

Szybki start

Sprawdź, czy token działa:

curl -H "Authorization: Bearer TWOJ_TOKEN" \
     https://vouchermarket.pl/api/v1/me

W odpowiedzi dostaniesz dane firmy, plan i uprawnienia tokenu:

{
  "success": true,
  "data": {
    "company": { "uuid": "…", "display_name": "Salon Luna", "city": "Wrocław" },
    "plan":    { "name": "Pro", "slug": "pro" },
    "token":   { "name": "Integracja GabinetOnline", "abilities": ["vouchers:read","codes:redeem"] }
  }
}

Uwierzytelnianie

Każde zapytanie wymaga nagłówka Authorization: Bearer <token>. Token generujesz w panelu — przy tworzeniu wybierasz, co ma móc robić. Token widać tylko raz, w momencie utworzenia; potem przechowujemy wyłącznie jego skrót.

Dostępne uprawnienia:

Token jest zawsze związany z jedną firmą — nie trzeba (i nie da się) przekazywać company_id w zapytaniu. Każda odpowiedź zawiera wyłącznie Twoje dane.

Konwencje i limity

• Sukces: {"success": true, "data": …}
• Błąd: {"success": false, "error": {"code": "…", "message": "…"}}
• Daty w ISO 8601, kwoty jako liczby, waluta w osobnym polu.
• Listy są stronicowane: ?page= i ?per_page= (maks. 100, domyślnie 25). Metadane w polu meta.
• Limit: 120 zapytań na minutę. Po przekroczeniu HTTP 429.

Kody błędów, które warto obsłużyć:

Endpointy

Realizacja vouchera

Najpierw sprawdź kod — dowiesz się, czy nadaje się do realizacji i ile na nim zostało:

curl -H "Authorization: Bearer TWOJ_TOKEN" \
     https://vouchermarket.pl/api/v1/codes/LUNA-9F3K-220

{
  "success": true,
  "data": {
    "code": "LUNA-9F3K-220",
    "status": "active",
    "can_redeem": true,
    "voucher_name": "Masaż relaksacyjny 90 min",
    "face_value": 220.0,
    "remaining_value": 220.0,
    "sessions_total": null,
    "expires_at": "2027-10-26T12:00:00+02:00"
  }
}

Następnie zrealizuj. Dla voucherów kwotowych możesz rozliczyć część wartości:

curl -X POST \
     -H "Authorization: Bearer TWOJ_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"amount": 150, "note": "Wizyta 26.10"}' \
     https://vouchermarket.pl/api/v1/codes/LUNA-9F3K-220/redeem

{
  "success": true,
  "message": "Voucher zrealizowany pomyślnie.",
  "amount_used": 150.0,
  "remaining_value": 70.0,
  "new_status": "partially_used"
}

Webhooki

Zamiast odpytywać API w pętli, podaj adres, na który mamy wysyłać zdarzenia. Konfigurujesz go w panelu: adres musi używać HTTPS, wybierasz listę zdarzeń i dostajesz sekret do weryfikacji podpisu.

Każde zadanie przychodzi jako POST z nagłówkami:

Ponowienia: odpowiedz kodem 2xx, żeby potwierdzić odbiór. Przy innym kodzie lub braku odpowiedzi ponawiamy do 5 razy z odstępami 1 min, 5 min, 15 min, 1 h i 3 h. Po 20 kolejnych nieudanych dostawach endpoint jest automatycznie wyłączany — zobaczysz to w panelu i włączysz go z powrotem jednym kliknięciem.

Idempotencja: ta sama dostawa może przyjść więcej niż raz (np. gdy Twoja odpowiedź nie dotarła). Zapamiętuj X-VM-Delivery i pomijaj powtórzenia.

Weryfikacja podpisu

Podpisujemy <timestamp>.<surowe ciało żądania> algorytmem HMAC-SHA256 Twoim sekretem. Porównaj wynik metodą odporną na pomiar czasu i odrzuć żądania starsze niż kilka minut:

// PHP
$raw       = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_VM_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_VM_SIGNATURE'] ?? '';

// odrzuć stare żądania (ochrona przed powtórzeniem)
if (abs(time() - (int) $timestamp) > 300) {
    http_response_code(400);
    exit;
}

$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $raw, $SEKRET);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

$event = json_decode($raw, true);
// … obsłuż $event['event'] i $event['data']
http_response_code(200);

Zdarzenia

Każde żądanie ma tę samą kopertę:

{
  "event": "order.paid",
  "created_at": "2026-10-26T13:45:02+02:00",
  "data": { … }
}

"data": {
  "order_uuid": "…",
  "order_number": "VM/2026/000420",
  "voucher_name": "Masaż relaksacyjny 90 min",
  "code": "LUNA-9F3K-220",
  "customer_email": "klient@example.com",
  "recipient_name": "Anna",
  "total": 220.0,
  "company_payout": 211.2,
  "currency": "PLN",
  "payment_method": "stripe",
  "paid_at": "2026-10-26T13:45:02+02:00"
}

"data": {
  "code": "LUNA-9F3K-220",
  "voucher_name": "Masaż relaksacyjny 90 min",
  "method": "qr",
  "amount_used": 150.0,
  "remaining_value": 70.0,
  "sessions_total": null,
  "sessions_used": 1,
  "status": "partially_used",
  "redeemed_at": "2026-10-26T14:02:11+02:00"
}

"data": {
  "order_uuid": "…",
  "order_number": "VM/2026/000420",
  "voucher_name": "Masaż relaksacyjny 90 min",
  "total": 220.0,
  "currency": "PLN",
  "reason": "Rezygnacja klienta",
  "refunded_at": "2026-10-27T09:12:00+02:00"
}

"data": {
  "voucher_uuid": "…",
  "name": "Masaż relaksacyjny 90 min",
  "slug": "masaz-relaksacyjny-90-min-salon-luna-wroclaw",
  "type": "service",
  "price": 220.0,
  "currency": "PLN",
  "is_published": true,
  "published_at": "2026-10-26T10:00:00+02:00"
}