Codenica API

Codenica API pozwala połączyć zewnętrzne aplikacje z danymi w Twoim systemie Codenica, zarówno w wersji Cloud jak i w wersji On-Premise. Artykuł opisuje zasady wspólne dla całego API: utworzenie klucza, wybór zakresów, adres usługi, sposób uwierzytelniania oraz reguły bezpiecznego wykonywania żądań. Szczegóły pól i operacji dla poszczególnych obiektów znajdziesz w osobnych artykułach API.

Utworzenie klucza API

Przygotowanie integracji zacznij od przygotowania odpowiednich kluczy API. Klucz jest przypisany do Twojej firmy i służy zewnętrznej aplikacji do wykonywania wyłącznie operacji objętych wybranymi zakresami.

  1. Otwórz Ustawienia, a następnie wybierz API i API Keys.
  2. W polu Nazwa wpisz nazwę integracji, na przykład Integracja magazynowa albo Raporty BI.
  3. Opcjonalnie dodaj opis, aby później łatwo rozpoznać zastosowanie klucza.
  4. Ustaw datę Aktywny do. Krótszy czas aktywności ogranicza skutki przypadkowego ujawnienia sekretu.
  5. Wybierz tylko te zakresy uprawnień, których wymaga integracja.
  6. Wybierz Utwórz klucz API.
  7. Skopiuj od razu Client ID oraz Client Secret i zapisz je w bezpiecznym magazynie sekretów używanym przez integrację.

Client Secret jest pokazywany tylko po utworzeniu klucza albo podczas jego rotacji. Lista kluczy przechowuje informacje o kluczu, ale nie zwraca ponownie sekretu. Jeśli sekret zaginie, wykonaj rotację lub usuń klucz i utwórz nowy.

Panel API Keys w ustawieniach Codenica z formularzem tworzenia klucza i listą zakresów uprawnień.

Limity kluczy zależne od licencji

Każdy klucz warto traktować jako osobny kanał dostępu dla jednej integracji. Liczba dostępnych kluczy zależy od licencji firmy:

Licencja
Dostęp do API
Maksymalna liczba aktywnych kluczy
Starter
Brak
0
Plus
Tak
50
Enterprise
Tak
100

Usunięcie klucza usuwa jego rekord i zwalnia miejsce w limicie. Operacja jest trwała, dlatego przed usunięciem upewnij się, że dana integracja nie korzysta już z tego klucza. Wygaśnięcie daty aktywności zatrzymuje uwierzytelnianie, ale nie zastępuje porządkowania listy kluczy.

Jeżeli przy tworzeniu nie ustawisz daty końcowej, domyślny okres ważności wynosi 90 dni. Maksymalny czas aktywności jednego klucza to 5 lat. W praktyce najlepiej dopasować datę do cyklu przeglądu danej integracji.

Adres API i uwierzytelnianie

Adres bazowy zależy od sposobu wdrożenia. Do adresu bazowego dopisujesz ścieżkę /api/v1 oraz ścieżkę konkretnego zasobu.

  • Cloud: użyj publicznego adresu firmy, na przykład https://twoja-firma.codenica.com/api/v1.
  • On-Premise: domyślny adres zarejestrowany przez Codenica Discovery to http://codenica.local:5150/api/v1. Jeśli administrator opublikował instalację pod własną nazwą DNS, reverse proxy albo przez HTTPS, użyj adresu dostępnego dla serwera integracji. Szczegóły wdrożenia opisuje instrukcja instalacji Codenica On-Premise.

Nie używaj localhost, adresu kontenera ani adresu bazy danych, chyba że aplikacja integrująca działa dokładnie na tym samym komputerze i jest to świadoma konfiguracja testowa. Serwer integracji musi mieć dostęp sieciowy do opublikowanego adresu Codenica.

Każde żądanie API uwierzytelniaj dwoma nagłówkami:

  • X-Codenica-Client-Id - identyfikator klucza;
  • X-Codenica-Client-Secret - sekret klucza.

Do Public API nie przekazujesz sesji panelu ani tokenu JWT użytkownika. Sekretu nie umieszczaj w adresie URL, parametrach zapytania, treści odpowiedzi ani logach.

export BASE_URL="https://twoja-firma.codenica.com"
export CLIENT_ID="cna_twoj_client_id"
export CLIENT_SECRET="cns_twoj_client_secret"

curl --request GET \
  --url "$BASE_URL/api/v1/context" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Dla domyślnej instalacji On-Premise wartość BASE_URL w powyższym przykładzie zastąp przez http://codenica.local:5150. W środowisku produkcyjnym używaj HTTPS, jeśli instalacja jest opublikowana z certyfikatem.

Standardowy układ żądań

Przykłady w kolejnych artykułach korzystają z prostego układu znanego z dokumentacji REST: metoda, adres URL, nagłówki, a przy operacjach z treścią także JSON w parametrze --data-raw. Taki zapis można łatwo przenieść do kodu aplikacji albo narzędzia integracyjnego.

Operacje zmieniające dane wymagają dodatkowo nagłówka Idempotency-Key. Nadaj mu unikalną wartość dla każdej intencji wykonania operacji. Ponowienie dokładnie tego samego żądania z tym samym kluczem nie powinno tworzyć drugiego rekordu.

curl --request POST \
  --url "$BASE_URL/api/v1/<resource>" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: integration-create-20260907-001" \
  --data-raw '{"field":"value"}'

