Publiczne API

Helpdesk udostępnia jedno publiczne API: punkt końcowy GraphQL. Każda operacja ze schematu jest osiągalna spoza przeglądarki przy użyciu osobistego tokena dostępu (Personal Access Token, PAT).

Ta strona jest kontraktem — co jest stabilne, jak się uwierzytelnić, co dają zakresy uprawnień i jaką postać mają błędy. CLI hdmx jest na nim zbudowane, a wersjonowanie API opisuje, jak ta powierzchnia się rozwija.

Punkt końcowy

POST https://<your-host>/backend/<subdomain>/api/<version>/graphql

• <subdomain> identyfikuje Twoje konto (ten sam identyfikator, którego używasz do logowania).
• <version> to datowana wersja API, na przykład 2026-07 — zobacz wersjonowanie API. Możesz też pominąć segment wersji i wywołać …/backend/<subdomain>/graphql; żądanie obsłuży wtedy najstarsza wspierana wersja, a każda odpowiedź powie Ci, która wersja odpowiedziała.

Uwierzytelnianie

Wyślij osobisty token dostępu jako poświadczenie Bearer:

Authorization: Bearer hdmx_<random>

PAT jest długowieczny (z obowiązkową datą wygaśnięcia), ograniczony zakresami uprawnień, przypisany do adresów IP i możliwy do unieważnienia. Jest powiązany z jednym kontem: okazanie tokena w subdomenie innego konta zostaje odrzucone z kodem HTTP 401.

Tworzenie tokena

Twórz tokeny i zarządzaj nimi samodzielnie w aplikacji agenta, w sekcji Settings → API tokens:

