Łączenie systemu rozliczeniowego lub CRM z interfejsem API Partnera Uniqkey

Partnerzy Uniqkey mogą odczytywać miesięczne wykorzystanie licencji dla wszystkich należących do nich organizacji klientów za pośrednictwem interfejsu REST API, dzięki czemu system rozliczeniowy, CRM lub raportowy może pobierać dane bezpośrednio, zamiast wymagać ich eksportowania z Portalu Partnera. W tym artykule wyjaśniono, jak utworzyć klucz API w Portalu Partnera, jak działa interfejs API oraz czego można oczekiwać od danych.

Kto może korzystać

• Interfejs API jest przeznaczony dla partnerów Uniqkey. Klucze API są tworzone w Portalu Partnera przez użytkownika partnera z rolą Administrator. Użytkownicy z innymi rolami nie widzą strony Klucze API.
• Klucz jest przypisany do konta partnera, a nie do użytkownika, który go utworzył. Nadal działa, jeśli użytkownik opuści organizację lub zostanie usunięty.
• Klucz zapewnia dostęp do własnego konta partnera oraz partnerów znajdujących się poniżej niego w hierarchii, dlatego dystrybutor widzi również klientów swoich resellerów. Klucz nigdy nie zapewnia dostępu do partnerów znajdujących się powyżej ani na tym samym poziomie hierarchii.
• System musi mieć możliwość nawiązywania wychodzących połączeń HTTPS z adresem https://partner-api-public.production.uniqkey.eu.
• Interfejs API jest przeznaczony wyłącznie do odczytu i zwraca dane dotyczące licencji oraz nazwy organizacji. Dane sejfów, hasła, klucze ani dane pracowników nigdy nie są uwzględniane.

Krok 1: Utworzenie klucza API

1. Zaloguj się do Portalu Partnera jako administrator.
2. Otwórz pozycję Klucze API w menu.
3. Kliknij Utwórz klucz API.
4. Wprowadź Nazwę integracji, która będzie korzystać z klucza, na przykład Synchronizacja rozliczeń. Nazwa jest wyświetlana w dzienniku audytu przy wszystkich działaniach wykonywanych za pomocą klucza, dlatego powinna być łatwa do rozpoznania.
5. Opcjonalnie wybierz Datę wygaśnięcia. Najwcześniejszą możliwą datą jest dzień jutrzejszy. Klucz działa do końca tego dnia w strefie czasowej przeglądarki. Pozostaw pole puste, aby klucz nie wygasał.
6. Kliknij Utwórz. W oknie dialogowym Skopiuj teraz klucz API zostanie wyświetlony nowy klucz zaczynający się od uk_p_.
7. Skopiuj klucz i zapisz go w magazynie sekretów swojego systemu. Klucz jest wyświetlany tylko raz. Zaznacz opcję Zapisałem(-am) ten klucz API w bezpiecznym miejscu, aby zamknąć okno dialogowe. Później nie będzie można ponownie wyświetlić klucza. Jeśli go utracisz, utwórz nowy klucz.

Późniejsze zarządzanie kluczami:

• Na stronie Klucze API znajduje się lista wszystkich kluczy wraz z ich nazwami, początkowymi znakami klucza (dzięki czemu można je rozróżnić), datą utworzenia, datą wygaśnięcia, datą ostatniego użycia oraz stanem: Aktywny, Wygasł lub Unieważniony.
• Aby unieważnić klucz, otwórz menu w jego wierszu, wybierz Unieważnij i potwierdź. Unieważnienie jest trwałe i nie można go cofnąć. Klucz przestaje działać natychmiast; w rzadkich przypadkach może to potrwać do 1 minuty. Unieważnione klucze pozostają na liście ze stanem Unieważniony.
• Ostatnie użycie jest aktualizowane najwyżej co 5 minut, dlatego przy aktywnie używanym kluczu wyświetlany czas może być opóźniony nawet o 5 minut.
• Daty wygaśnięcia nie można zmienić po utworzeniu klucza. Gdy klucz zbliża się do wygaśnięcia, utwórz nowy.
• Możesz utworzyć kilka kluczy, na przykład po jednym dla każdej integracji, aby móc unieważnić jeden klucz bez wpływu na pozostałe. Wszystkie klucze partnera mają wspólny limit liczby żądań (zobacz „Limity liczby żądań”).
• Aby zmienić klucz: utwórz nowy klucz, zaktualizuj system, sprawdź, czy wartość Ostatnie użycie wskazuje użycie nowego klucza, a następnie unieważnij stary klucz.
• Utworzenie i unieważnienie klucza jest rejestrowane w sekcji Dzienniki audytu w Portalu Partnera wraz z nazwą klucza. Każde pomyślne żądanie danych licencyjnych wykonane za pomocą klucza jest również tam rejestrowane, a nazwa klucza jest wyświetlana jako wykonawca. Wpisy pojawiają się w dzienniku audytu partnera, do którego należy klucz. Odrzucone żądania oraz żądania do punktu końcowego /v1/me nie są rejestrowane.

