Integracja z API Vojager

API służy do komunikacji serwer–serwer. Nie umieszczaj klucza w przeglądarce, aplikacji mobilnej ani publicznym repozytorium.

Pobierz kanoniczną specyfikację OpenAPI (YAML)

Szybki start

Odpowiedzi API mogą zyskiwać opcjonalne pola. Klient powinien ignorować nieznane pola odpowiedzi zamiast odrzucać cały obiekt.

  1. W panelu utwórz zestaw reguł i aktywuj wersję. Bez aktywnej wersji ocena zwraca 409.
  2. W sekcji „Klucz API” wygeneruj klucz produkcyjny albo testowy. Klucz produkcyjny ma format vjg_<prefiks>_<sekret>, a testowy vjg_test_<prefiks>_<sekret>. Zapisz go w bezpiecznej konfiguracji serwera; pełny klucz jest pokazywany tylko raz.
  3. Pobierz katalog oraz dopasowany do firmy przykład. Katalog pokazuje też cechy nieaktywne; parser API nadal rozpoznaje je według katalogu firmy. Polecenie używa jq, aby zapisać samą kopertę wniosku, bez objaśnienia z odpowiedzi.
export VOJAGER_API_KEY='wstaw-klucz-z-panelu'
curl -H "Authorization: Bearer ${VOJAGER_API_KEY}" https://app.vojager.pl/api/v1/catalog
curl -fsS -H "Authorization: Bearer ${VOJAGER_API_KEY}" https://app.vojager.pl/api/v1/catalog/example | jq .application > wniosek.json
  1. W pliku wniosek.json zastąp wszystkie przykładowe wartości i ustaw własny, unikalny application_id. Klucz testowy wymusza test: true, nawet gdy pole pominięto. Jawne test: false przy kluczu testowym zwraca 422 z errors.test i nie zapisuje oceny. Klucz produkcyjny zachowuje wartość pola test. Oceny testowe zapisują się w historii firmy.
  2. Wyślij wniosek jako JSON. Zachowaj otrzymany adres Location, aby pobrać ocenę.
curl -i -X POST https://app.vojager.pl/api/v1/assessments \
  -H "Authorization: Bearer ${VOJAGER_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data-binary @wniosek.json

# Następnie odczytaj adres z nagłówka Location:
curl -H "Authorization: Bearer ${VOJAGER_API_KEY}" 'https://app.vojager.pl/api/v1/assessments/ID-OCENY'

Ponawianie: 429 ponów dopiero po czasie z Retry-After. Po timeout lub utracie odpowiedzi POST nie ponawiaj automatycznie: najpierw wyszukaj unikalny application_id w historii panelu; jeśli wynik pozostaje nieznany, skieruj wniosek do ręcznej weryfikacji. Automatyczne ponowienie jest dozwolone wyłącznie po otrzymanej odpowiedzi 5xx/502: najwyżej 3 próby, z odstępami 2 s, 10 s i 30 s, a potem ręczna weryfikacja. POST nie ma klucza idempotencji i ponowienie po 5xx/502 może utworzyć widoczną duplikację. Dla 409 najpierw aktywuj wersję; 415 i 422 wymagają poprawienia żądania, bez ponawiania.