Manual programisty: Publiczne API v1

1. Informacje ogólne

Adres TWOJA-DOMENA to domena instancji (ta sama, na której działa strona zapisu). API jest wyłącznie do odczytu: nie tworzy ani nie zmienia danych.

2. Autoryzacja

Klucz API należy przesłać w nagłówku HTTP X-API-Key. Klucz generuje administrator w panelu (Ustawienia → Klucze API) i przekazuje go odbiorcy.

X-API-Key: TWOJ_KLUCZ_API

Można wydać wiele kluczy dla różnych odbiorców i wyłączać je niezależnie. Wyłączenie lub usunięcie klucza odbiera dostęp natychmiast.

3. Endpoint: aktywne webinary

Pola pozycji

4. Endpoint: aktywne kursy

Pola pozycji

5. Przykład zapytania (cURL)

curl -X GET "https://TWOJA-DOMENA/api/public/v1/webinars" \
  -H "X-API-Key: TWOJ_KLUCZ_API"

curl -X GET "https://TWOJA-DOMENA/api/public/v1/courses" \
  -H "X-API-Key: TWOJ_KLUCZ_API"

6. Przykład zapytania (JavaScript / fetch)

const response = await fetch("https://TWOJA-DOMENA/api/public/v1/webinars", {
  method: "GET",
  headers: { "X-API-Key": "TWOJ_KLUCZ_API" }
});

if (!response.ok) {
  throw new Error("API zwrocilo status " + response.status);
}

const webinars = await response.json();
console.log(webinars.length, "aktywnych webinarow");

7. Przykład zapytania (PHP)

<?php
$ch = curl_init("https://TWOJA-DOMENA/api/public/v1/courses");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: TWOJ_KLUCZ_API"]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status === 200) {
    $courses = json_decode($body, true);
    foreach ($courses as $course) {
        echo $course["title"] . "\n";
    }
}

8. Odpowiedzi API

8.1 Sukces (HTTP 200) – webinary

[
  {
    "slug": "audyt-sieci-20260917",
    "title": "Audyt bezpieczenstwa sieci",
    "description": "Jak wykryc luki, zanim zrobi to ktos inny.",
    "startsAt": "2026-09-17T09:00:00+02:00",
    "endsAt": "2026-09-17T10:30:00+02:00",
    "timezone": "Europe/Warsaw",
    "registrationOpen": true,
    "capacity": 100,
    "registeredCount": 42,
    "registrationUrl": "https://TWOJA-DOMENA/w/audyt-sieci-20260917"
  }
]

8.2 Sukces (HTTP 200) – kursy

[
  {
    "slug": "podstawy-eksploatacji",
    "title": "Podstawy eksploatacji sieci wodociagowej",
    "subtitle": "Kurs dla poczatkujacych",
    "description": "Od podstaw do samodzielnej pracy.",
    "category": "Eksploatacja",
    "level": "BASIC",
    "durationMinutes": 180,
    "free": false,
    "priceGross": 490.00,
    "currency": "PLN",
    "enrolledCount": 128,
    "courseUrl": "https://TWOJA-DOMENA/kurs/podstawy-eksploatacji"
  }
]

Brak pozycji zwraca pustą tablicę [] ze statusem 200 – to nie jest błąd.

8.3 Błędy

Ciało błędu ma postać { "message": "...", "fields": {} }.

9. Dobre praktyki po stronie klienta

• Wysyłaj żądania wyłącznie przez HTTPS.
• Trzymaj klucz po stronie serwera. Nie umieszczaj go w kodzie strony ani w aplikacji przeglądarkowej, gdzie każdy go odczyta.
• Maskuj X-API-Key w logach aplikacyjnych.
• Buforuj odpowiedzi po swojej stronie (np. 1–5 minut). Dane zmieniają się rzadko, a odpytywanie co sekundę jest zbędne.
• Przy statusie 401 nie ponawiaj automatycznie – sprawdź, czy klucz nie został wyłączony lub usunięty.
• Przy błędach 5xx zastosuj ponawianie z limitem prób i narastającym odstępem (backoff).

10. Checklista testów integracyjnych

• Poprawne żądanie z ważnym kluczem zwraca HTTP 200 i tablicę JSON.
• Brak nagłówka X-API-Key zwraca HTTP 401.
• Błędny klucz zwraca HTTP 401.
• Wyłączenie klucza w panelu natychmiast skutkuje HTTP 401.
• Żądanie metodą POST pod adres endpointu zwraca HTTP 405.
• Instancja bez aktywnych pozycji zwraca pustą tablicę [] ze statusem 200.