Makaram – HygieneTech IoT Sensor APIs

Production-Only Reminder

Base URL

Use https://hygienetech.tech/portal for every API action (`api?action=...`) and device endpoint (`/api/sensors/*`). No other host is supported for Makaram's handover.

Testing Scope

Before sharing deliverables, run your smoke tests directly against the production tenant (or a staging tenant routed through the same domain) to mirror the data contracts documented here.

Base URL & Authentication

Environment	Portal Base URL	Notes
Live / Production	`https://hygienetech.tech/portal`	Public tenant-facing environment. All API traffic must use this host.

Language Parameter

Every `api?action=...` call accepts lang=en or lang=ar. It decides which localized values you get back for bilingual JSON fields.

Portal / API Users

Header: Authorization: Bearer <userId> (numeric ID from the users table).
Fallback: append &token=<userId> to the query string.
Super admins can access all companies; other users are scoped to their company_id.

Device Tokens

Header: Authorization: Bearer <deviceToken>.
Issued automatically during provisioning or via the dashboard “Generate Token” action.
Handle HTTP 401 responses by requesting a fresh token from the admin team.

CSRF note: Only dashboard forms use CSRF tokens. The public API endpoints documented here do not require CSRF headers.

Provisioning Flow (Company Admin)

Authenticate: Log into the portal UI, capture the numeric user_id, and use it as your bearer token.
Create Device: Send the payload below to create a device tied to your company and optional maintenance item.
List Devices: Verify the device exists and inherits the correct thresholds.
Inspect Single Device: Confirm bilingual metadata and linkages.
Distribute Token: Share the returned api_token with the firmware team (store securely).

Create Device (POST api?action=createSensorDevice)

curl -X POST "https://hygienetech.tech/portal/api?action=createSensorDevice&lang=en" \
  -H "Authorization: Bearer 42" \
  -H "Content-Type: application/json" \
  -d '{
        "device_name_en": "Walk-in Freezer A",
        "device_name_ar": "فريزر تخزين أ",
        "device_type": "temperature",
        "temperature_min": -5,
        "temperature_max": 5,
        "temperature_unit": "celsius",
        "reading_frequency": 300,
        "offline_threshold": 900,
        "maintenance_item_id": 118,
        "mac_address": "BC-33-A1-77-09-E2",
        "location_en": "Central Kitchen",
        "location_ar": "المطبخ المركزي",
        "description_en": "Primary cold room sensor"
			}'

Success sample: responses/createSensorDevice-success.json. Validation error sample: responses/createSensorDevice-validation-error.json.

List Devices (GET api?action=getSensorDevices)

curl -X GET "https://hygienetech.tech/portal/api?action=getSensorDevices&lang=en" \
  -H "Authorization: Bearer 42"

Response snapshot: responses/getSensorDevices-success.json.

Fetch Single Device (GET api?action=getSensorDevice)

curl -X GET "https://hygienetech.tech/portal/api?action=getSensorDevice&device_id=214&lang=en" \
  -H "Authorization: Bearer 42"

Use the success (responses/getSensorDevice-success.json), not-found, and access-denied samples to validate edge cases.

Runtime Flow (Device Firmware)

Once a device has a valid token, hit the live endpoints below. Respect the configured reading_frequency and offline_threshold to stay inside rate limits.

1. Heartbeat

curl -X POST "https://hygienetech.tech/portal/api/sensors/heartbeat" \
  -H "Authorization: Bearer <DEVICE_TOKEN>"

Sample response: responses/heartbeat-success.json. Missing token: responses/common-missing-token.json.

2. Submit Reading

curl -X POST "https://hygienetech.tech/portal/api/sensors/reading" \
	-H "Authorization: Bearer <DEVICE_TOKEN>" \
	-H "Content-Type: application/json" \
	-d '{
        "reading_type": "temperature",
        "temperature": 3.8,
        "temperature_unit": "celsius",
        "humidity": 67,
        "battery_level": 82,
        "signal_strength": -71,
        "timestamp": "2025-11-18 09:30:05"
			}'

Success payload: responses/sensors-reading-success.json. Validation failure: responses/sensors-reading-validation-error.json.

3. Device Info

curl -X GET "https://hygienetech.tech/portal/api/sensors/device-info" \
  -H "Authorization: Bearer <DEVICE_TOKEN>"

See responses/sensors-device-info-success.json for the full configuration payload.

Live Response Library

Select any captured JSON to preview it inline. Files are mirrored inside this package under responses/.

Guide Library (HTML)

These expandable sections mirror the Markdown guides in /_dev-docs/iot-sensors/makaram/guides/. Use them offline without switching between formats.

Base URLs & Authentication

The HygieneTech IoT APIs are exposed only on the live tenant:

Environment	Portal Base URL	Notes
Live / Production	`https://hygienetech.tech/portal`	Public tenant-facing environment. All API traffic must use this host.

Language parameter: append lang=en or lang=ar to any api?action=... request to choose localized JSON fields.

Portal / API Users

Header: Authorization: Bearer <userId> (numeric user ID).
Fallback query string: &token=<userId>.
Super admins see every company; other users are scoped automatically.

Device Tokens

Header: Authorization: Bearer <deviceToken>.
Tokens come from provisioning responses or dashboard “Generate Token”.
On HTTP 401, request a new token from the admin team.

CSRF: Dashboard forms only. Public APIs do not expect CSRF tokens.

Rate limiting: Each device token defaults to 3600 calls/hour—respect reading_frequency and offline_threshold.

Provisioning Flow (Company Admin)

Authenticate in the portal UI, note the numeric user_id, and reuse it as a bearer token.
POST api?action=createSensorDevice with bilingual names, thresholds, and optional maintenance_item_id.
GET api?action=getSensorDevices to confirm statistics for the company.
GET api?action=getSensorDevice&device_id=... for the exact metadata, ensuring ownership enforcement works.
Distribute the returned api_token securely, or generate new tokens via the dashboard.

The canonical curl snippets are the same as in the section above; see also the JSON fixtures in responses/.

Runtime Flow (Device Firmware)

Heartbeat: POST /api/sensors/heartbeat every offline_threshold/2 seconds with the device token.
Reading submission: POST /api/sensors/reading including reading_type and temperature for temperature/hybrid devices, plus optional telemetry.
Configuration sync: GET /api/sensors/device-info periodically to pull latest min/max, frequency, and alert counts.
Error handling: 401 indicates expired/disabled tokens, 400 covers validation issues (see validation JSON), 500 should be escalated with captured payloads.

All endpoints must target https://hygienetech.tech/portal and include Authorization: Bearer <deviceToken>.

Pre-Share Checklist

✅ Company + maintenance assets exist in production.
✅ Device created with accurate thresholds and location data.
✅ Device token generated, stored securely, and validated against production endpoints.
✅ Heartbeat, reading, and device-info calls tested on https://hygienetech.tech/portal; responses match the files above.
✅ Alerts/cron behaviours observed via production dashboards/logs.

Note: This static site cannot run live API calls or spawn the PHP portal. Perform the real tests from an authenticated workstation against the production tenant, then refresh the JSON response files if anything changes.