Dokumentacja API: architektura, pola i kody statusu

Elementy wspólne dla każdej operacji: przepływ żądań, wspólne pola JSON, typy szablonów, kody statusu, porty i szyfrowanie payloadu.

Dokumentacja API

Architektura API

Właściwość	Callback API	RESTful API
Inicjator	Urządzenie / Biometric Gateway	Twój serwer
Kierunek	Urządzenie → Twój serwer	Twój serwer → urządzenie
Opóźnienie	Czas rzeczywisty (milisekundy)	~15 sekund
Wyzwalacz	Zdarzenie biometryczne na urządzeniu	HTTP POST z Twojego kodu
Twoja rola	Odbierz & potwierdź	Wyślij polecenie & odpytuj/czekaj na odpowiedź
Ciało odpowiedzi	`{"status":"done"}`	`{"Status":"done","OperationID":"…","StatusCode":0}`
Zachowanie offline	Buforowane przez silnik; dostarczane po powrocie serwera online	Kolejkowane przez silnik; dostarczane po ponownym połączeniu urządzenia

Dokumentacja API

Wspólne pola

Wszystkie żądania — zarówno Callback, jak i RESTful — mają wspólne pola najwyższego poziomu.

AuthTokenString. 32-znakowy token identyfikujący i uwierzytelniający żądania z konkretnego urządzenia. Konfigurowany w portalu API Monitor. Weryfikuj go przy każdym przychodzącym callbacku.

OperationIDString. Unikalny identyfikator tej instancji operacji (np. "j95xfejt3vr1"). Odpowiedzi RESTful zwracają ten sam OperationID, dzięki czemu możesz dopasować żądania do odpowiedzi.

TimeString. Znacznik czasu UTC przetworzenia zdarzenia w formacie YYYY-MM-DD HH:mm:ss GMT +0000. Lokalne znaczniki czasu urządzenia w payloadzie mogą używać innego przesunięcia strefy czasowej.

stgid (parametr zapytania)String. Service Tag ID — identyfikuje docelowe urządzenie dla wywołań RESTful API. Przekaż jako parametr zapytania URL do endpointu z Twojego konta API Monitor: POST https://<your-endpoint>?stgid=YOUR_TAG_ID.

Typy szablonów

Dane biometryczne i uwierzytelniające są przesyłane w tablicy Template. Każdy element ma pole Type:

