Własne elementy: interfejs API

Interfejs API to formularz, którego wypełnione wartości Skava wysyła jako JSON na wskazany przez Ciebie adres (Twój backend). Dzięki temu możesz bezpiecznie połączyć Skava z własnymi systemami.

Konfiguracja interfejsu API

Interfejs składa się z pól wejściowych (tworzą one JSON), adresu docelowego oraz uwierzytelniania.

1. Tworzenie pól: Każde pole otrzymuje klucz JSON. Po prawej stronie widzisz na żywo podgląd JSON, który zostanie wysłany do Twojego backendu dokładnie w tej formie.
2. Adres (URL): adres https:// Twojego backendu. Dozwolone są wyłącznie adresy HTTPS i publicznie dostępne (zobacz Bezpieczeństwo poniżej).
3. Metoda: POST (domyślnie), PUT, PATCH lub GET. Przy użyciu GET wartości są dołączane jako parametry zapytania zamiast wysyłania w ciele żądania.
4. Uwierzytelnianie: Ustaw nazwę nagłówka (np. Authorization) oraz prefiks wartości (np. Bearer ), a następnie zapisz token. Opcjonalnie ustaw datę wygaśnięcia.
5. Pola odpowiedzi (opcjonalnie): Zdefiniuj ścieżkę, aby określić, które wartości z odpowiedzi backendu mają być wyświetlane: np. order.id lub items[0].sku.
6. Sprawdź za pomocą Ping i Test Request, a następnie Release.

Przechowuj token bezpiecznie

Token jest przechowywany zaszyfrowany i nigdy nie jest zwracany do klientów: aplikacja pokazuje jedynie czy token jest ustawiony oraz kiedy wygasa. Podczas wysyłania aplikacja Skava dodaje go po stronie serwera do skonfigurowanego nagłówka. Jeśli ustawisz datę wygaśnięcia, Skava odrzuci połączenie po jej upływie i poprosi o odnowienie tokena.

Testowanie: ping i żądanie testowe

• Ping : szybka weryfikacja dostępności. Sprawdza jedynie czy Twój adres odpowiada, nie wysyłając przy tym tokena ani danych formularza. Wyświetla dostępność, status i czas odpowiedzi. Idealny jako pierwszy krok.
• Testowe żądanie : prawdziwa próba: wysyła przykładowe dane w tym token do Twojego adresu i pokazuje pełną odpowiedź oraz wyodrębnione pola odpowiedzi.

Jako administrator możesz uruchomić oba testy w trybie szkicu, aby zweryfikować integrację przed publikacją.

Szkic i publikacja

Każdy interfejs rozpoczyna się jako szkic i może być dowolnie edytowany. Gdy wszystko jest gotowe, publikujesz go przyciskiem Publikuj.

Bezpieczeństwo

Jak zespół korzysta z opublikowanego interfejsu

Gdy interfejs zostanie opublikowany, wszyscy członkowie firmy mogą go uruchomić bezpośrednio z czatu, bez konieczności używania edytora. Proces jest taki sam jak w przypadku szablonów dokumentów: wybierz, wypełnij, wyślij.

1. W czacie dotknij przycisku Plus na dole i wybierz Element niestandardowy.
2. Wybierz żądany szablon lub interfejs z listy.
3. Wypełnij formularz i naciśnij Wyślij.
4. Wynik pojawia się jako karta w czacie: widoczna dla wszystkich uczestników rozmowy.

Pozwól AI na stworzenie elementu

Jako administrator firmy nie musisz korzystać z edytora samodzielnie. Powiedz asystentowi Skava w czacie, na przykład „stwórz mi formularz zamówienia dla mojego katalogu z ilością i adresem dostawy". Na tej podstawie tworzy wersję roboczą, którą później można zmieniać pole po polu. Asystent zna Twój przesłany katalog artykułów: w przypadku zamówień sugeruje on wybór produktu zamiast pola tekstowego dla numeru artykułu.

Co może również ustawić: punkt końcowy i metodę oraz grupę docelową („tylko członkowie firmy" lub „również osoby z zewnątrz w tym samym czacie"). W przypadku grupy docelowej najpierw pyta, zamiast od razu ustawiać, ponieważ to decyduje, kto może uruchomić coś z zewnątrz.

