Klucze API

Klucz API to długi, tajny ciąg znaków, który pozwala innemu programowi korzystać z danych w panelu bez logowania się na konto użytkownika. Dzięki niemu system CRM, program księgowy albo strona internetowa sam pobiera aktualne ceny i statusy jednostek albo zapisuje zmiany. Klucz tworzy osoba z uprawnieniami w panelu, a wpisuje go w swoim systemie programista, który przygotowuje integrację.

Klucze API tworzą i zmieniają osoby z rolą Właściciel lub Administrator. Uprawnienie do zarządzania kluczami API można też nadać roli niestandardowej. Role niestandardowe opisuje poradnik Role własne i zakres dostępu. Klucz nie może mieć szerszych uprawnień ani szerszego zakresu niż konto osoby, która go tworzy.

Otwórz klucze API

Ustalenia przed utworzeniem kluczaKopiuj link do sekcji

Przed utworzeniem klucza warto ustalić z programistą trzy rzeczy:

• do jakich danych integracja potrzebuje dostępu: deweloperów, inwestycji, jednostek,
• czy ma dane tylko odczytywać, czy także zmieniać,
• czy dotyczy całej organizacji, jednej firmy deweloperskiej albo jednej inwestycji.

Klucz powinien mieć tylko te uprawnienia, których integracja naprawdę potrzebuje. Każda integracja powinna mieć osobny klucz. Dzięki temu w razie problemu wyłącza się tylko jeden klucz.

Lista kluczyKopiuj link do sekcji

Klucze są w UstawieniaKlucze API, w grupie Integracje. Lista pokazuje przy każdym kluczu nazwę, status, uprawnienia, zakres, ostatnie użycie, ważność i przełącznik Aktywny.

Tworzenie kluczaKopiuj link do sekcji

1. Na liście kluczy kliknij Utwórz klucz API.
2. W polu Nazwa wpisz nazwę, która pozwoli rozpoznać klucz, np. Integracja z ERP.
3. W polu Opis wpisz, do czego służy klucz i kto za niego odpowiada.
4. W polu Zakres wybierz Cała organizacja, Wybrany deweloper albo Wybrana inwestycja. W dwóch ostatnich przypadkach wskaż firmę albo inwestycję.
5. W sekcji Uprawnienia wybierz poziom dostępu dla każdego rodzaju danych (tabela niżej).
6. W polu Okres ważności zostaw 1 rok albo wybierz krótszy okres. Okresu ważności nie można zmienić po utworzeniu klucza.
7. Opcjonalnie w sekcji Dozwolone adresy IP kliknij Dodaj adres i wpisz adresy IP serwerów, z których integracja łączy się z panelem. Adresy poda programista.
8. Kliknij Utwórz klucz.

Rodzaje danych to Deweloperzy, Inwestycje i biura sprzedaży oraz Jednostki i historia cen. Co najmniej jeden musi mieć poziom inny niż Brak dostępu. Gdy zakres jest węższy, część poziomów jest niedostępna, np. klucz dla jednej inwestycji nie doda ani nie usunie inwestycji.

Pusta lista w polu Dozwolone adresy IP oznacza, że klucza można używać z dowolnego adresu. Lista adresów ogranicza skutki wycieku klucza, bo obca osoba nie użyje go ze swojego komputera.

Potwierdzenie i skopiowanie kluczaKopiuj link do sekcji

Po kliknięciu Utwórz klucz otworzy się okno Potwierdzenie tożsamości.

1. W polu Bieżące hasło wpisz hasło do swojego konta. Jeśli konto korzysta z logowania przez Google, kliknij Wyślij kod i wpisz kod z wiadomości e-mail.
2. Kliknij Kontynuuj.
3. W oknie Utworzenie klucza API kliknij Utwórz klucz.
4. W oknie Nowy klucz API kliknij Kopiuj. Klucz trafi do schowka, ale na ekranie pozostanie ukryty.
5. Kliknij Zamknij.

Bezpieczne przekazanie klucza programiścieKopiuj link do sekcji

Klucz działa jak hasło do danych organizacji. Każdy, kto go zna, może korzystać z danych w zakresie uprawnień klucza.

• Przekaż klucz za pomocą firmowego menedżera haseł albo innego kanału przeznaczonego do haseł.
• Nie wysyłaj klucza zwykłym e-mailem, komunikatorem ani SMS-em i nie wklejaj go do dokumentów w bibliotece.
• Nie przekazuj klucza nikomu poza osobą, która konfiguruje integrację.
• Jeśli klucz trafił w niepowołane ręce, od razu go unieważnij albo wygeneruj nowy sekret z opcją Natychmiast.

Strona kluczaKopiuj link do sekcji

Kliknięcie klucza na liście otwiera jego stronę. Nad zakładkami są status klucza i pola Klucz (początek i koniec klucza), Ważność, Ostatnie użycie (z adresem IP) oraz Utworzony przez. Zakładka Ustawienia ma te same pola co formularz tworzenia, z wyjątkiem okresu ważności. Zmiany zapisuje przycisk Zapisz zmiany.

Dziennik żądańKopiuj link do sekcji

Żądanie to pojedyncze zapytanie integracji do panelu. Zakładka Żądania pokazuje wszystkie żądania wysłane z kluczem w ostatnich 30 dniach, z kolumnami Data, Żądanie, Status i Czas. Filtr Wynik z opcjami Udane i Nieudane zawęża listę. Kliknięcie żądania otwiera okno Szczegóły żądania z adresem IP, aplikacją i kodem błędu. Wartość pola ID żądania warto podać w zgłoszeniu do obsługi.

Zmiany wprowadzone przez integrację trafiają też do rejestru zdarzeń. Jako autor zmiany widnieje tam nazwa klucza z dopiskiem Klucz API.

Nowy sekret, wyłączanie i unieważnianieKopiuj link do sekcji

Klucz z okresem ważności przestaje działać w dniu wygaśnięcia i dostaje status Wygasły. Przed tym dniem trzeba wygenerować nowy sekret i przekazać go programiście:

1. Na stronie klucza kliknij Wygeneruj nowy sekret.
2. W polu Poprzedni klucz przestanie działać wybierz Natychmiast, Za 24 godziny albo Za 7 dni.
3. Potwierdź tożsamość hasłem albo kodem z e-maila.
4. Skopiuj nowy klucz w oknie Nowy klucz API i przekaż go programiście.

Nazwa, uprawnienia i pozostałe ustawienia klucza nie zmienią się, a okres ważności zacznie biec od nowa od dnia wygenerowania sekretu. Do wybranego terminu działa jeszcze poprzedni klucz, o czym przypomina komunikat na stronie klucza.

Przełącznik Aktywny na liście albo w sekcji Stan klucza wyłącza klucz bez unieważniania. Wyłączony klucz odrzuca wszystkie żądania, a po włączeniu ponownie działa.

Klucz, z którego integracja już nie korzysta, unieważnia się przyciskiem Unieważnij klucz w sekcji Unieważnienie klucza na stronie klucza.

Co dalejKopiuj link do sekcji

Webhooki

Jak połączyć panel z innym systemem, np. stroną internetową albo CRM, żeby dostawał powiadomienia o zmianach. Tworzenie webhooka, zakres i zdarzenia, sekret, test, dziennik dostaw, wyłączanie i usuwanie.

Rejestr aktywności

Jak sprawdzić, kto, kiedy i co zmienił w panelu. Rejestr zdarzeń organizacji, czyli historia zmian i dziennik audytu z filtrami, szczegółami zmian przed i po oraz zmianami wprowadzonymi przez system i klucze API.

Najczęstsze pytaniaKopiuj link do sekcji