Klucze API Fixh IT zamieniają oprogramowanie Twojego serwisu w otwartą platformę: w sekcji Firma > Klucze API Twoja firma może generować i unieważniać klucze API REST v1, używane w nagłówku X-API-Key do uwierzytelniania żądań do punktu końcowego /api/v1/company/... To nie jest funkcja dla odizolowanych programistów: to most między Twoim warsztatem naprawczym a resztą Twojego ekosystemu oprogramowania, od strony internetowej po program księgowy, od CRM po bota odpowiadającego klientom. Ze względów bezpieczeństwa pełny klucz jest wyświetlany na ekranie tylko raz, zaraz po utworzeniu: od tego momentu jest widoczny tylko w formie zamaskowanej (key_prefix), dlatego trzeba go od razu skopiować i zapisać w bezpiecznym miejscu.
Dlaczego to ważne dla serwisu naprawczego
Warsztat naprawy smartfonów i komputerów rzadko pracuje z jednym narzędziem: jest główny system zarządzania, może sklep internetowy z częściami zamiennymi, chatbot odpowiadający klientom na WhatsApp lub Telegramie, oprogramowanie księgowe do fakturowania, narzędzie marketingowe do kampanii e-mailowych. Bez prawdziwej integracji wszystkie te informacje pozostają odizolowane w każdym systemie, zmuszając personel do wielokrotnego wprowadzania tych samych danych, z realnym ryzykiem błędów w przepisywaniu i opóźnień w komunikacji z klientem. Klucze API REST v1 rozwiązują dokładnie ten problem: pozwalają systemowi zewnętrznemu automatycznie komunikować się z danymi napraw Twojej firmy w Fixh IT, odczytując status zgłoszenia, tworząc nowe naprawy z formularza online lub aktualizując zgłoszenie, gdy technik oznacza zlecenie jako ukończone. Dla serwisu obsługującego dziesiątki lub setki napraw miesięcznie ta integracja między naprawami smartfonów i komputerów a zewnętrznym oprogramowaniem może stanowić różnicę między płynnym przepływem pracy a takim pełnym podwójnego ręcznego wprowadzania danych.
W praktyce
Każdy wygenerowany klucz API jest przypisany do Twojej firmy (key_type "company") i pozwala systemowi zewnętrznemu uwierzytelnić się w API REST v1 Fixh IT poprzez dołączenie klucza w nagłówku X-API-Key każdego żądania HTTP. Za pomocą tego typu klucza możesz przeglądać listę napraw swojej firmy z filtrami według sklepu, statusu lub tekstu wyszukiwania, odczytać szczegóły pojedynczej naprawy, tworzyć nowe, podając sklep, klienta, technika, urządzenie, stwierdzoną usterkę, przekazane akcesoria i wycenę, lub aktualizować istniejącą naprawę, zmieniając jej status, płatność, wydanie lub notatki wewnętrzne. Każde żądanie jest zawsze automatycznie filtrowane według firmy, do której należy klucz: system zewnętrzny nigdy nie może zobaczyć ani zmodyfikować danych innej firmy w sieci, nawet przez pomyłkę, ponieważ kontrola odbywa się po stronie serwera przy każdym pojedynczym zapytaniu.
Ze względów bezpieczeństwa pełny klucz (rzeczywisty tajny ciąg znaków) jest wyświetlany na ekranie tylko raz, zaraz po utworzeniu: od tego momentu system przechowuje jedynie skrót klucza i pokazuje na liście wyłącznie jego początkowy prefiks (key_prefix), wystarczający do rozpoznania, ale nie do ponownego użycia. Dlatego kluczowe jest natychmiastowe skopiowanie klucza i wklejenie go do pliku konfiguracyjnego systemu zewnętrznego, który będzie go używał, przed zamknięciem okna: jeśli o tym zapomnisz, jedynym rozwiązaniem jest unieważnienie tego klucza i wygenerowanie nowego. Każdy klucz pokazuje też datę ostatniego użycia, co pomaga ocenić, czy integracja jest nadal aktywna, czy można ją bezpiecznie wyłączyć, bo nie jest już używana. Jeśli klucz zostanie zgubiony, naruszony lub nie jest już potrzebny, możesz go unieważnić w dowolnym momencie z listy: po unieważnieniu natychmiast przestaje działać, data unieważnienia zostaje zapisana, a każdy system, który go używał, natychmiast traci dostęp do API, bez konieczności interwencji gdzie indziej.
Obok kluczy typu firma, w tym samym systemie technicznym istnieje też typ klucza zarezerwowany dla resellerów sieci Fixh IT, używany do automatycznego zarządzania wystawianiem i kontrolą kodów licencyjnych z własnego oprogramowania zarządzającego: oba typy kluczy są całkowicie rozdzielone (różne zabezpieczenia, różne uprawnienia), a klucz firmowy nigdy nie może być użyty do operacji zarezerwowanych dla resellerów, i odwrotnie.
Szybki przewodnik
- Przejdź do Firma > Klucze API.
- Utwórz nowy klucz API, nadając mu opisową nazwę jednoznacznie identyfikującą integrację (np. "Sklep internetowy z częściami" lub "Bot wsparcia WhatsApp").
- Od razu skopiuj pełny klucz wyświetlony na ekranie: później nie będzie już widoczny w całości, tylko w formie zamaskowanej.
- Wklej klucz do pliku konfiguracyjnego systemu zewnętrznego, w zmiennej przeznaczonej dla nagłówka X-API-Key.
- Skonfiguruj system zewnętrzny tak, aby wysyłał klucz w nagłówku X-API-Key przy każdym żądaniu do /api/v1/company/repairs i innych dostępnych punktów końcowych.
- Przetestuj integrację przykładowym wywołaniem, na przykład odczytem listy napraw, aby sprawdzić, czy odpowiedź zawiera oczekiwane dane.
- Regularnie sprawdzaj datę ostatniego użycia każdego klucza, aby wykryć nieaktywne już integracje.
- W razie potrzeby unieważnij klucz z listy, aby natychmiast przerwać jego użycie, na przykład przy zmianie dostawcy strony internetowej lub rezygnacji z zewnętrznego narzędzia.
Rzeczywiste przypadki użycia
Formularz zgłoszenia naprawy na stronie internetowej. Warsztat naprawy smartfonów integruje na swojej stronie formularz "zgłoś naprawę": gdy klient go wypełni, zewnętrzny skrypt wywołuje punkt końcowy tworzenia naprawy z nagłówkiem X-API-Key, automatycznie generując nowe zgłoszenie w systemie, już przypisane do właściwego sklepu i gotowe do podjęcia przez technika, bez konieczności ręcznego przepisywania danych ze strony do systemu przez kogokolwiek.
Synchronizacja z zewnętrznym systemem księgowym. Firma z wieloma sklepami korzysta z osobnego oprogramowania księgowego do fakturowania: zaplanowana integracja co noc odczytuje, za pomocą klucza API, naprawy oznaczone jako opłacone i wydane w ciągu ostatnich 24 godzin, i importuje je do systemu księgowego w celu rejestracji podatkowej, unikając podwójnego ręcznego wprowadzania danych.
Automatyczne powiadomienia klienta przez bota. Serwis naprawczy łączy bota komunikatora ze swoim systemem: gdy technik zmienia status naprawy z "w trakcie" na "gotowa do odbioru" za pomocą API, zewnętrzny bot okresowo sprawdza niedawno zaktualizowane naprawy i automatycznie wysyła klientowi wiadomość, ograniczając telefony do sklepu z pytaniem o status naprawy.
Wskazówki i dobre praktyki
Twórz osobny klucz API dla każdej integracji, zamiast wielokrotnie używać tego samego klucza wszędzie: dzięki temu, jeśli system zewnętrzny zostanie wycofany lub naruszony, możesz unieważnić tylko ten jeden klucz, bez konieczności ponownej konfiguracji wszystkich innych integracji. Nadawaj każdemu kluczowi opisową nazwę, która od razu przypomina, do czego służy, zwłaszcza jeśli z czasem zgromadzisz ich kilka. Regularnie sprawdzaj datę ostatniego użycia, aby wykryć "zapomniane" klucze powiązane z systemami, których już nie używasz, i unieważniaj je: mniej aktywnych kluczy oznacza mniejszą powierzchnię ataku. Przechowuj pełny klucz w menedżerze haseł lub chronionym pliku konfiguracyjnym, nigdy w udostępnionym dokumencie ani wiadomości na czacie.
Częste błędy, których należy unikać
Nigdy nie udostępniaj tego samego klucza API wielu różnym integracjom: jeśli w przyszłości będziesz musiał wyłączyć jedną z nich, ryzykujesz przerwanie działania także pozostałych. Nie umieszczaj klucza bezpośrednio w publicznym kodzie źródłowym strony lub aplikacji: powinien zawsze znajdować się w osobnym, niewersjonowanym pliku konfiguracyjnym. Nie licz na to, że odzyskasz pełny klucz po zamknięciu okna po raz pierwszy: jeśli zapomnisz go skopiować, jedynym wyjściem jest unieważnienie go i wygenerowanie nowego. Na koniec nie zapominaj o unieważnianiu kluczy wycofanych integracji: aktywny, ale nieużywany klucz pozostaje potencjalnym punktem dostępu do danych Twoich napraw.
Dowiedz się więcej
- Fixh Assistant: chatbot WhatsApp z Fixh AI dla Twojego serwisu
- Witryna Firmowa: sprzedawaj online produkty ze swojego magazynu
- Eksport wszystkich danych firmy: naprawy, dokumenty, klienci i paragony w archiwum ZIP
Najczęściej zadawane pytania
Czy mogę ponownie zobaczyć pełny klucz po jego utworzeniu? Nie, ze względów bezpieczeństwa pełny klucz jest widoczny tylko w momencie utworzenia; jeśli go zgubisz, musisz go unieważnić i wygenerować nowy.
Co się stanie, jeśli unieważnię klucz API? Klucz natychmiast przestaje działać, data unieważnienia zostaje zapisana, a każde żądanie, które go używa, zostaje odrzucone przez system.
Czy mogę utworzyć wiele kluczy API dla tej samej firmy? Tak, możesz wygenerować kilka kluczy, na przykład jeden na każdą integrację lub połączony system zewnętrzny, i unieważniać je pojedynczo bez wpływu na pozostałe.
Jakie dane mogę odczytywać lub zapisywać za pomocą firmowego klucza API? Naprawy Twojej firmy: możesz je przeglądać, filtrować według sklepu lub statusu, tworzyć nowe oraz aktualizować status, płatność, wydanie i notatki wewnętrzne istniejących, zawsze automatycznie ograniczone do Twojej firmy.
Czy klucze API różnią się od tych używanych przez resellerów do licencji? Tak, istnieją dwa całkowicie rozdzielone typy kluczy: firmowe do napraw i reselerskie do zarządzania kodami licencyjnymi, z odrębnymi uprawnieniami i zakresami.
Czy potrzebna jest wiedza techniczna do korzystania z kluczy API? Tak, integracja wymaga, aby system zewnętrzny (strona, bot, oprogramowanie firm trzecich) był zaprogramowany do wysyłania żądań HTTP z nagłówkiem X-API-Key: jest przeznaczona dla programistów lub dostawców oprogramowania współpracujących z Twoim serwisem naprawczym.
