Skava Skava / Wiki

Łączenie elementów niestandardowych dla deweloperów

Ta strona jest przeznaczona dla deweloperów łączących backend firmy ze Skava. Tworzenie i publikowanie elementu API opisano na stronie Elementy niestandardowe: interfejsy API; tutaj omawiamy wszystko, co musi się wydarzyć po drugiej stronie linii.

Idea w jednym zdaniu: Skava nie zna Twojej dziedziny. Zna dokładnie jeden format, czyli kartę. Ty decydujesz, co ona mówi, my sprawdzamy tylko kształt, rozmiar i bezpieczeństwo. Zamówienie materiałów to jeden przykład; następna firma zbiera opinie użytkowników, a kolejna archiwizuje zdjęcia z budowy we własnych rejestrach.

Przebieg w skrócie

  1. Administrator firmy tworzy element API w Skava: formularz oraz adres, metodę i token Twojego backendu.
  2. Ktoś w czacie wypełnia formularz i go wysyła.
  3. Skava wywołuje Twoje backend i wysyła wypełnione wartości jako JSON.
  4. Twoja odpowiedź staje się kartą w czacie.
  5. Opcjonalnie raportujesz później nowe stany przez callback. Każdy raport staje się kolejną kartą; poprzednia pozostaje.

Wymagania dla Twojego backendu

  • HTTPS. Tylko https://, bez http, bez danych uwierzytelniających w adresie, maksymalnie 2000 znaków.
  • Dostęp publiczny. Host musi rozwiązywać się wyłącznie do publicznych adresów IP. Adresy localhost, sieci prywatnych, link-local oraz metadanych chmury są odrzucane, a ta weryfikacja odbywa się przy każdym wywołaniu.
  • Stały adres. Skava rozwiązuje host tylko raz i przypina połączenie do tego adresu IP. Zmiana DNS w trakcie wywołania nie ma wpływu.
  • Brak przekierowań. Przekierowanie 301 do „poprawnego” adresu jest traktowane jako błąd. Wprowadź od razu adres docelowy.
  • Czas odpowiedzi. Limit czasu jest konfigurowalny dla każdego elementu i twardo ograniczony do 30 sekund. Jeśli potrzebujesz więcej czasu, odpowiedz natychmiast i zgłoś wynik później przez wywołanie zwrotne.
  • Rozmiar odpowiedzi. Skava odczytuje maksymalnie 256 KiB.
  • Content-Type. Treść jest analizowana wyłącznie w formacie application/json.

Żądanie, które do Ciebie trafia

Metoda to GET, POST, PUT lub PATCH, w zależności od elementu. W przypadku POST, PUT i PATCH wartości są przesyłane w ciele JSON, a w przypadku GET jako parametry zapytania.

Uwierzytelnianie to jedna nagłówek, którego nazwa i prefiks wartości są skonfigurowane w elemencie, zwykle Authorization z prefiksem Bearer . Token jest przechowywany zaszyfrowano po naszej stronie. Nagłówków host, content-length, content-type, cookie i accept-encoding nie można ustawić.

Ciało jest płaskim obiektem. Klucze wybiera osoba, która zbudowała element; zagnieżdżenie pojawia się tylko tam, gdzie dodano tabelę lub selektor produktu:

{"artikelnummer": "5100110", "menge": 20, "note": "Please deliver in the morning", "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "project": "Spitalstrasse 11", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/…", "callback_token": "…"}

Trzy klucze zawsze pochodzą od nas, więc nie używaj ich samodzielnie:

  • locale: kod języka użytkownika. Odpowiadaj w tym języku; nie tłumaczymy Twoich tekstów.
  • callback_url i callback_token: wywołanie zwrotne dla tej jednej interakcji, patrz niżej. Są obecne tylko wtedy, gdy wywołanie pochodzi z czatu.

Pola kontekstowe, takie jak nazwa, firma, projekt lub podrozmowa, są wypełniane przez sam serwer na podstawie kanału, w którym uruchomiono element. Zmanipulowany klient nie może tam podać innej nazwy projektu.

Odpowiedź: format karty

Odpowiedz kodem 2xx i obiektem card. To dokładnie to, co staje się kartą w czacie:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

  • v (wymagane): liczba całkowita 1. Jako tekst ("1") jest odrzucana. Bez niej odpowiedź nie jest traktowana jako karta i stosowane jest mapowanie odpowiedzi skonfigurowane w elemencie.
  • title: nagłówek karty.
  • state: tylko kolor i ton ikony, jedna z wartości: ok, pending, warn, error. Nieznana wartość powoduje powrót do ok i wyświetlenie podpowiedzi.
  • status_text: swobodny tekst, którego nie interpretujemy. Znajduje się u góry karty i jest wyświetlany w liście czatów oraz w powiadomieniach push.
  • fields: lista elementów label i value. Maksymalnie 20 wpisów, label do 80 znaków, value do 200, title i status_text po 120 znaków. Zbyt długie wartości są skracane, a nie odrzucane: zamówienie nie powinno się nieudawać z powodu drobnego szczegółu.
  • icon: patrz niżej.

