Tworzenie odbiornika wywołań zwrotnych biometrii w Pythonie, Node.js i PHP
Odbiornik wywołań zwrotnych to niewielki fragment kodu, który zamienia każde skanowanie odcisku palca, twarzy lub karty w rekord w Twoim własnym systemie. Cams Biometrics Gateway wysyła każde zweryfikowane skanowanie na Twój serwer jako żądanie JSON, a serwer odpowiada, potwierdzając jego odbiór. Nie musisz pisać tego odbiornika od zera. Cams udostępnia AI Code Generator Prompts dla Pythona, Node.js i PHP: wklej jeden z nich do asystenta AI, takiego jak Claude lub ChatGPT, a otrzymasz kompletny, działający plik z odbiornikiem wywołań zwrotnych, klientem REST i interfejsem testowym. Ten poradnik wyjaśnia, co musi robić odbiornik, jak wygenerować go dla wybranego języka, jak go skonfigurować i jak przetestować przed uruchomieniem.
01 · Sześć zadań
Co musi robić odbiornik wywołań zwrotnych
Niezależnie od języka każdy odbiornik wywołań zwrotnych biometrii wykonuje te same sześć zadań. Są to również punkty, które należy sprawdzić w każdym wygenerowanym kodzie.
| Zadanie | Co oznacza | Dlaczego jest ważne |
|---|---|---|
| 1. Przyjmij żądanie | Odbierz żądanie HTTP/HTTPS POST z surowym ciałem JSON | W ten sposób Gateway dostarcza każde zdarzenie |
| 2. Zweryfikuj token | Sprawdź AuthToken względem oczekiwanego tokenu wywołania zwrotnego | Uniemożliwia innym osobom wysyłanie fałszywych danych o obecności na Twój adres URL |
| 3. Kieruj według typu zdarzenia | Sprawdź, który klucz znajduje się w RealTime, i odpowiednio go obsłuż | Nie każde wywołanie dotyczy rejestracji czasu; niektóre raportują zdjęcia lub zmiany użytkowników |
| 4. Pomijaj duplikaty | Użyj OperationID, aby ignorować zdarzenia, które już zapisano | Powtórne dostarczenie nigdy nie tworzy podwójnego rekordu |
| 5. Zapisz i zaloguj | Zapisz potrzebne pola i zaloguj każde wywołanie zwrotne | Tworzy rekord, z którego skorzysta Twój HRMS, system płac lub pulpit |
| 6. Odpowiedz done | Zwróć {“status”:”done”} z HTTP 200 | Informuje Gateway, że zdarzenie dotarło bezpiecznie |
02 · Poznaj swoje dane
Ładunek, który otrzymasz
Najczęstszym wywołaniem zwrotnym jest dziennik rejestracji, wysyłany za każdym razem, gdy ktoś się zeskanuje. Zapisz tę próbkę jako sample.json, ponieważ użyjesz jej później do przetestowania odbiornika.
|
Callback API, żądanie PunchLog wysyłane do odbiornika {
"RealTime": {
"OperationID": "9nu1wak5616p",
"LabelName": "Burj Khalifa",
"SerialNumber": "ZHM11xxxxxxxx",
"PunchLog": {
"Type": "CheckOut",
"Temperature": "36.8",
"FaceMask": false,
"InputType": "Fingerprint",
"UserId": "2",
"LogTime": "2020-09-17 07:48:22 GMT +0530"
},
"AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
"Time": "2020-09-17 04:19:03 GMT +0000"
}
}
|
Po obsłudze dowolnego wywołania zwrotnego odbiornik musi odpowiedzieć kodem HTTP 200 i dokładnie tym ciałem:
|
Callback API, odpowiedź, którą musi zwrócić odbiornik { "status": "done" } (HTTP 200)
|
Typy zdarzeń wywołania zwrotnego
Każde wywołanie zwrotne przychodzi wewnątrz obiektu RealTime. Odbiornik decyduje, co zrobić, sprawdzając, który z tych kluczy jest obecny:
| Klucz wewnątrz RealTime | Co raportuje |
|---|---|
| PunchLog | Skanowanie obecności: kto, wejście czy wyjście, kiedy i w jaki sposób |
| UserUpdated | Dane użytkownika zostały zaktualizowane na urządzeniu |
Dwa szczegóły, na które łapią się programiści
| Szczegół | Na co zwrócić uwagę |
|---|---|
| Klucz odpowiedzi jest pisany małymi literami | Zwróć status małymi literami z wartością done. Nie kopiuj wielkiej litery pola Status z odpowiedzi RESTful API |
| Format LogTime | LogTime wygląda tak: 2020-09-17 07:48:22 GMT +0530. To rzeczywisty czas skanowania z przesunięciem urządzenia. Przetwórz go z uwzględnieniem przesunięcia i użyj jako czasu obecności |
03 · Niech AI napisze kod
Wygeneruj swój odbiornik za pomocą AI Code Generator Prompts
Cams publikuje gotowy plik z promptem dla każdego obsługiwanego języka serwera. Każdy prompt zawiera podsumowanie specyfikacji Cams Web API 3.0 oraz jasne instrukcje, co należy zbudować. Wklejasz go do asystenta AI, a asystent generuje kompletną implementację w jednym pliku dla Twojego stosu technologicznego.
|
Pobierz plik z promptem Wybierz swój język w następnej sekcji i pobierz jego plik promptu .txt. |
|
|
Wklej go do asystenta AI Otwórz Claude, ChatGPT, Copilot lub dowolne narzędzie AI do kodowania i wklej całą treść promptu. |
|
|
Otrzymaj kompletny, działający plik AI generuje jeden plik. Ustaw wartości konfiguracji, wdróż go i uruchom. |
| Każdy wygenerowany plik zawiera | Co robi |
|---|---|
| Odbiornik wywołań zwrotnych | Odczytuje surowe ciało POST, weryfikuje AuthToken, kieruje według typu zdarzenia, zapisuje każde wywołanie w logu, przechowuje dzienniki rejestracji, zapisuje zdjęcia obecności i odpowiada done |
| Klient REST | Ogólna funkcja żądań oraz funkcje opakowujące dla wszystkich 27 operacji RESTful, takich jak AddUser, DeleteUser, ResendAllUser i UpdateAccessTime |
| Interfejs testowy HTML | Strona w przeglądarce z polami konfiguracji, listą rozwijaną operacji, edytorem JSON wypełnionym szablonami żądań, przeglądarką odpowiedzi i listą ostatnich wywołań zwrotnych |
|
Najpierw dokumentacja online Każdy prompt nakazuje AI przeczytać pełną dokumentację Cams Web API i traktować ją jako wiarygodne źródło operacji, schematów JSON, nazw pól i kodów odpowiedzi. Jeśli cokolwiek w podsumowaniu promptu jest sprzeczne z dokumentacją online, pierwszeństwo ma dokumentacja. |
04 · Wybierz swój język
Prompty dla Pythona, Node.js i PHP
Każdy prompt jest dostrojony tak, aby tworzyć idiomatyczny kod z minimalną liczbą zależności dla danego języka.
|
|
|
Prompty są także dostępne dla C# (.NET 8) z Minimal API, Javy z wbudowanym HttpServer i bez zależności, Go z net/http i wyłącznie biblioteką standardową oraz Ruby z Sinatra i SQLite. Wszystkie znajdziesz w sekcji AI Code Generator Prompts dokumentacji Cams Web API. Pobierz prompty.
05 · Trzy wartości do ustawienia
Konfiguracja wygenerowanego pliku
Wygenerowany plik ma blok konfiguracji na górze. W wersji PHP wygląda on tak, a pozostałe języki używają tych samych trzech wartości:
|
Blok konfiguracji, wersja PHP $CONFIG = [
'base_url' => 'https://YOUR_RESTFUL_ENDPOINT_URL',
'stgid' => 'YOUR_SERVICE_TAG_ID',
'auth_token' => 'YOUR_AUTH_TOKEN',
];
|
| Ustawienie | Co wpisać |
|---|---|
| base_url | Adres URL punktu końcowego RESTful z Twojego konta Cams API Monitor |
| stgid | Twój identyfikator Service Tag ID. |
| auth_token | Twój AuthToken, dołączany do wychodzących żądań RESTful i sprawdzany względem AuthToken w przychodzących żądaniach wywołań zwrotnych. |
|
Nie trzymaj tokenów we wspólnym kodzie Do szybkiego testu wpisanie wartości w bloku konfiguracji jest w porządku. Przed uruchomieniem produkcyjnym przenieś tokeny do zmiennych środowiskowych lub menedżera sekretów, aby nigdy nie trafiły do systemu kontroli wersji ani do wspólnego pliku. |
Po skonfigurowaniu i wdrożeniu pod publicznym adresem HTTPS ustaw ten adres jako Callback URL w Cams Gateway. Od tego momentu każde zweryfikowane skanowanie będzie docierać do odbiornika w czasie rzeczywistym.
06 · Przetestuj przed podłączeniem urządzeń
Testowanie odbiornika
Do przetestowania odbiornika wywołań zwrotnych nie potrzebujesz urządzenia biometrycznego. Wyślij mu przykładową próbkę samodzielnie za pomocą cURL, używając pasującego tokenu wywołań zwrotnych, i sprawdź odpowiedź.
|
Terminal, wysyłanie testowego wywołania zwrotnego # Zapisz przykładowy ładunek jako sample.json, a następnie wyślij go do odbiornika:
curl -X POST https://YOUR_SERVER/YOUR_CALLBACK_PATH \
-H "Content-Type: application/json" \
-d @sample.json
# Oczekiwana odpowiedź (HTTP 200):
# {"status":"done"}
|
| Test | Co wysłać | Oczekiwany wynik |
|---|---|---|
| Poprawne zdarzenie | sample.json z AuthToken ustawionym na Twój auth_token | HTTP 200 z done, a rejestracja zostaje zapisana |
| Zduplikowane zdarzenie | To samo żądanie po raz drugi | HTTP 200 z done, a drugi rekord nie zostaje zapisany |
| Zły token | sample.json z innym AuthToken | Odrzucone, a nic nie zostaje zapisane |
| Zdarzenie wejścia | sample.json z Type zmienionym na CheckIn | Zapisane jako wejście |
| Operacja RESTful | Użyj wbudowanego interfejsu testowego HTML, aby wysłać operację | Odpowiedź ze Status i StatusCode |
Wygenerowany interfejs testowy HTML ułatwia wypróbowanie strony RESTful: otwórz plik w przeglądarce, wybierz operację z listy rozwijanej, dostosuj wypełniony JSON i wyślij go. Przeglądarka ostatnich wywołań zwrotnych na tej samej stronie potwierdza, że testowe wywołania zostały odebrane.
07 · Lista kontrolna produkcji
Sprawdź przed uruchomieniem
Kod generowany przez AI to szybki i niezawodny punkt wyjścia, ale jak każdy kod powinien zostać sprawdzony, zanim zacznie obsługiwać prawdziwe dane pracowników.
| Punkt | Gotowe, gdy |
|---|---|
| Kod sprawdzony | Programista przeczytał wygenerowany plik i rozumie, co robi każda sekcja |
| Tylko HTTPS | Odbiornik jest dostępny wyłącznie przez HTTPS z ważnym certyfikatem |
| Tokeny chronione | AuthTokeny są przechowywane w zmiennych środowiskowych lub w menedżerze sekretów |
| Duplikaty obsłużone | OperationID jest zapisywany i sprawdzany, aby powtórne dostarczenia były ignorowane |
| Odpowiedni magazyn danych | Magazyn plików JSON wystarcza w małych instalacjach; większe wdrożenia mogą przejść na produkcyjną bazę danych |
| Interfejs testowy chroniony | Strona testowa HTML jest zabezpieczona hasłem lub wyłączona na publicznych serwerach |
| Zdjęcia obsługiwane ostrożnie | Zdjęcia obecności zapisane na dysku są objęte kontrolą dostępu i przechowywane tylko tak długo, jak jest to potrzebne |
| Monitoring na miejscu | Błędy i nietypowy wolumen wywołań zwrotnych są logowane, a Twój własny monitoring generuje alerty |
|
Reguły biznesowe trzymaj gdzie indziej Zadaniem odbiornika jest przyjąć, zweryfikować, skierować, zapisać i potwierdzić zdarzenie. Decyzje o tym, kto się spóźnił, obliczanie nadgodzin czy wysyłanie powiadomień należą do systemów, które czytają zapisane zdarzenia, takich jak HRMS, ERP lub narzędzia automatyzacji. Skupiony odbiornik łatwiej zabezpieczyć i utrzymać. |
Najczęściej zadawane pytania
|
Czy muszę sam pisać jakikolwiek kod? Zwykle nie. AI Code Generator Prompts tworzą kompletny, działający plik. Ustawiasz trzy wartości konfiguracji, wdrażasz go i testujesz. Programista powinien mimo to sprawdzić kod przed uruchomieniem produkcyjnym. |
|
Które asystenty AI działają z promptami? Każdy zdolny asystent do kodowania AI, w tym Claude, ChatGPT i Copilot. Wklej całą treść promptu za jednym razem, aby asystent miał pełną specyfikację. |
|
Gdzie znajdę adres URL punktu końcowego RESTful i Service Tag ID? Oba pochodzą z Twojego konta Cams API Monitor. Żądania RESTful są wysyłane na adres URL punktu końcowego z ?stgid= oraz Twoim Service Tag ID. |
|
Dlaczego odpowiadać done na zduplikowane zdarzenie? Ponieważ zdarzenie dotarło bezpiecznie, nawet jeśli już je zapisałeś. Odpowiedź done informuje Gateway, że nie musi wysyłać go ponownie. |
|
Czy mogę użyć języka, którego nie ma na liście? Tak. Odbiornik wywołań zwrotnych musi jedynie przyjmować HTTPS POST i zwracać JSON. Prompty to skrót, a to samo API działa z każdym językiem, który to potrafi. |
Podsumowanie: od promptu do rejestracji w czasie rzeczywistym w jedno popołudnie
Odbiornik wywołań zwrotnych biometrii jest niewielki, ale to on zamienia każde zweryfikowane skanowanie w dane na żywo dla Twojego HRMS, systemu płac, pulpitów i automatyzacji. Dzięki Cams AI Code Generator Prompts nie musisz budować go od pustej kartki. Pobierz prompt dla Pythona, Node.js lub PHP, wklej go do asystenta AI, ustaw trzy wartości i przetestuj. Następnie sprawdź, zabezpiecz i pozwól, by dane o obecności w czasie rzeczywistym zaczęły napływać.
Cams Biometrics Gateway dostarcza zdarzenia, których potrzebuje Twój odbiornik. Jego Callback API wysyła każde zweryfikowane skanowanie w czasie rzeczywistym, w jednym spójnym formacie JSON, z urządzeń ponad 15 marek, a jego RESTful API oferuje 27 operacji, które wygenerowany klient może wywoływać. Cała komunikacja odbywa się przez HTTP/HTTPS z walidacją tokenu uwierzytelniającego i opcjonalnym szyfrowaniem AES-256. Poznaj platformę na CamsBiometrics.com i przeczytaj pełną dokumentację Web API, w tym każdy AI Code Generator Prompt: Pobierz prompty.