W przypadku aktualizacji, usunięcia, relacji i operacji na plikach użyj również nagłówka If-Match z aktualną wartością ETag. Konkretne ścieżki, nazwy pól i przykładowe treści znajdziesz na stronach poszczególnych obiektów.

Wspólny cykl pracy integracji

  1. Wyślij GET /api/v1/context, aby sprawdzić dane firmy, caller, zakresy, możliwości API i limity.
  2. Otwórz schemat interesującego obiektu, na przykład GET /api/v1/assets/schema, aby poznać dostępne pola, operacje, zakresy i obsługiwane relacje.
  3. Pobierz listę obiektów z paginacją i filtrami. Parametry filtrowania są opisane w artykule danego obiektu.
  4. Odczytaj pojedynczy rekord po identyfikatorze, gdy potrzebujesz aktualnych danych oraz jego ETag.
  5. Twórz, aktualizuj i usuwaj rekordy z zachowaniem Idempotency-Key oraz, gdy jest wymagany, If-Match.
  6. Relacje, pliki, operacje zbiorcze i akcje specjalne wykonuj wyłącznie przez ścieżki opisane dla danego obiektu.

Wspólny format odpowiedzi

Udane odpowiedzi zwracają dane w polu data. Informacje techniczne, takie jak requestId i czasem ETag, znajdują się w polu meta. Identyfikator requestId zachowaj w logu integracji, aby można było szybko odszukać żądanie podczas diagnozowania problemu.

ETag, ponowienia i błędy

ETag chroni rekord przed nadpisaniem zmian wykonanych przez inną osobę lub integrację. Po odczycie zapisz wartość nagłówka ETag. Przed aktualizacją albo usunięciem przekaż ją jako If-Match. Po udanej zmianie używaj nowej wartości zwróconej przez API.

  • 428 Precondition Required z kodem if_match_required oznacza brak wymaganego nagłówka If-Match lub Idempotency-Key.
  • 412 Precondition Failed z kodem if_match_failed oznacza, że użyta wartość ETag nie jest już aktualna. Odczytaj rekord ponownie i zdecyduj, czy chcesz powtórzyć zmianę.
  • 429 Too Many Requests oznacza przekroczenie limitu. Odczytaj nagłówek Retry-After, jeśli został zwrócony, i ponów żądanie po czasie z rosnącym opóźnieniem.

Błędy mają format Problem Details. Najważniejsze pola to status, code, detail i requestId. Nie traktuj samego tekstu detail jako stabilnego identyfikatora błędu - do logiki aplikacji używaj pola code.

Odpowiedzi zawierają także nagłówki limitu, między innymi X-RateLimit-Limit i X-RateLimit-Remaining. Integracja powinna ograniczać tempo żądań, reagować na 429 i nie wykonywać agresywnej pętli ponowień.

Artykuły API dla poszczególnych obiektów

Po utworzeniu klucza i sprawdzeniu połączenia wybierz artykuł odpowiadający danym, które chcesz zintegrować:

  • API - Zasoby - komputery, urządzenia, oprogramowanie i pozostałe elementy ewidencji wraz z polami, relacjami i plikami.
  • API - Dokumenty - dokumenty firmowe, takie jak faktury, ich dane opisowe, pliki i powiązania.
  • API - Klienci / Pracownicy - dane klientów lub pracowników, kontakty, informacje organizacyjne i obsługiwane relacje.
  • API - Dostawcy - kartoteki dostawców oraz relacje dostępne dla tego obiektu, w szczególności dokumenty i notatki.
  • API - Zgłoszenia - zgłoszenia Service Desk, ich cykl życia, pola operacyjne, pliki i relacje.
  • API - Zmiany - planowane zmiany w środowisku IT, etapy realizacji i dane potrzebne do kontroli procesu.
  • API - Problemy - problemy wymagające analizy przyczyny, obsługi procesu i powiązania z innymi elementami.
  • API - Wydania - planowanie i obsługa wydań, statusy oraz informacje o wdrażanych zmianach.
  • API - Rozwiązania - wpisy bazy rozwiązań oraz ich powiązania z problemami.
  • API - Notatki - notatki, prywatność, przypinanie wpisów, pliki i relacje z rekordami.
  • API - Akceptacje - procesy akceptacji, dane decyzji, przypisania i obsługa wyniku.
  • API - Potwierdzenia - potwierdzenia wymagające decyzji klienta oraz ich pliki i powiązania.
  • API - Zadania - zadania robocze, przypisania, statusy, relacje i załączniki.
  • API - Zapotrzebowania - zapotrzebowania na produkty lub usługi, dane realizacji, pliki i powiązania.
  • API - Godziny pracy - wpisy czasu pracy powiązane ze zgłoszeniem, zmianą, problemem, wydaniem albo zadaniem roboczym.

Krótka lista kontrolna przed uruchomieniem integracji

  • Utwórz osobny klucz dla każdej integracji i nadaj mu tylko potrzebne zakresy.
  • Przechowuj Client ID i Client Secret w magazynie sekretów, a nie w repozytorium ani w kodzie wysyłanym do przeglądarki.
  • Ustaw termin aktywności dopasowany do sposobu zarządzania daną integracją.
  • W produkcji korzystaj z HTTPS i adresu firmy dostępnego dla serwera integracji.
  • Loguj requestId, status HTTP i kod błędu, ale maskuj Client Secret.
  • Obsłuż paginację, limity, 429, ETag oraz bezpieczne ponowienia.

Po wykonaniu tych czynności przejdź do artykułu wybranego obiektu. Znajdziesz tam gotowe ścieżki, pola i przykłady operacji właściwe dla danego rodzaju danych.