Czego nie dotyka w sposób jawny: tokena dostępu. Nigdy o niego nie pyta i nigdy go nie akceptuje, ponieważ wiadomości czatu są przechowywane. Wpisujesz go samodzielnie w edytorze, w przeciwnym razie żaden wywołanie nie zostanie wysłane. Nie może również opublikować: ostatni krok pozostaje w Twoich rękach, więc nic nie staje się widoczne dla klientów bez Twojej weryfikacji.

Kto może to uruchomić

Karta „Punkt końcowy" określa, kto może korzystać z elementu. Domyślnie są to członkowie Twojej firmy. Drugie ustawienie otwiera dostęp dla osób z zewnątrz, ale tylko w czacie, w którym obecny jest również ktoś z Twojej firmy: dokładnie ten przypadek, do którego jest to przeznaczone, czyli klient składający zamówienie u Ciebie. Gdy Twoja firma opuszcza czat, uprawnienia wygasają automatycznie.

Produkty z własnego katalogu

Po załadowaniu katalogu artykułów kreator oferuje blok wybierania produktów. Nie ma opcji do zarządzania: lista to Twój katalog. Osoba składająca zamówienie wyszukuje w niej, widzi obrazek, nazwę i numer artykułu, a Twój backend otrzymuje numer artykułu. Skava odrzuca numer, którego nie ma w katalogu. Obok pola z ilością umieść zwykłe pole liczbowe.

Zdefiniuj kartę samodzielnie

Twój backend decyduje o treści karty. Skava sprawdza tylko kształt, rozmiar i bezpieczeństwo, nigdy znaczenie: nie zna stanów zamówień ani nazw pól. Aby to zrobić, odpowiedz obiektem card:

{"card": {"v": 1, "title": "Order 10001", "state": "pending", "status_text": "Being picked", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}}

• v musi być liczbą całkowitą 1. Bez tego odpowiedź nie jest traktowana jako karta i zastosowane zostanie mapowanie odpowiedzi skonfigurowane w elemencie.
• state to tylko kolor i ikona: ok, pending, warn lub error. Wszystko, co niesie znaczenie, należy umieścić w status_text jako dowolny tekst.
• fields to lista etykiet i wartości, maksymalnie 20 wpisów. Zbyt długie wartości są skracane, a nie odrzucane, dzięki czemu zamówienie nigdy nie zawiedzie z powodu szczegółu.

Wprowadzone przez użytkownika dane należą do serwera: pozostają nienaruszone niezależnie od tego, co wysyła Twój backend. Stanowią one zapis w czacie tego, co faktycznie zostało przesłane.

Raportowanie statusu później

Gdy element działa, Skava wysyła dwie dodatkowe wartości: callback_url i callback_token. Później zgłoś tam nowy stan, a w czacie, również na telefonie, pojawi się nowa karta, nawet gdy ktoś na nią patrzy. Poprzednia pozostanie, więc będzie czytelne, który stan został zgłoszony. Wyślij ten sam obiekt card jak powyżej, metodą POST z nagłówkiem Authorization: Bearer <callback_token>. Obok karty znajdują się trzy opcjonalne wartości:

• seq: Twój własny licznik. Raport o mniejszej lub równej wartości jest odrzucany, dzięki czemu dwa raporty nie mogą się wyprzedzić.
• final: Zamyka interakcję. Token traci ważność, a karta staje się ostateczna.
• notify: Ustaw na false, aby opublikować kartę cicho, bez licznika nieprzeczytanych i bez powiadomienia. Przeznaczone dla kroków pośrednich, które nie powinny budzić nikogo. Bez tego ustawienia karta jest zwykłą wiadomością.

Interakcja może opublikować maksymalnie 50 kart. Ten sam raport wysłany dwukrotnie nie generuje drugiej karty.

Skava odpowiada kodem 200 i listą hints, jeśli cokolwiek zostało skrócone lub odrzucone, oraz kodem 422, jeśli karta była nie do użycia. Interakcja akceptuje raporty przez 90 dni.

Karty są publikowane przez nadawcę systemowego Skavy, a nie przez osobę, która uruchomiła element, ani przez konto Twojej firmy. W tytule karty podano, który system jest autorem.

Pełny przykład do skopiowania znajduje się w repozytorium w folderze example_order_server/ i działa na adresie api.skava.io.

Powiązane

Czy zamiast tego chcesz stworzyć szablon dokumentu do wypełnienia? Zobacz Custom Elements: Dokumenty.

Często zadawane pytania