REST API Xcellerate OPS z osobistymi kluczami API

Xcellerate OPS ma udokumentowane REST API (v1). Dzięki niemu połączysz własne narzędzia, skrypty lub platformy automatyzacji ze zgłoszeniami, firmami, kontaktami, szansami sprzedaży, projektami, wpisami czasu, zasobami i nie tylko. Każdy użytkownik tworzy własne klucze API w swoim profilu, a klucz może dokładnie to, co ten użytkownik w aplikacji, nic więcej. Ten poradnik jest dla administratorów technicznych w MSP i firmach usługowych.

TL;DR

• Utwórz klucz w profilu w sekcji API keys i od razu skopiuj token: jest pokazywany tylko raz.
• Przy każdym żądaniu wysyłaj dwa nagłówki: Authorization: Bearer <token> i X-Tenant-Id.
• Klucz dziedziczy uprawnienia Twojego użytkownika. Domyślny limit to 120 żądań na minutę na klucz.

Zanim zaczniesz

• Każdy pracownik może tworzyć klucze dla siebie. Rola administratora nie jest potrzebna.
• Uprawnienia klucza odpowiadają jeden do jednego uprawnieniom Twojego zespołu. Co jest zablokowane w aplikacji, jest zablokowane też w API.
• Potrzebujesz klienta HTTP, który potrafi wysyłać nagłówki: skryptu, platformy automatyzacji lub własnej aplikacji.
• Jeden użytkownik może mieć do 20 aktywnych kluczy.

Uwaga: sekcja kluczy API jest w aplikacji dostępna tylko po angielsku, dlatego poniższe etykiety są po angielsku.

Tworzenie i używanie klucza API

Krok 1: Otwórz klucze API

Przejdź do swojego profilu i otwórz sekcję API keys (Klucze API).

Krok 2: Utwórz klucz

Nadaj kluczowi nazwę, która mówi, do czego służy. Wybierz, czy może tylko czytać, czy także zapisywać, i opcjonalnie ustaw datę wygaśnięcia w przyszłości. Klucze są tylko do odczytu, chyba że utworzysz je z prawem zapisu. Jeśli potrzebujesz tylko odczytu danych, zostań przy odczycie.

Krok 3: Skopiuj token

Po utworzeniu OPS wyświetla komunikat „Copy your new API key now — it will not be shown again.” Od razu skopiuj token i przechowuj go w bezpiecznym miejscu. Tokeny zaczynają się od xok_. Jeśli go zgubisz, utwórz nowy klucz.

Krok 4: Skopiuj ID obszaru roboczego

W tej samej sekcji widać ID Twojego obszaru roboczego (tenant id). Skopiuj je przyciskiem Copy (Kopiuj). Jest potrzebne przy każdym żądaniu.

Krok 5: Wyślij pierwsze żądanie

Przetestuj klucz prostym żądaniem do /api/v1/me z oboma nagłówkami:

GET /api/v1/me
Authorization: Bearer <token>
X-Tenant-Id: <workspace id>

Link API documentation ↗ (dokumentacja API) w sekcji otwiera interaktywną dokumentację. Sprawdź tam właściwy adres bazowy i dostępne endpointy.

Krok 6: Unieważniaj nieużywane klucze

Klucz unieważniasz z tej samej listy. Przy każdym kluczu widać, kiedy był ostatnio używany, więc łatwo znaleźć klucze, których nikt już nie potrzebuje.

Co dzieje się po połączeniu

• Format: JSON w żądaniach i odpowiedziach. Listy są stronicowane kursorem.
• Zakres: m.in. firmy, kontakty, interakcje CRM, pola niestandardowe, zgłoszenia i harmonogramy zgłoszeń, projekty z planowaniem i finansami, wpisy czasu, wydatki, nieobecności, czas pracy, zasoby i CMDB, oprogramowanie, usługi, zmiany, problemy, poważne incydenty, wydania, baza wiedzy, szanse sprzedaży, cenniki, faktury cykliczne, raporty, raporty SLA i XLA, połączenia i nagrania oraz dziennik działań AI. Pełna lista jest w dokumentacji API.
• Portal klienta: klienci korzystający z Twojego portalu klienta mogą tworzyć tam własne klucze. Takie klucze widzą tylko dane danego klienta.

Jak OPS chroni dostęp, przeczytasz w sekcji bezpieczeństwo i kontrola dostępu. Wszystkie połączenia opisuje strona integracje UE i bezpieczeństwo.

Dobrze wiedzieć

• Limit: domyślnie 120 żądań na minutę na klucz. RMM Labs może go podnieść dla obszaru roboczego na prośbę. Każda odpowiedź zawiera nagłówki X-RateLimit-Limit i X-RateLimit-Remaining.
• Nieudane uwierzytelnienia: powtarzające się nieudane próby z tego samego adresu są tymczasowo blokowane.
• Klucze należą do osoby. Wyłączenie użytkownika unieważnia jego klucze i blokuje dostęp. Integracje działające na tych kluczach przestają działać. Pamiętaj o tym, gdy pracownik odchodzi.
• Ustawienia osobiste, np. preferencje synchronizacji kalendarza, nie są dostępne przez API.

Rozwiązywanie problemów

• 401 unauthenticated „Invalid API credentials.” Token jest błędny, wygasły lub unieważniony, brakuje X-Tenant-Id lub jest błędny, obszar roboczy jest zawieszony albo użytkownik wyłączony. Wszystkie te przypadki celowo dają tę samą odpowiedź.
• 429 rate_limited „Too many requests.” Odczekaj liczbę sekund z nagłówka Retry-After.
• 429 „Too many failed authentication attempts.” Twój adres IP jest tymczasowo zablokowany po wielu nieudanych próbach.
• „You have reached the maximum number of API keys.” Masz 20 aktywnych kluczy. Najpierw unieważnij jeden.

Zacznij

Chcesz połączyć OPS z własnymi skryptami i narzędziami? Zacznij za darmo i utwórz pierwszy klucz API w profilu.