Łączenie szablonów — ważne dla handlerów callbacków
Gdy dane użytkownika są przesyłane z urządzenia (operacje Callback #3–#9), szablony mogą przychodzić pojedynczo lub w grupach, w wielu callbackach. Każdy callback nie zawiera pełnego zestawu szablonów użytkownika — przenosi tylko szablony, które zostały dodane lub zmienione.

Twój serwer musi scalać przychodzące szablony z już zapisanymi szablonami tego użytkownika. Unikalnym kluczem szablonu jest Type + Index. Na przykład:
• Callback 1 przychodzi z Fingerprint Index 0 → zapisz go
• Callback 2 przychodzi z Face Index 0 + Card → scal, nie nadpisuj odcisku palca
• Callback 3 przychodzi z Fingerprint Index 0 (nowe dane) → zaktualizuj istniejący odcisk palca o Index 0
Nigdy nie zastępuj wszystkich szablonów podczas callbacku — zawsze wykonuj upsert według Type + Index.

Typ	Opis	Kluczowe dodatkowe pola
`Card`	Numer karty RFID / zbliżeniowej	`Data` (ciąg z numerem karty)
`Password`	Numeryczny PIN	`Data` (ciąg z PIN-em)
`Fingerprint`	Szablon odcisku palca — dane binarne zakodowane w Base64	`Index` (indeks palca 0–9), `Size`, `Data`
`Face`	Szablon twarzy — JPEG lub dane binarne zakodowane w Base64	`Index`, `Size`, `Data`
`Palm`	Szablon żył dłoni — dane binarne zakodowane w Base64	`Index`, `Data`
`UserPhoto`	Zdjęcie profilowe użytkownika — JPEG zakodowany w Base64	`Data`

Dokumentacja API

Kody statusu odpowiedzi

Odpowiedzi RESTful API zawierają numeryczny StatusCode. Odpowiedzi Callback API zawsze mają prostą postać {"status":"done"}, niezależnie od wyniku.

Kod	Status	Opis
`0`	Sukces	Operacja zakończona pomyślnie.
`1`	Nieprawidłowe dane żądania	Ciało JSON jest nieprawidłowo sformatowane lub zawiera niepoprawne wartości.
`2`	Nieprawidłowy Service Tag ID	Parametr zapytania `stgid` nie odpowiada żadnemu zarejestrowanemu urządzeniu.
`3`	Nieprawidłowe żądanie	Struktura żądania nie odpowiada oczekiwanemu formatowi operacji.
`4`	Nieprawidłowe szyfrowanie	Nie udało się odszyfrować payloadu zaszyfrowanego (AES-256). Sprawdź klucz szyfrowania.
`5`	Urządzenie offline	Urządzenie docelowe nie jest obecnie połączone z Biometric Gateway.
`6`	Przekroczono czas operacji	Urządzenie nie potwierdziło polecenia w wyznaczonym czasie.
`7`	Nieprawidłowy Auth Token	`AuthToken` w żądaniu nie zgadza się z tokenem skonfigurowanym dla urządzenia.
`8`	Użytkownik już istnieje	Podjęto próbę operacji Add dla UserID, który już istnieje na urządzeniu.
`9`	Nie znaleziono użytkownika	Podany UserID nie istnieje na urządzeniu.
`10`	Błąd szablonu	Dane szablonu biometrycznego są uszkodzone lub mają nieobsługiwany format.
`11`	Pamięć urządzenia pełna	Urządzenie osiągnęło maksymalną pojemność użytkowników lub szablonów.
`13`	Nieprawidłowy klucz zabezpieczający	Klucz zabezpieczający skonfigurowany w API Monitor nie zgadza się.
`15`	Funkcja nieobsługiwana	Żądana operacja nie jest obsługiwana przez ten model urządzenia lub tryb komunikacji.
`999`	Nieznany błąd	Wystąpił nieoczekiwany błąd. Skontaktuj się ze wsparciem Cams, podając OperationID.

Informacje dodatkowe

Obsługiwane porty

Aby odbierać informacje o obecności w czasie rzeczywistym, Twój serwer musi udostępniać endpoint HTTP(S), do którego ma dostęp Cams Protocol Engine.

Port	Protokół	Zastosowanie
`80`	HTTP	Produkcja. Powiąż swój callback URL z portem 80. Konfigurowane w API Monitor i wywoływane automatycznie przy odbiciach.
`443`	HTTPS	Produkcja (bezpieczna). HTTPS z prawidłowym certyfikatem SSL. Zalecane dla środowiska produkcyjnego.
`8123`	HTTP	Tylko do testów. Niestandardowy port tymczasowo dostępny na czas prac deweloperskich.

Zalecane HTTPS. W środowisku produkcyjnym używaj HTTPS z prawidłowym certyfikatem SSL. Zadbaj o automatyczne odnawianie bez restartu serwera.

Informacje dodatkowe

Przykładowe dane

Przykładowe payloady żądań i odpowiedzi dla wszystkich 38 operacji znajdują się powyżej w sekcji każdej operacji. Zestawienie zbiorcze:

Ta stronaKażda sekcja operacji powyżej zawiera gotowe do skopiowania JSON żądania i odpowiedzi z przykładowymi danymi.

Starsza strona z przykładamibiometric-web-api-sample-request-response.html — lista rozwijana dla każdej operacji.

Informacje dodatkowe

Szyfrowanie

Opcjonalne szyfrowanie AES-256 można włączyć dla wszystkich danych wymienianych między Cams Protocol Engine a Twoim serwerem.

AlgorytmAES-256 w trybie ECB z dopełnieniem PKCS5 (AES/ECB/PKCS5PADDING).

Konfiguracja kluczaUstaw swój klucz jako Security Key w API Monitor. Po skonfigurowaniu wszystkie surowe payloady JSON są szyfrowane.

KodowanieZaszyfrowane payloady są kodowane w Base64 dla bezpiecznego transportu HTTP.

Przykład w Javie

Szyfrowanie / odszyfrowywanie (Java)

// Encryption
Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5PADDING");
SecretKeySpec keySpec = new SecretKeySpec(securityKey.getBytes("UTF-8"), "AES");
cipher.init(Cipher.ENCRYPT_MODE, keySpec);
String encrypted = Base64.getEncoder().encodeToString(cipher.doFinal(rawJson.getBytes("UTF-8")));

// Decryption
cipher.init(Cipher.DECRYPT_MODE, keySpec);
byte[] decoded = Base64.getDecoder().decode(encryptedPayload);
String decrypted = new String(cipher.doFinal(decoded), "UTF-8");

Ważne: Gdy szyfrowanie jest włączone, odszyfrowuj przychodzące payloady Callback i szyfruj wychodzące ciała żądań RESTful tym samym kluczem.