Krok 2: Konfiguracja systemu

Każda integracja wymaga tych samych elementów:

Dobrym ustawieniem domyślnym jest pobieranie danych raz dziennie. Dane są aktualizowane przez codzienne zadanie (zobacz sekcję „Czego można oczekiwać”), dlatego częstsze odpytywanie nie przynosi korzyści.

Interaktywna dokumentacja interfejsu API jest dostępna pod adresem https://partner-api-public.production.uniqkey.eu/docs. Specyfikacja OpenAPI, której większość narzędzi może użyć do wygenerowania klienta, znajduje się pod adresem https://partner-api-public.production.uniqkey.eu/openapi/v1.json.

Szybki test za pomocą curl

Sprawdź, czy klucz działa i do którego partnera należy:

curl -s "https://partner-api-public.production.uniqkey.eu/v1/me" \
  -H "Authorization: Bearer <your key>"

Następnie pobierz kilka pierwszych wierszy dotyczących licencji:

curl -s "https://partner-api-public.production.uniqkey.eu/v1/licenses?limit=5" \
  -H "Authorization: Bearer <your key>"

Poprawnie skonfigurowany system zwraca kod HTTP 200 z treścią JSON podobną do przykładów w sekcji „Odpowiedź”. Kod 401 oznacza, że brakuje nagłówka Authorization, nie zawiera on tokenu Bearer albo klucz jest nieprawidłowy, unieważniony lub wygasł.

Dokumentacja interfejsu API

Żądanie

GET /v1/licenses

Żądanie bez parametrów jest prawidłowe i zwraca każdy miesiąc dla każdej organizacji widocznej dla klucza, od najnowszych danych, po jednej stronie naraz.

Kursor jest nieprzejrzysty. Nie twórz go, nie analizuj ani nie modyfikuj. Jego format może się zmienić bez ostrzeżenia.

GET /v1/me

Nie przyjmuje parametrów. Zwraca partnera, do którego należy klucz, oraz nazwę, prefiks i datę wygaśnięcia klucza. Użyj go do przetestowania klucza. Żądanie to jest uwzględniane w limicie liczby żądań tak samo jak każde inne.

Odpowiedź

GET /v1/licenses:

