FAQ, SDK i koszty
Najczęstsze pytania integratorów oraz zasady działania SDK i cennika API.
Informacje dodatkowe
Najczęściej zadawane pytania
Najczęstsze pytania dotyczące integracji z Cams Biometrics Web API 3.0.
Ogólne
P: Czym jest Cams Biometric Gateway i jego Biometric API?
Cams Biometric Gateway to uniwersalna platforma chmurowa udostępniająca Biometric API, które umożliwia dowolnej aplikacji webowej komunikację z biometrycznymi urządzeniami do rejestracji czasu pracy i kontroli dostępu w czasie rzeczywistym. Obsługuje 38 operacji w ramach Callback API (przychodzące) i RESTful API (wychodzące) — bez konieczności korzystania z SDK urządzenia ani stałego adresu IP.
Cams Biometric Gateway to uniwersalna platforma chmurowa udostępniająca Biometric API, które umożliwia dowolnej aplikacji webowej komunikację z biometrycznymi urządzeniami do rejestracji czasu pracy i kontroli dostępu w czasie rzeczywistym. Obsługuje 38 operacji w ramach Callback API (przychodzące) i RESTful API (wychodzące) — bez konieczności korzystania z SDK urządzenia ani stałego adresu IP.
P: Czy potrzebuję SDK do integracji?
Nie. Cams nie dostarcza ani nie wymaga SDK. Cała komunikacja odbywa się za pomocą standardowych żądań HTTP/HTTPS POST z payloadami JSON. Sprawdzi się każdy język, który potrafi wykonywać wywołania HTTP.
Nie. Cams nie dostarcza ani nie wymaga SDK. Cała komunikacja odbywa się za pomocą standardowych żądań HTTP/HTTPS POST z payloadami JSON. Sprawdzi się każdy język, który potrafi wykonywać wywołania HTTP.
P: Które języki programowania są obsługiwane?
Każdy język, który potrafi wysyłać/odbierać HTTP POST z JSON — PHP, Python, Java, C#, Node.js, Go, Ruby i inne. Udostępniamy prompty do generatorów kodu AI dla 7 języków.
Każdy język, który potrafi wysyłać/odbierać HTTP POST z JSON — PHP, Python, Java, C#, Node.js, Go, Ruby i inne. Udostępniamy prompty do generatorów kodu AI dla 7 języków.
P: Czym jest Cams Protocol Engine?
To chmurowe oprogramowanie pośredniczące między urządzeniami biometrycznymi a Twoim serwerem. Zajmuje się translacją protokołów, normalizacją danych i buforowaniem offline oraz zapewnia spójne API JSON niezależnie od marki i modelu urządzenia.
To chmurowe oprogramowanie pośredniczące między urządzeniami biometrycznymi a Twoim serwerem. Zajmuje się translacją protokołów, normalizacją danych i buforowaniem offline oraz zapewnia spójne API JSON niezależnie od marki i modelu urządzenia.
P: Czym jest API Monitor?
API Monitor to Twój portal administracyjny, w którym konfigurujesz Callback URL, zarządzasz AuthToken, ustawiasz Security Key, sprawdzasz status urządzeń oraz znajdziesz adres URL endpointu RESTful i Service Tag ID.
API Monitor to Twój portal administracyjny, w którym konfigurujesz Callback URL, zarządzasz AuthToken, ustawiasz Security Key, sprawdzasz status urządzeń oraz znajdziesz adres URL endpointu RESTful i Service Tag ID.
Zgodność urządzeń
P: Które urządzenia biometryczne są obsługiwane?
Wszystkie urządzenia Cams Biometrics (wymienione na camsbiometrics.com/product) obsługują pełne API w trybie Native Push. Urządzenia zweryfikowane na developer.camsbiometrics.com również mają pełną obsługę Native Push.
Wszystkie urządzenia Cams Biometrics (wymienione na camsbiometrics.com/product) obsługują pełne API w trybie Native Push. Urządzenia zweryfikowane na developer.camsbiometrics.com również mają pełną obsługę Native Push.
P: Czy urządzenia innych marek niż Cams (ZkTeco, eSSL, BioMax itd.) mogą korzystać z tego API?
Tak, po wykonaniu Protocol Update. Urządzenia innych marek niż Cams i niezweryfikowane działają w trybie Hybrid Push. Niektóre funkcje mogą być ograniczone w zależności od trybu połączenia i możliwości sprzętu.
Tak, po wykonaniu Protocol Update. Urządzenia innych marek niż Cams i niezweryfikowane działają w trybie Hybrid Push. Niektóre funkcje mogą być ograniczone w zależności od trybu połączenia i możliwości sprzętu.
P: Jaka jest różnica między Native Push a Hybrid Push?
Native Push: pełna obsługa API bez ograniczeń — działają wszystkie 38 operacji. Dostępny dla urządzeń Cams i zweryfikowanych.
Hybrid Push: dla urządzeń innych niż Cams/niezweryfikowanych. Dostępność funkcji zależy od trybu komunikacji (SDK, DB Pull lub przetwarzanie plików). Zobacz Tryby połączenia.
Native Push: pełna obsługa API bez ograniczeń — działają wszystkie 38 operacji. Dostępny dla urządzeń Cams i zweryfikowanych.
Hybrid Push: dla urządzeń innych niż Cams/niezweryfikowanych. Dostępność funkcji zależy od trybu komunikacji (SDK, DB Pull lub przetwarzanie plików). Zobacz Tryby połączenia.
P: Jakie metody biometryczne są obsługiwane?
Odcisk palca, rozpoznawanie twarzy, układ żył dłoni, karta RFID/zbliżeniowa, numeryczny PIN/hasło, skanowanie tęczówki i pomiar temperatury ciała (zależnie od urządzenia).
Odcisk palca, rozpoznawanie twarzy, układ żył dłoni, karta RFID/zbliżeniowa, numeryczny PIN/hasło, skanowanie tęczówki i pomiar temperatury ciała (zależnie od urządzenia).
P: Niektóre funkcje API nie działają z moim urządzeniem. Dlaczego?
Zależy to od (a) trybu połączenia — tryby DB Pull i przetwarzanie plików obsługują wyłącznie przesyłanie obecności, a nie RESTful API, oraz (b) ograniczeń sprzętowych — niektóre modele urządzeń mogą nie obsługiwać określonych funkcji na poziomie firmware'u. Przetestuj na swoim sprzęcie i skontaktuj się ze wsparciem Cams, aby uzyskać pomoc.
Zależy to od (a) trybu połączenia — tryby DB Pull i przetwarzanie plików obsługują wyłącznie przesyłanie obecności, a nie RESTful API, oraz (b) ograniczeń sprzętowych — niektóre modele urządzeń mogą nie obsługiwać określonych funkcji na poziomie firmware'u. Przetestuj na swoim sprzęcie i skontaktuj się ze wsparciem Cams, aby uzyskać pomoc.
Callback API (urządzenie → serwer)
P: Czym jest Callback API?
Callback API dostarcza zdarzenia z urządzeń biometrycznych do Twojego serwera w czasie rzeczywistym. Gdy nastąpi odbicie lub użytkownik zostanie zmodyfikowany na urządzeniu, Cams Protocol Engine natychmiast wysyła payload JSON metodą POST na skonfigurowany Callback URL.
Callback API dostarcza zdarzenia z urządzeń biometrycznych do Twojego serwera w czasie rzeczywistym. Gdy nastąpi odbicie lub użytkownik zostanie zmodyfikowany na urządzeniu, Cams Protocol Engine natychmiast wysyła payload JSON metodą POST na skonfigurowany Callback URL.
P: Co powinien odpowiadać mój serwer?
Zawsze zwracaj
Zawsze zwracaj
{"status":"done"} ze statusem HTTP 200 — nawet jeśli wewnętrzne przetwarzanie się nie powiedzie. Nigdy nie blokuj Cams Protocol Engine. Ciężkie przetwarzanie dodawaj do kolejki i wykonuj asynchronicznie.P: Co się stanie, jeśli mój serwer będzie offline w momencie odbicia?
Biometric Gateway buforuje wszystkie zdarzenia i dostarcza je automatycznie, gdy tylko Twój serwer wróci online. Żadne dane nie zostaną utracone.
Biometric Gateway buforuje wszystkie zdarzenia i dostarcza je automatycznie, gdy tylko Twój serwer wróci online. Żadne dane nie zostaną utracone.
P: Jak obsłużyć zduplikowane odbicia?
Zaimplementuj na swoim serwerze logikę wykrywania duplikatów, wykorzystując kombinację
Zaimplementuj na swoim serwerze logikę wykrywania duplikatów, wykorzystując kombinację
UserID + LogTime. To samo odbicie może zostać wysłane ponownie podczas odzyskiwania po przerwie offline lub przy ponowieniach sieciowych.P: Jakie typy odbić są obsługiwane?
CheckIn, CheckOut, BreakOut, BreakIn, OverTimeIn, OverTimeOut, MealIn, MealOut. Pole InputType wskazuje użytą metodę biometryczną: Fingerprint, Face, Palm, Card lub Password.P: Jak działają szablony użytkowników w callbackach?
Gdy użytkownik jest aktualizowany na urządzeniu (operacje #3–#9), szablony mogą przychodzić pojedynczo lub w grupach, w wielu callbackach. Każdy callback przenosi tylko szablony, które uległy zmianie — nie pełny zestaw. Twój serwer musi scalać/wykonywać upsert z kluczem unikalnym
Gdy użytkownik jest aktualizowany na urządzeniu (operacje #3–#9), szablony mogą przychodzić pojedynczo lub w grupach, w wielu callbackach. Każdy callback przenosi tylko szablony, które uległy zmianie — nie pełny zestaw. Twój serwer musi scalać/wykonywać upsert z kluczem unikalnym
Type + Index. Nigdy nie nadpisuj wszystkich szablonów na podstawie pojedynczego callbacku.P: Czy mogę otrzymywać zdjęcia z obecności?
Tak. Operacja #10 RealTimeAttendancePhoto dostarcza zdjęcie JPEG zakodowane w Base64, wykonane w momencie odbicia. Jest ona oddzielna od callbacku dziennika odbić (#11) i dostępna na urządzeniach z kamerą.
Tak. Operacja #10 RealTimeAttendancePhoto dostarcza zdjęcie JPEG zakodowane w Base64, wykonane w momencie odbicia. Jest ona oddzielna od callbacku dziennika odbić (#11) i dostępna na urządzeniach z kamerą.
P: Czy Callback zawiera temperaturę i wykrywanie maski?
Tak, jeśli urządzenie to obsługuje. Obiekt
Tak, jeśli urządzenie to obsługuje. Obiekt
PunchLog zawiera Temperature (odczyt temperatury ciała) i FaceMask (wartość logiczna — czy wykryto maskę na twarzy).RESTful API (serwer → urządzenie)
P: Czym jest RESTful API?
RESTful API pozwala Twojemu serwerowi wysyłać polecenia do urządzeń biometrycznych — dodawanie/usuwanie użytkowników, pobieranie logów, rejestrację danych biometrycznych i sterowanie dostępem. Wysyłasz JSON metodą POST na adres URL endpointu z Twojego konta API Monitor.
RESTful API pozwala Twojemu serwerowi wysyłać polecenia do urządzeń biometrycznych — dodawanie/usuwanie użytkowników, pobieranie logów, rejestrację danych biometrycznych i sterowanie dostępem. Wysyłasz JSON metodą POST na adres URL endpointu z Twojego konta API Monitor.
P: Gdzie znajdę adres URL mojego endpointu RESTful?
Zaloguj się na swoje konto API Monitor. Znajdziesz tam adres URL endpointu RESTful i Service Tag ID (
Zaloguj się na swoje konto API Monitor. Znajdziesz tam adres URL endpointu RESTful i Service Tag ID (
stgid).P: Jakie jest opóźnienie poleceń RESTful?
Około 15 sekund. Biometric Gateway kolejkuje Twoje polecenie i dostarcza je do urządzenia przy jego następnym połączeniu (dla urządzeń online jest to niemal ciągłe).
Około 15 sekund. Biometric Gateway kolejkuje Twoje polecenie i dostarcza je do urządzenia przy jego następnym połączeniu (dla urządzeń online jest to niemal ciągłe).
P: Jaki jest maksymalny zakres dat dla LoadLog?
Zalecane maksimum to 30 dni na jedno żądanie. Dla większych zakresów wykonaj kilka żądań z kolejnymi oknami czasowymi.
Zalecane maksimum to 30 dni na jedno żądanie. Dla większych zakresów wykonaj kilka żądań z kolejnymi oknami czasowymi.
P: Czy mogę dodać użytkownika z wieloma szablonami biometrycznymi naraz?
Tak. Tablica Template przyjmuje wiele wpisów. Na przykład operacja #27 dodaje użytkownika z kartą + odciskiem palca + hasłem + twarzą + dłonią + UserPhoto w jednym żądaniu.
Tak. Tablica Template przyjmuje wiele wpisów. Na przykład operacja #27 dodaje użytkownika z kartą + odciskiem palca + hasłem + twarzą + dłonią + UserPhoto w jednym żądaniu.
P: Co się stanie, jeśli urządzenie będzie offline, gdy wyślę polecenie RESTful?
Biometric Gateway kolejkuje polecenie i dostarcza je automatycznie po ponownym połączeniu urządzenia. Jeśli urządzenie nie odpowie w wyznaczonym czasie, otrzymasz kod statusu
Biometric Gateway kolejkuje polecenie i dostarcza je automatycznie po ponownym połączeniu urządzenia. Jeśli urządzenie nie odpowie w wyznaczonym czasie, otrzymasz kod statusu
5 (Device Offline).P: Jak sprawdzić wynik polecenia?
Odpowiedzi RESTful zawierają pole
Odpowiedzi RESTful zawierają pole
StatusCode. Kod 0 oznacza sukces. Pełną listę kodów błędów i ich znaczenie znajdziesz w Kodach statusu odpowiedzi.P: Czy mogę zdalnie uruchomić rejestrację odcisku palca?
Tak. Operacja #35 EnrollFingerPrint uruchamia sesję rejestracji na urządzeniu. Użytkownik musi jednak być fizycznie obecny przy urządzeniu, aby zeskanować palec.
Tak. Operacja #35 EnrollFingerPrint uruchamia sesję rejestracji na urządzeniu. Użytkownik musi jednak być fizycznie obecny przy urządzeniu, aby zeskanować palec.
Bezpieczeństwo & sieć
P: Czy mogę używać HTTPS dla callbacków?
Tak. HTTPS z prawidłowym certyfikatem SSL na porcie 443 jest w pełni obsługiwany i zalecany w środowisku produkcyjnym.
Tak. HTTPS z prawidłowym certyfikatem SSL na porcie 443 jest w pełni obsługiwany i zalecany w środowisku produkcyjnym.
P: Czy szyfrowanie jest obowiązkowe?
Nie. Szyfrowanie AES-256 jest opcjonalne. Aby je włączyć, skonfiguruj Security Key w API Monitor. Po włączeniu wszystkie payloady JSON są szyfrowane/odszyfrowywane za pomocą AES/ECB/PKCS5PADDING z kodowaniem Base64.
Nie. Szyfrowanie AES-256 jest opcjonalne. Aby je włączyć, skonfiguruj Security Key w API Monitor. Po włączeniu wszystkie payloady JSON są szyfrowane/odszyfrowywane za pomocą AES/ECB/PKCS5PADDING z kodowaniem Base64.
P: Jak sprawdzić, czy callback naprawdę pochodzi od Cams?
Każdy callback zawiera pole
Każdy callback zawiera pole
AuthToken. Porównaj je z tokenem skonfigurowanym w Twoim API Monitor. Odrzucaj każde żądanie z niezgodnym tokenem.P: Które porty powinienem otworzyć?
Port
Port
80 (HTTP) lub 443 (HTTPS) dla środowiska produkcyjnego. Port 8123 jest dostępny wyłącznie do testów. Zobacz Obsługiwane porty.P: Jak testować lokalnie bez wdrażania na serwerze?
Użyj publicznego IP z przekierowaniem portów lub narzędzia do tunelowania, takiego jak ngrok. Przewodnik krok po kroku znajdziesz w Testowanie lokalne.
Użyj publicznego IP z przekierowaniem portów lub narzędzia do tunelowania, takiego jak ngrok. Przewodnik krok po kroku znajdziesz w Testowanie lokalne.
Dane & założenia projektowe
P: Jakiego formatu danych używa API?
Wszystkie żądania i odpowiedzi to surowy JSON w kodowaniu UTF-8. Użyj nagłówka
Wszystkie żądania i odpowiedzi to surowy JSON w kodowaniu UTF-8. Użyj nagłówka
Content-Type: application/json. Bez kodowania formularzowego.P: Jakiego formatu znacznika czasu używa API?
YYYY-MM-DD HH:mm:ss GMT +OFFSET (np. 2020-09-17 07:48:22 GMT +0530). Pole Time jest w UTC; lokalne znaczniki czasu urządzenia (takie jak LogTime, OperationTime) mogą używać innego przesunięcia strefy czasowej.P: Jak obsługiwać odbicia offline i dane wsteczne?
Zaprojektuj swoją aplikację tak, aby przyjmowała odbicia przychodzące w kolejności niechronologicznej. Gdy urządzenie było offline, po ponownym połączeniu prześle zbuforowane odbicia. Może być konieczne wsteczne zaktualizowanie statusu obecności (np. zmiana użytkownika wyświetlanego jako „nieobecny” na „obecny”).
Zaprojektuj swoją aplikację tak, aby przyjmowała odbicia przychodzące w kolejności niechronologicznej. Gdy urządzenie było offline, po ponownym połączeniu prześle zbuforowane odbicia. Może być konieczne wsteczne zaktualizowanie statusu obecności (np. zmiana użytkownika wyświetlanego jako „nieobecny” na „obecny”).
P: Jak określić WEJŚCIE/WYJŚCIE, gdy użytkownik korzysta z wielu urządzeń?
Posortuj wszystkie odbicia użytkownika według
Posortuj wszystkie odbicia użytkownika według
LogTime ze wszystkich urządzeń, a następnie zastosuj swoją logikę biznesową. Nie polegaj wyłącznie na polu Type (CheckIn/CheckOut) z jednego urządzenia, jeśli użytkownik odbija się na różnych urządzeniach.P: Czym jest OperationID i jak go używać?
Unikalny ciąg znaków identyfikujący każdą operację. W przypadku przychodzących callbacków generuje go Biometric Gateway. Dla wychodzących żądań RESTful powinieneś wygenerować unikalny identyfikator dla każdego żądania (UUID lub oparty na znaczniku czasu). Odpowiedź zwraca go z powrotem, dzięki czemu możesz skorelować pary żądanie/odpowiedź.
Unikalny ciąg znaków identyfikujący każdą operację. W przypadku przychodzących callbacków generuje go Biometric Gateway. Dla wychodzących żądań RESTful powinieneś wygenerować unikalny identyfikator dla każdego żądania (UUID lub oparty na znaczniku czasu). Odpowiedź zwraca go z powrotem, dzięki czemu możesz skorelować pary żądanie/odpowiedź.
P: Jak szablony biometryczne są przechowywane i przesyłane?
Dane biometryczne (odcisk palca, twarz, dłoń, zdjęcie użytkownika) są zakodowane w Base64 w polu
Dane biometryczne (odcisk palca, twarz, dłoń, zdjęcie użytkownika) są zakodowane w Base64 w polu
Data obiektu Template. Szablony odcisku palca i twarzy zawierają także Size (długość w bajtach) i Index (numer slotu). Numery kart i PIN-y są zwykłymi ciągami znaków.Cennik & licencjonowanie
P: Jak licencjonowane jest API?
Za każde urządzenie biometryczne. W pierwszym roku wymagane są Aktywacja API + licencja roczna. W kolejnych latach wymagane jest tylko odnowienie licencji rocznej. Zobacz Koszt API, aby poznać ceny.
Za każde urządzenie biometryczne. W pierwszym roku wymagane są Aktywacja API + licencja roczna. W kolejnych latach wymagane jest tylko odnowienie licencji rocznej. Zobacz Koszt API, aby poznać ceny.
P: Co się stanie, jeśli moja licencja API wygaśnie?
Komunikacja API dla tego urządzenia zostanie zatrzymana do czasu odnowienia licencji. Twoje istniejące dane nie zostaną naruszone, ale nowe callbacki ani polecenia RESTful nie będą przetwarzane.
Komunikacja API dla tego urządzenia zostanie zatrzymana do czasu odnowienia licencji. Twoje istniejące dane nie zostaną naruszone, ale nowe callbacki ani polecenia RESTful nie będą przetwarzane.
P: Czy jest opcja on-premise?
Tak. Protocol Engine Lite można zainstalować na własnym serwerze (Windows/Linux) w środowiskach wyłącznie LAN lub samodzielnie hostowanych. Szczegóły: sales@camsbiometrics.com.
Tak. Protocol Engine Lite można zainstalować na własnym serwerze (Windows/Linux) w środowiskach wyłącznie LAN lub samodzielnie hostowanych. Szczegóły: sales@camsbiometrics.com.
Informacje dodatkowe
SDK do biometrycznej rejestracji czasu pracy
Cams nie dostarcza tradycyjnego SDK. Wszystkie operacje korzystają ze standardowych Callback i RESTful API przez HTTP — bez instalowania bibliotek.
SDK nie jest potrzebne. Komunikacja odbywa się w całości przez Cams Protocol Engine, z użyciem Callback URL i endpointów RESTful HTTP.
Dzięki temu integracja z dowolną platformą webową jest prosta:
OpenERPERPNextZoho PeopleSAPTallyHRAPPOdooAplikacje webowe na zamówienie
Informacje dodatkowe
Koszt API
Licencje API są rozliczane za każde urządzenie biometryczne. Pierwszy rok = aktywacja + licencja; kolejne lata = tylko odnowienie licencji.
| Usługa | USD | Uwagi |
|---|---|---|
| Native Push — urządzenia Cams & zweryfikowane | ||
| Aktywacja API | $120 | Jednorazowo na urządzenie. |
| Roczna licencja API | $60 – $120 | Wymagane coroczne odnowienie. |
| Protocol Update (inne niż Cams) | $120 – $280 | Jednorazowo. Włącza protokół Cams na urządzeniach innych niż Cams. |
| Hybrid Push — ZKTeco, eSSL & wszystkie marki firm trzecich | ||
| Aktywacja API | $150 | Jednorazowo na urządzenie. |
| Roczna licencja API | $90 – $150 | Wymagane coroczne odnowienie. |
| Hybrid Connector (niezweryfikowane) | $150 – $300 | Jednorazowo. Wymagane dla niezweryfikowanych urządzeń w trybie Hybrid Push. |
| Sprzęt & inne | ||
| Sprzęt | $220 – $720 | Różni się w zależności od modelu. |
Protocol Engine Lite (on-premise) — dla środowisk wyłącznie LAN lub samodzielnie hostowanych. Koszt: $500–$10,000. Szczegóły uzyskasz w dziale sprzedaży.