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.
Szybkie odpowiedzi
Jakie są dwa przepływy API?
Callback API wysyła zdarzenia z urządzenia (przez Cams Biometric Gateway) do Twojego serwera w czasie rzeczywistym. RESTful API pozwala Twojemu serwerowi wysyłać polecenia do urządzenia, a odpowiedź przychodzi po około 15 sekundach. Jeśli Twój serwer jest offline, silnik buforuje callbacki; polecenia REST trafiają do kolejki do czasu ponownego połączenia urządzenia.
Jakie kody statusu zwraca RESTful API?
Liczbowy StatusCode: 0 sukces, 1 nieprawidłowe dane żądania, 2 nieprawidłowy Service Tag ID, 3 nieprawidłowe żądanie, 4 nieprawidłowe szyfrowanie, 5 urządzenie offline, 6 przekroczenie czasu operacji, 7 nieprawidłowy token uwierzytelniania, 8 użytkownik już istnieje, 9 nie znaleziono użytkownika, 10 błąd szablonu, 11 pamięć urządzenia pełna, 13 nieprawidłowy klucz bezpieczeństwa, 15 funkcja nieobsługiwana, 999 nieznany błąd. Odpowiedzi na callbacki zawsze używają {"status":"done"}.
Co oznacza kod statusu 5 (Urządzenie offline)?
Urządzenie docelowe nie jest obecnie połączone z Biometric Gateway. Zobacz kod statusu 5.
Jak uwierzytelniać żądania?
Każde żądanie zawiera AuthToken — 32-znakowy token, który identyfikuje jedno urządzenie i jest ustawiany w portalu API Monitor. Weryfikuj go przy każdym przychodzącym callbacku. Wywołania REST przekazują też urządzenie w parametrze zapytania stgid (Service Tag ID). Zobacz Wspólne pola.
Jakich portów potrzebuje mój serwer?
Port 80 (HTTP) lub 443 (HTTPS) w środowisku produkcyjnym; zalecany jest HTTPS z ważnym certyfikatem. Port 8123 (HTTP) służy wyłącznie do testów. Zobacz Obsługiwane porty.
Jak szyfrowane są dane żądania?
Szyfrowanie jest opcjonalne. Po włączeniu dane są szyfrowane algorytmem AES-256 w trybie ECB z dopełnieniem PKCS5 (AES/ECB/PKCS5PADDING) z użyciem klucza bezpieczeństwa (Security Key) ustawionego w API Monitor i kodowane w Base64 na potrzeby transportu HTTP. Odszyfrowuj przychodzące callbacki i szyfruj wychodzące treści REST tym samym kluczem. Zobacz Szyfrowanie.
Jak obsługiwać szablony przychodzące w kilku callbackach?
Scalaj je. Każdy callback zawiera tylko szablony, które zostały dodane lub zmienione. Unikalnym kluczem szablonu jest Type + Index, więc wykonuj upsert według tej pary i nigdy nie zastępuj całego zestawu szablonów użytkownika. Zobacz Typy szablonów.
Jakie typy szablonów istnieją?
Card, Password, Fingerprint, Face, Palm i UserPhoto. Szablony Fingerprint, Face i Palm są kodowane w Base64, a indeks odcisku palca przyjmuje wartości 0–9.
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 |
Wspólne pola
Wszystkie żądania — zarówno Callback, jak i RESTful — mają wspólne pola najwyższego poziomu.
"j95xfejt3vr1"). Odpowiedzi RESTful zwracają ten sam OperationID, dzięki czemu możesz dopasować żądania do odpowiedzi.YYYY-MM-DD HH:mm:ss GMT +0000. Lokalne znaczniki czasu urządzenia w payloadzie mogą używać innego przesunięcia strefy czasowej.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:
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 0Nigdy 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 |
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. |
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. |
Przykładowe dane
Przykładowe payloady żądań i odpowiedzi dla wszystkich 38 operacji znajdują się powyżej w sekcji każdej operacji. Zestawienie zbiorcze:
Szyfrowanie
Opcjonalne szyfrowanie AES-256 można włączyć dla wszystkich danych wymienianych między Cams Protocol Engine a Twoim serwerem.
AES/ECB/PKCS5PADDING).Przykład w Javie
// 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");