{
  "items": [
    {
      "organizationId": "d5ecd732-4a67-418c-9dea-38a097fba1f6",
      "organizationName": "Example Customer ApS",
      "organizationExternalId": "CRM-10442",
      "partnerId": "3f2a9c1e-7b44-4d0a-9e51-2a6c8f0d1b77",
      "partnerName": "Example Reseller A/S",
      "month": "2026-09",
      "usageLicenseCount": 48,
      "committedLicenseCount": 50,
      "discoveryInstallationCount": 12,
      "discoveryActivatedNow": true
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJEIjoiMjAyNi0wOS0wMSIsIk8iOiJkNWVj..."
}

• Wiersze są uporządkowane od najnowszego miesiąca, a następnie według organizationId.
• hasMore informuje, czy należy zażądać następnej strony. Powtarzaj operację, dopóki hasMore ma wartość true.
• nextCursor ma wartość null na ostatniej stronie.

GET /v1/me:

{
  "partnerId": "3f2a9c1e-7b44-4d0a-9e51-2a6c8f0d1b77",
  "partnerName": "Example Reseller A/S",
  "keyName": "Billing sync",
  "keyPrefix": "uk_p_Xa81kQ2z",
  "expiresAt": "2027-03-31T21:59:59.999Z"
}

expiresAt jest podawane w UTC i ma wartość null dla klucza, który nie wygasa.

Błędy używają standardowego formatu szczegółów problemu (Content-Type: application/problem+json) ze stabilnym, przeznaczonym do odczytu maszynowego polem code:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "The request could not be processed.",
  "code": "bad_request",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Obsługę błędów należy opierać na polu code i statusie HTTP. Pola title i detail są przeznaczone dla użytkowników i mogą się zmienić.

Format wiersza

Limity liczby żądań

• Każdy partner może wykonywać co najmniej 120 żądań na minutę. Limit jest wspólny dla wszystkich kluczy partnera, dlatego utworzenie większej liczby kluczy nie zwiększa przepustowości.
• Po przekroczeniu limitu interfejs API zwraca kod 429 z kodem too_many_requests oraz nagłówkiem Retry-After zawierającym liczbę sekund oczekiwania. Przed ponowieniem żądania odczekaj co najmniej ten czas.
• Na poziomie sieci obowiązuje osobny, wyższy limit dla każdego źródłowego adresu IP. W przypadku prawidłowych odpowiedzi ten limit jest wskazywany w nagłówkach X-RateLimit-*. Po jego przekroczeniu również otrzymasz kod 429, ale bez treści JSON, dlatego obsługuj kod 429 na podstawie statusu i nagłówka Retry-After, a nie przez analizowanie treści odpowiedzi.

Codzienna synchronizacja z wartością limit=1000 wymaga tylko kilku żądań i pozostaje znacznie poniżej limitów.

Czego można oczekiwać od danych

• Liczby są miesięcznymi wartościami szczytowymi. Pola usageLicenseCount i discoveryInstallationCount zawierają najwyższe wartości spośród dziennych liczb odnotowanych w danym miesiącu, a nie średnią ani wartość z końca miesiąca. Użytkownik dodany i ponownie usunięty między dwoma dziennymi pomiarami nie zostanie uwzględniony.
• Dane mogą być opóźnione o maksymalnie jeden dzień. Wartości są rejestrowane przez codzienne zadanie uruchamiane krótko po północy UTC i przypisywane do poprzedniego dnia. Zmiana wprowadzona dzisiaj będzie widoczna po następnym uruchomieniu.
• Bieżący miesiąc może się jeszcze zmienić. Do zakończenia miesiąca nowa wartość szczytowa zwiększa wartość wiersza bieżącego miesiąca. Ostatni pomiar dla miesiąca jest wykonywany w pierwszej godzinie pierwszego dnia następnego miesiąca (UTC), dlatego miesiąc należy traktować jako ostateczny od godziny 02:00 UTC pierwszego dnia miesiąca.
• Każda organizacja otrzymuje wiersz dla każdego miesiąca, również dla miesięcy z zerowym wykorzystaniem. Wiersze zaczynają się od miesiąca utworzenia organizacji. W rzadkich przypadkach, takich jak nieudane codzienne uruchomienie, wiersz dla danego miesiąca może nie istnieć. Brakujący miesiąc traktuj jako nieznany, a nie jako wartość zero.
• Uwzględniane są organizacje testowe. Wiersze są zwracane dla każdej organizacji należącej do konta partnera, niezależnie od tego, czy jest ona płacącym klientem.
• Brak zobowiązania i zobowiązanie o wartości 0 wyglądają tak samo. W obu przypadkach zwracana jest wartość committedLicenseCount: null.
• discoveryInstallationCount oznacza instalacje, a nie tożsamości. Pole zlicza pasywne instalacje rozszerzenia, na podstawie których licencjonowana jest funkcja Discovery. Liczba „Tożsamości firmowe” na pulpicie Discovery oznacza coś innego i nie będzie zgodna z tą wartością.
• discoveryActivatedNow nie jest wartością historyczną. Odzwierciedla dzisiejsze ustawienie i jest powtarzana dla każdego miesiąca. Do rozliczeń używaj pola discoveryInstallationCount.
• Wyświetlane są bieżące nazwy. Jeśli nazwa organizacji lub partnera zostanie zmieniona, we wszystkich miesiącach będzie wyświetlana nowa nazwa. Dopasowuj dane na podstawie organizationId, a nie nazw.
• Usunięte organizacje zachowują historię. Miesiące zarejestrowane przed usunięciem organizacji nadal są zwracane. Wiersze nie wskazują, że organizacja została usunięta.
• Przeniesienie organizacji przenosi również jej historię. Tylko Uniqkey może przenieść organizację do innego partnera. Jeśli do tego dojdzie, wszystkie jej miesiące, w tym miesiące już rozliczone, zostaną przeniesione do nowego partnera. Znikną z wyników starego partnera, chyba że nowy partner znajduje się poniżej starego.

Uwagi dotyczące integracji z systemami rozliczeniowymi i CRM

• Zachowuj własną kopię rozliczonych miesięcy. Podczas rozliczania zapisuj w swoim systemie wiersze dotyczące każdego miesiąca. Z powodu opisanych powyżej przeniesień i zmian nazw ponowne pobranie miesiąca w późniejszym terminie może zwrócić dane różniące się od tych, na podstawie których wykonano rozliczenie.
• Używaj pól organizationId i month jako klucza. Każda organizacja ma najwyżej jeden wiersz na miesiąc. Przy kolejnych synchronizacjach aktualizuj wiersz zamiast wstawiać duplikaty.
• Ponownie odczytuj ostatnie miesiące. Prosta i niezawodna synchronizacja polega na ustawieniu parametru from na poprzedni miesiąc przy każdym uruchomieniu i zastępowaniu tych wierszy, a następnie zablokowaniu miesiąca w systemie po jego rozliczeniu.
• Mapuj klientów za pomocą pola organizationExternalId. W Portalu Partnera otwórz organizację, edytuj jej szczegóły i wprowadź numer klienta z systemu CRM w polu Identyfikator zewnętrzny. Możesz również ustawić go podczas tworzenia organizacji. Następnie będzie zwracany w każdym wierszu. Uniqkey nie sprawdza, czy wartość jest unikatowa.
• Używaj jednego klucza dla każdego systemu. Oddzielny klucz dla systemu rozliczeniowego i CRM ułatwia odczytywanie dziennika audytu oraz pozwala unieważnić jeden klucz bez zakłócania działania drugiego systemu.

Rozwiązywanie problemów

Kontaktując się z pomocą techniczną, podaj identyfikator partnera (z punktu końcowego /v1/me), nazwę klucza, dokładny adres URL żądania bez klucza, status HTTP oraz treść odpowiedzi wraz z wartością traceId.