@7365admin1/core 3.8.0 → 3.9.0

package/docs/hid-amico-postman-api.md

@@ -0,0 +1,614 @@
+# HID Amico Postman API Guide
+
+Use this guide to test the iService365 HID Amico backend with Postman.
+
+## 1. Postman Environment
+
+Create an environment, for example `HID`, with these variables:
+
+```text
+base_url=http://localhost:5001
+hid_base_url={{base_url}}/api/access-management/hid
+sid=
+siteId=
+readerId=
+identityId=
+```
+
+Local API-core usually runs on:
+
+```text
+http://localhost:5001
+```
+
+The HID module route is:
+
+```text
+{{base_url}}/api/access-management/hid
+```
+
+Do not use:
+
+```text
+/api/readers
+```
+
+That route does not exist.
+
+## 2. Login
+
+Request:
+
+```text
+POST {{base_url}}/api/auth
+```
+
+Body:
+
+```json
+{
+  "email": "<admin email>",
+  "password": "<admin password>"
+}
+```
+
+Expected response:
+
+```json
+{
+  "sid": "<session id>",
+  "user": "<user id>"
+}
+```
+
+Set environment variable:
+
+```text
+sid=<response.sid>
+```
+
+For protected HID APIs, use:
+
+```text
+Authorization: Bearer {{sid}}
+Content-Type: application/json
+```
+
+## 3. Create Reader
+
+Request:
+
+```text
+POST {{hid_base_url}}/readers
+```
+
+Headers:
+
+```text
+Authorization: Bearer {{sid}}
+Content-Type: application/json
+```
+
+Body:
+
+```json
+{
+  "site": "{{siteId}}",
+  "name": "Philippines HID Amico",
+  "location": "Lobby",
+  "baseUrl": "http://192.168.20.123",
+  "username": "<hid username>",
+  "password": "<hid password>",
+  "deviceId": "PH-HID-01",
+  "monitorPath": "api/access-management/hid/notifications",
+  "enabled": true,
+  "status": "active"
+}
+```
+
+Copy response:
+
+```text
+data._id -> readerId
+```
+
+Notes:
+
+- `password` is encrypted before saving.
+- Response will not return the password.
+- Response includes `passwordSet`.
+
+## 4. List Readers
+
+Request:
+
+```text
+GET {{hid_base_url}}/readers?site={{siteId}}&page=1&limit=10
+```
+
+Headers:
+
+```text
+Authorization: Bearer {{sid}}
+```
+
+## 5. Test Reader Connection
+
+Request:
+
+```text
+POST {{hid_base_url}}/readers/{{readerId}}/test
+```
+
+Headers:
+
+```text
+Authorization: Bearer {{sid}}
+```
+
+This tests:
+
+```text
+/hidlogin.fcgi
+/session_is_valid.fcgi
+/logout.fcgi
+```
+
+Expected success:
+
+```json
+{
+  "data": {
+    "valid": true,
+    "message": "HID Amico connection test succeeded."
+  }
+}
+```
+
+## 6. Load HID Users
+
+Request:
+
+```text
+POST {{hid_base_url}}/readers/{{readerId}}/objects
+```
+
+Headers:
+
+```text
+Authorization: Bearer {{sid}}
+Content-Type: application/json
+```
+
+Body:
+
+```json
+{
+  "operation": "load",
+  "object": "users",
+  "limit": 50,
+  "offset": 0
+}
+```
+
+Known response shape:
+
+```json
+{
+  "data": {
+    "users": [
+      {
+        "id": 3,
+        "name": "Harris",
+        "registration": "",
+        "image_timestamp": 1780498277,
+        "last_access": 1780505386
+      }
+    ]
+  }
+}
+```
+
+## 7. Load Access Logs
+
+Request:
+
+```text
+POST {{hid_base_url}}/readers/{{readerId}}/objects
+```
+
+Body:
+
+```json
+{
+  "operation": "load",
+  "object": "access_logs",
+  "limit": 50,
+  "offset": 0
+}
+```
+
+Known response shape:
+
+```json
+{
+  "data": {
+    "access_logs": [
+      {
+        "id": 1,
+        "time": 1780561438,
+        "event": 7,
+        "device_id": 14227560204339188,
+        "identifier_id": 1717658368,
+        "user_id": 3,
+        "portal_id": 1,
+        "identification_rule_id": 1,
+        "card_value": 0,
+        "qrcode_value": "",
+        "pin_value": "",
+        "confidence": 922,
+        "mask": 0,
+        "log_type_id": -1
+      }
+    ]
+  }
+}
+```
+
+`time` is Unix seconds. Example:
+
+```text
+1780561438 = 2026-06-04 16:23:58 Asia/Manila
+```
+
+## 8. Filter Access Logs
+
+Some HID firmware expects `where` to be nested by object/table name.
+
+Filter by HID `user_id`:
+
+```json
+{
+  "operation": "load",
+  "object": "access_logs",
+  "where": {
+    "access_logs": {
+      "user_id": 3
+    }
+  },
+  "limit": 20,
+  "offset": 0
+}
+```
+
+Filter by id:
+
+```json
+{
+  "operation": "load",
+  "object": "access_logs",
+  "where": {
+    "access_logs": {
+      "id": 1
+    }
+  },
+  "limit": 1
+}
+```
+
+If HID returns:
+
+```text
+Invalid object (object expected)
+```
+
+Check that `where` is nested correctly.
+
+## 9. Create Identity Mapping
+
+This maps a HID user/card to an iService365 record.
+
+Request:
+
+```text
+POST {{hid_base_url}}/readers/{{readerId}}/identities
+```
+
+Body:
+
+```json
+{
+  "hidUserId": "3",
+  "registration": "",
+  "cardNo": "",
+  "user": "<iService365 user ObjectId>",
+  "type": "staff",
+  "metadata": {
+    "source": "manual"
+  }
+}
+```
+
+At least one is required:
+
+```text
+hidUserId
+registration
+cardNo
+```
+
+Supported `type` values:
+
+```text
+resident
+staff
+contractor
+visitor
+unknown
+```
+
+Copy response:
+
+```text
+data._id -> identityId
+```
+
+## 10. List Identity Mappings
+
+Request:
+
+```text
+GET {{hid_base_url}}/readers/{{readerId}}/identities?page=1&limit=20
+```
+
+Filters:
+
+```text
+GET {{hid_base_url}}/readers/{{readerId}}/identities?type=staff
+GET {{hid_base_url}}/readers/{{readerId}}/identities?status=active
+GET {{hid_base_url}}/readers/{{readerId}}/identities?search=Harris
+```
+
+## 11. Update Identity Mapping
+
+Request:
+
+```text
+PATCH {{hid_base_url}}/identities/{{identityId}}
+```
+
+Body:
+
+```json
+{
+  "type": "staff",
+  "metadata": {
+    "note": "Updated from Postman"
+  }
+}
+```
+
+## 12. Delete Identity Mapping
+
+Request:
+
+```text
+DELETE {{hid_base_url}}/identities/{{identityId}}
+```
+
+This marks the mapping as deleted.
+
+## 13. Backend Event Logs
+
+Request:
+
+```text
+GET {{hid_base_url}}/readers/{{readerId}}/logs?page=1&limit=20
+```
+
+Filter by event type:
+
+```text
+GET {{hid_base_url}}/readers/{{readerId}}/logs?page=1&limit=20&type=objects_load
+```
+
+These are iService365 backend logs, not the same as raw HID `access_logs`.
+
+## 14. Notification Callback
+
+This endpoint is for HID reader callbacks and does not require auth.
+
+Request:
+
+```text
+POST {{hid_base_url}}/notifications/{{readerId}}/new_user_identified
+```
+
+Example test body:
+
+```json
+{
+  "user_id": 3,
+  "name": "Harris",
+  "time": 1780561438
+}
+```
+
+The backend tries to resolve identity using:
+
+```text
+hidUserId
+registration
+cardNo
+```
+
+If no mapping exists, the event is still saved with:
+
+```json
+{
+  "identity": null,
+  "identityLookup": {
+    "hidUserId": 3
+  }
+}
+```
+
+## 15. Sync Reader
+
+Request:
+
+```text
+POST {{hid_base_url}}/readers/{{readerId}}/sync
+```
+
+Body:
+
+```json
+{
+  "objects": [
+    {
+      "object": "users",
+      "values": []
+    }
+  ]
+}
+```
+
+Short form:
+
+```json
+{
+  "users": [],
+  "cards": [],
+  "qrcodes": [],
+  "pins": []
+}
+```
+
+Current sync is a convenience wrapper around HID `create_objects.fcgi`.
+
+## 16. Execute Actions
+
+Request:
+
+```text
+POST {{hid_base_url}}/readers/{{readerId}}/actions
+```
+
+Body:
+
+```json
+{
+  "actions": [
+    {
+      "action": "<hid action name>",
+      "parameters": {}
+    }
+  ]
+}
+```
+
+Action payload depends on HID firmware support.
+
+## 17. Door State
+
+Request:
+
+```text
+GET {{hid_base_url}}/readers/{{readerId}}/door-state
+```
+
+Observed response from the tested reader:
+
+```json
+{
+  "error": "Invalid command: door_state",
+  "code": 1
+}
+```
+
+This means the current firmware may not support `door_state.fcgi`. Treat this API as optional.
+
+## 18. Delete Reader
+
+Request:
+
+```text
+DELETE {{hid_base_url}}/readers/{{readerId}}
+```
+
+This marks the reader as deleted and disables it.
+
+## Troubleshooting
+
+### `Cannot GET /api/readers`
+
+Use:
+
+```text
+/api/access-management/hid/readers
+```
+
+### `ECONNREFUSED 127.0.0.1:5001`
+
+API-core is not running on port `5001`, or Postman `base_url` is wrong.
+
+### `"site" must be a string`
+
+The endpoint expects `site` in query/body. Check whether you are calling the correct endpoint and passing the correct payload.
+
+### `"user" must only contain hexadecimal characters`
+
+Fields such as `user`, `person`, `member`, and `visitor` must be MongoDB ObjectIds. Do not put HID user names or numeric HID ids into these fields.
+
+Use HID ids in:
+
+```text
+hidUserId
+registration
+cardNo
+```
+
+### `Invalid object (object expected)`
+
+For HID `load_objects.fcgi`, try nested `where`:
+
+```json
+{
+  "where": {
+    "access_logs": {
+      "user_id": 3
+    }
+  }
+}
+```
+
+### `Invalid table events`
+
+The tested reader does not expose an `events` table through `load_objects.fcgi`. Use:
+
+```text
+access_logs
+```
+
+### `Invalid command: door_state`
+
+The current reader/firmware may not support `door_state.fcgi`.
+
+### `401 Unauthorized`
+
+Login again and set:
+
+```text
+Authorization: Bearer {{sid}}
+```
+
+### HID web portal works but API fails
+
+Possible causes:
+
+- Wrong HID object name.
+- Wrong `where` shape.
+- Unsupported firmware endpoint.
+- Backend cannot reach reader through VPN/network.
+- Wrong HID username/password saved in reader config.