Co Skava robi z Twoimi tekstami, zanim trafią do czatu: usuwa znaki nowej linii i znaki sterujące (znak zapisu od prawej do lewej mógłby odwrócić wyświetlanie kwoty), zastępuje backticki oraz neutralizuje wszystko, co zaczyna się od [SKAVA:. Ostatnia zasada zapobiega odczytaniu wartości karty jako innego elementu czatu, na przykład prośby o płatność.

Linki w polach, HTML i obrazy nie mogą być ustawiane. Czat to zaufane środowisko, a klikalny adres z obcego backendu byłby zaproszeniem do przebudowy strony logowania.

Wejścia użytkownika należą do serwera: pojawiają się na pierwszej karcie i nie można ich nadpisać. W czacie stanowią zapis tego, co faktycznie zostało przesłane.

Ikony

Dzięki icon karta otrzymuje własny znak w nagłówku. Dwa sposoby:

Nazwa z zestawu wbudowanego: package, package-check, package-open, box, boxes, truck, forklift, warehouse, settings, cog, gauge, wrench, hammer, drill, hard-hat, ruler, paint-roller, construction, clipboard-check, receipt, file-text, camera, clock, calendar-clock, circle-check, circle-alert, triangle-alert, send, mail-check, shopping-cart, credit-card, map-pin.

Lub własny SVG jako ciąg znaków. Skava pobiera z niego wyłącznie geometrię (path, circle, ellipse, rect, line, polyline, polygon wraz z ich atrybutami liczbowymi) i tworzy własny obraz. Skrypty, style, odwołania zewnętrzne, foreignObject oraz atrybuty zdarzeń są odrzucane; deklaracja typu dokumentu lub encja powodują odrzucenie; plik może mieć maksymalnie 8 KiB i zawierać co najwyżej 16 kształtów. Kolor, grubość linii i rozmiar ustawia Skava, więc ikona nie może udawać elementu sterującego. Pracuj na siatce 24 na 24.

Bez icon pozostaje domyślny znak.

Callback: raportowanie późniejszych stanów

Wywołanie zawiera callback_url i callback_token. Użyj ich, aby później raportować nowe stany:

POST <callback_url> z Authorization: Bearer <callback_token> i Content-Type: application/json, treść maksymalnie 32 KiB:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}, "seq": 3, "final": false}

Oprócz karty istnieją trzy opcjonalne wartości:

  • seq: własny licznik. Raport o mniejszej lub równej wartości jest odrzucany, aby dwa raporty nie mogły się wyprzedzić. Bez seq wygrywa ten, który dotarł ostatni.
  • final: zamyka interakcję. Token staje się nieważny i nie pojawiają się kolejne karty. Dozwolone również w pierwszej odpowiedzi, dla procesów bez dalszych kroków.
  • notify: ustaw na false, aby opublikować kartę cicho, bez licznika nieprzeczytanych i bez powiadomienia. Dla kroków pośrednich, które nie powinny nikogo budzić. Bez tego ustawienia karta jest zwykłą wiadomością.

Każdy raport staje się własną kartą w czacie, poprzednia pozostaje. Dzięki temu widać, jaki stan został zgłoszony. Stąd rekomendacja: wysyłaj tylko to, co się zmieniło. Karta powtarzająca numer zamówienia, pozycje i sumę po raz czwarty to tylko szum dla czytelnika.

Dwa limity: ten sam raport wysłany dwukrotnie nie generuje drugiej karty, a interakcja może opublikować maksymalnie 50 kart. Interakcja przyjmuje raporty przez 90 dni.