1. Kliknij New token.
2. Nadaj mu nazwę, którą później rozpoznasz.
3. Wybierz termin ważności (do 365 dni — opcja „nigdy" nie istnieje).
4. Ustaw politykę dostępu — włącz dokładnie te zasoby, których ten token potrzebuje, w trybie odczytu albo odczytu i zapisu. Domyślnie nie ma dostępu do niczego.
5. Dodaj co najmniej jeden adres IP lub CIDR do listy dozwolonych (wymagane — zobacz Lista dozwolonych adresów IP). Formularz może dodać Twój bieżący adres IP za Ciebie.
6. Sprawdź i utwórz. Pełny token jest pokazywany dokładnie raz — skopiuj go od razu. Przechowywany jest wyłącznie skrót, więc nie da się go wyświetlić ponownie; jeśli go zgubisz, wykonaj rotację tokena, aby otrzymać nowy.

Później możesz edytować politykę dostępu i listę dozwolonych adresów tokena, wykonać jego rotację (wydać nowy sekret, podczas gdy stary działa jeszcze przez krótki okres przejściowy, byś mógł się przełączyć bez przestoju) oraz unieważnić go. Przy każdym tokenie widać, kiedy i skąd był ostatnio używany, oraz dziennik ostatniej aktywności.

Zakresy uprawnień

Dostęp jest gruboziarnisty i zorganizowany według rodzin zasobów. Token niesie stały zestaw zakresów; każda operacja najwyższego poziomu sprawdza jeden z nich.

Zakres	Uprawnia do
tickets:read	Odczytu zgłoszeń, wiadomości, wersji roboczych, historii, załączników, raportów
tickets:write	Tworzenia / aktualizacji / usuwania zgłoszeń, publikowania wiadomości, przesyłania załączników. Obejmuje tickets:read
chat:read	Odczytu czatów, rozmów, wiadomości, sesji
chat:write	Wysyłania wiadomości agenta, dołączania / opuszczania / zamykania / ponownego otwierania rozmów. Obejmuje chat:read
customers:read	Odczytu rekordów klientów
customers:write	Tworzenia / aktualizacji / scalania rekordów klientów. Obejmuje customers:read
settings:read	Odczytu ustawień konta (działy, statusy, priorytety, skrzynki pocztowe — bez sekretów)

Pola z poświadczeniami skrzynek pocztowych (nazwy użytkowników, hasła i hosty IMAP/SMTP) nigdy nie są zwracane tokenowi, niezależnie od zakresu — te sekrety należą do Twojego dostawcy poczty i pozostają poza zasięgiem publicznego API.

Klasyfikacja błędów

Odpowiedzi GraphQL używają errors[].extensions.code:

Kod	Znaczenie	HTTP
SCOPE_DENIED	Tokenowi brakuje wymaganego zakresu. extensions.valid_values wymienia zakresy, które spełniłyby wymagania operacji	200
RATE_LIMITED	Budżet żądań dla tokena został wyczerpany. extensions.retryAfter to liczba sekund do zresetowania, a nagłówek Retry-After zawiera tę samą liczbę	429
INVALID_API_TOKEN	Token nie został znaleziony, jest zniekształcony lub w inny sposób nieużyteczny	200

Tokeny unieważnione, wygasłe, niezgodność kont oraz odmowy wynikające z listy dozwolonych adresów IP są odrzucane, zanim zapytanie zostanie wykonane, i zwracane jako HTTP 401 bez treści GraphQL. Traktuj kod 401 przy żądaniu z tokenem jako „ten token nie jest już ważny dla tego żądania — sprawdź jego termin ważności, zakresy i listę dozwolonych adresów IP".

Limity zapytań

Każde żądanie z tokenem niesie nagłówki:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 96
X-RateLimit-Reset: 1715692800

Domyślny budżet to 120 żądań na minutę na token. Każde żądanie kosztuje 1, niezależnie od tego, czy odczytuje, czy zapisuje. Przekroczenie zwraca HTTP 429 z nagłówkiem Retry-After i extensions.code = "RATE_LIMITED"; dobrze zachowujący się klient czeka do momentu zresetowania.

Lista dozwolonych adresów IP

Każdy samodzielnie utworzony token musi zawierać co najmniej jeden adres IP lub CIDR — tokeny „z dowolnego IP" nie istnieją. Źródłowy adres IP każdego żądania jest porównywany z listą tokena; brak dopasowania jest odrzucany z kodem HTTP 401 i extensions.sub_code = "ip_not_allowed".

• Akceptowane są IPv4, IPv6 oraz zakresy CIDR. Dla pojedynczego hosta użyj /32 (IPv4) lub /128 (IPv6).
• Zakresy są walidowane i normalizowane przy zapisie.
• Listę dozwolonych adresów można edytować po utworzeniu — edycja nie zmienia sekretu.

Używaj tokena ze stabilnego punktu wyjścia: runnera CI, zaplanowanego zadania, stałego biurowego NAT-u lub własnych serwerów w znanym zakresie adresów IP. Wyciekły token jest bezużyteczny z dowolnego miejsca spoza swojej listy dozwolonych adresów.

Aktywność tokena

Każde uwierzytelnione żądanie wykonane przez token jest rejestrowane: czas, nazwa operacji, źródłowy adres IP, wynik (sukces, błąd, przekroczenie limitu, odmowa zakresu, unieważnienie lub wygaśnięcie) oraz czas odpowiedzi. To ten ślad warto sprawdzić, jeśli token zachowuje się nieoczekiwanie.

Wersjonowanie i wycofania

API jest wersjonowane wersjami datowanymi YYYY-MM. Przypnij jedną w adresie URL, a pozostanie stabilna przez co najmniej 12 miesięcy; wycofania są ogłaszane w samych odpowiedziach, zanim zniknie cokolwiek, czego używasz. Pełną politykę znajdziesz w sekcji Wersjonowanie API.

Poznawanie schematu

Schemat sam się opisuje: użyj standardowej introspekcji GraphQL na wersjonowanym punkcie końcowym, aby wygenerować typy i poznać powierzchnię API. Interaktywny GraphQL Playground jest dostępny pod adresem …/backend/<subdomain>/playground.

Szybki start z curl

Przykłady zakładają host helpdesk.example.com, subdomenę acme, wersję 2026-07 i token w zmiennej $TOKEN.

Odczyt bieżącego użytkownika (dowolny zakres)

curl -sS https://helpdesk.example.com/backend/acme/api/2026-07/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ currentUser { id email firstname lastname } }"}'

Lista ostatnich zgłoszeń (tickets:read)

curl -sS https://helpdesk.example.com/backend/acme/api/2026-07/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query ($first: Int!) {
      ticketList(first: $first) {
        edges { node { code subject status { name } updatedAt } }
      }
    }",
    "variables": { "first": 10 }
  }'

Publikacja publicznej odpowiedzi (tickets:write)

curl -sS https://helpdesk.example.com/backend/acme/api/2026-07/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation ($input: SaveTicketInput!) {
      saveTicket(input: $input) {
        ticket { code }
        error { code message }
      }
    }",
    "variables": {
      "input": {
        "id": "TICKET-UUID-HERE",
        "message": "Thanks — fixing this now.",
        "messageType": "PUBLIC"
      }
    }
  }'

Do codziennej pracy CLI hdmx opakowuje całą tę powierzchnię w wygodne polecenia.