Support Widget

Widget komunikuje się z serwerem przez publiczne endpointy JSON. Nie wymagają autoryzacji Bearer — identyfikacja odbywa się przez token desku.

Endpointy widgetu

| Metoda | Ścieżka | Opis |
|——–|———|——|
| GET | /helpdesk/widget/data.json?token=DESK_TOKEN | Dane desku (nazwa, kolor, kategorie) |
| POST | /helpdesk/widget/create_ticket.json?token=DESK_TOKEN | Utworzenie zgłoszenia |
| GET | /helpdesk/widget/show_ticket.json?token=DESK_TOKEN&ticket_token=TT | Szczegóły zgłoszenia z komentarzami |
| GET | /helpdesk/widget/client_tickets.json?token=DESK_TOKEN | Lista zgłoszeń klienta |
| POST | /helpdesk/widget/add_comment.json?token=DESK_TOKEN&ticket_token=TT | Dodanie komentarza |

Publiczny widok zgłoszenia

| Metoda | Ścieżka | Opis |
|——–|———|——|
| GET | /helpdesk/ticket/:token | Widok HTML zgłoszenia |
| POST | /helpdesk/ticket/:token/comments | Dodanie komentarza (formularz HTML) |

GET /helpdesk/widget/data

Zwraca konfigurację desku:

{
  "name": "Support",
  "description": "Pomoc techniczna",
  "color": "#3b82f6",
  "active": true,
  "locale": "pl",
  "help_content": "Opisz swój problem...",
  "attachments_enabled": true,
  "categories": [
    { "id": 1, "name": "Błąd", "color": "red", "help_content": "..." }
  ]
}

POST /helpdesk/widget/create_ticket

| Pole | Typ | Opis |
|——|—–|——|
| title | string | Tytuł zgłoszenia (wymagane) |
| content | text | Treść |
| priority | string | low, normal, high, urgent |
| category_id | integer | ID kategorii |
| client_email | string | E-mail klienta |
| client_name | string | Imię klienta |
| client_external_id | string | Zewnętrzne ID klienta |
| client_url | string | URL klienta |
| client_plan | string | Plan klienta |
| user_external_id | string | ID użytkownika końcowego |
| user_email | string | E-mail użytkownika |
| user_name | string | Imię użytkownika |
| user_phone | string | Telefon użytkownika |
| attachment_signed_ids | array | ID załączników (DirectUpload) |
| signature | string | Podpis HMAC (jeśli wymagany) |

GET /helpdesk/widget/client_tickets

Wymaga client_external_id lub email + signature (jeśli desk wymaga).

Odpowiedź:

[
  {
    "id": 123,
    "token": "xyz",
    "number": "#T-001",
    "title": "Problem",
    "status": "open",
    "priority": "normal",
    "read": true,
    "waiting_for_client": false,
    "created_at": "2026-03-05T09:00:00Z",
    "updated_at": "2026-03-05T09:15:00Z"
  }
]

Podpis HMAC-SHA256

Gdy desk ma security_level: "signature", żądania muszą zawierać podpis.

Algorytm:

1. Zbierz parametry tożsamości: client_email, client_external_id, client_name, client_plan, client_url, user_email, user_external_id, user_name, user_phone
2. Usuń puste wartości
3. Posortuj alfabetycznie po kluczu
4. Połącz jako key1=value1&key2=value2
5. Oblicz HMAC-SHA256 z secret_key desku

data = params.compact_blank.sort_by { \|k, _\| k.to_s }.map { \|k, v\| "#{k}=#{v}" }.join("&")
signature = OpenSSL::HMAC.hexdigest("sha256", desk.secret_key, data)

Kod osadzenia

<div id="intum-helpdesk-widget"></div>
<script>
  var IntumHelpdeskWidget = {
    account_url: "https://konto.intum.pl",
    desk_token: "TOKEN_DESKU",
    client_external_id: "CRM-123",
    client_email: "jan@firma.pl",
    client_name: "Jan Kowalski",
    locale: "pl",
    signature: "HMAC_SIGNATURE"
  };
</script>
<script src="WIDGET_URL"></script>