Odpowiedzi, na które należy zareagować

  • 200 z {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Przeczytaj wskazówki: mówią one, co zostało skrócone lub usunięte.
  • 401: zły token lub identyfikator interakcji. Nie ponawiaj próby.
  • 410: interakcja zamknięta lub wygasła. Nie ponawiaj próby.
  • 422: karta nie do użycia, z wskazówkami jako powodem. Najpierw ją napraw.
  • 400 błędny JSON, 413 za duży rozmiar, 429 za dużo żądań (ponów z opóźnieniem), 500 błąd po naszej stronie, spróbuj później.

Przykład 1: zamówienie z historią statusów

Krok 1, żądanie do Twojego backendu:

POST https://api.example.com/v1/orders
Authorization: Bearer <your token>
{"artikelnummer": "5100110", "menge": 20, "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/1111…", "callback_token": "secret"}

Krok 2, Twoja natychmiastowa odpowiedź:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

Czat wyświetla teraz kartę z ikoną paczki, statusem i danymi wprowadzonymi przez użytkownika.

Krok 3, później podczas wyboru:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Being picked", "icon": "cog", "fields": []}, "seq": 2, "notify": false}

Cicha druga karta bez pól: zmienił się tylko status.

Krok 4, przy wysyłce:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}, {"label": "Carrier", "value": "DPD"}]}, "seq": 3}

Ta karta może obudzić kogoś, stąd brak notify: false.

Krok 5, przy dostawie:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "ok", "status_text": "Delivered", "icon": "package-check", "fields": []}, "seq": 4, "final": true}

Dzięki final interakcja zostaje zamknięta, a token przestaje działać.

Przykład 2: akcja bez dalszych kroków

Nie każdy przepływ ma historię. Element z jednym polem, który przekazuje dane do Twojego systemu, wymaga tylko jednej odpowiedzi:

{"card": {"v": 1, "title": "Filed", "state": "ok", "status_text": "Stored under project 4711", "icon": "clipboard-check", "fields": [{"label": "Case", "value": "4711"}]}, "final": true}

Tutaj kluczowe jest final: true: inaczej interakcja pozostałaby otwarta przez 90 dni z ważnym tokenem, mimo że nigdy więcej nic nie zgłosisz.

Wybór produktu z katalogu

Po tym, jak firma wgrała swój katalog artykułów, element może zawierać blok wybieracza produktów. Użytkownik tworzy z niego koszyk, a Ty otrzymujesz go jako listę pod kluczem wybranym przez osobę, która zbudowała element:

{"items": [{"artikelnummer": "5100110", "menge": 20}, {"artikelnummer": "5100111", "menge": 2}], "note": "…"}

Ponieważ klucz jest dowolny, szukaj pierwszej listy o tym kształcie, a nie konkretnej nazwy. Przed wysłaniem Skava sprawdza, czy każda liczba naprawdę istnieje w katalogu tej firmy, maksymalnie 50 pozycji. W karcie pozycje pojawiają się jako lista z obrazkiem produktu, nazwą i ilością.

Testowanie

  • Ping w edytorze elementów wysyła czyste HEAD bez tokena i bez danych. Odpowiedz czymkolwiek; każda odpowiedź HTTP liczy się jako osiągalność.
  • Żądanie testowe wykonuje rzeczywiste wywołanie z przykładowymi wartościami, nawet gdy element jest nadal w wersji roboczej, i wyświetla żądanie, odpowiedź oraz komunikaty walidatora karty.
  • Podgląd na sąsiedniej karcie: wklej odpowiedź JSON, sprawdź i zobacz gotową kartę wraz z podpowiedziami. Odpowiedź jest weryfikowana na serwerze tym samym kodem, który działa w produkcji.
  • Przykładowy serwer: kompletny przykładowy dostawca działa na api.skava.io i wykorzystuje wszystko opisane powyżej. Jego kod źródłowy znajduje się w repozytorium w katalogu example_order_server/, ma około 600 linii czystego kodu standardowej biblioteki i jest przeznaczony do skopiowania.

Co jeszcze warto wiedzieć

  • Karta to zwykła wiadomość czatu. Pojawia się w wynikach wyszukiwania, można ją cytować i pozostaje w historii.
  • Wysyłana jest przez nadawcę systemowego, nie przez konto Twojej firmy. Pojawia się po stronie osoby, która uruchomiła element, a w tytule wskazane jest, który system ją tworzy.
  • Osoby uprawnione do uruchomienia są określone na elemencie: wyłącznie członkowie firmy lub również osoby zewnętrzne, które mają dostęp do czatu. Gdy Twoja firma opuszcza czat, uprawnienie wygasa automatycznie.
  • Element API z wygasłym tokenem jest nieaktywny: bieżące aplikacje ukrywają go w menu, a wywołanie wysłane mimo to jest odrzucane po stronie serwera. Administrator zapisuje dla niego nowy token, co działa również na opublikowanym interfejsie.

Powiązane

Tworzenie i publikowanie: Elementy niestandardowe: interfejsy API. Dokumenty do wypełnienia zamiast interfejsów: Elementy niestandardowe: dokumenty.