{
  "openapi": "3.0.3",
  "info": {
    "title": "EntryLuma API",
    "version": "1.2.0",
    "description": "Entry Device and CCTV integration reference checked against EntryLuma portal 2.2.43."
  },
  "servers": [
    {
      "url": "https://www.entryluma.com/api/v1/attendance"
    }
  ],
  "security": [
    {
      "DeviceToken": []
    }
  ],
  "paths": {
    "/webhook.php": {
      "post": {
        "operationId": "submitAttendance",
        "summary": "Record one normalised attendance event",
        "description": "128 KiB body cap. 200 accepted does not necessarily mean recorded or notification delivery. Always inspect status. Canonical schema is stricter than the legacy parser. No bulk arrays or inline photos.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AttendanceEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Processed or logged for review; inspect status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AttendanceResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid credential or inactive registration.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "POST required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Identity mismatch or branch state conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AttendanceResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds 131072 bytes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Temporary failure; retry same immutable event.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/heartbeat.php": {
      "post": {
        "operationId": "submitHeartbeat",
        "summary": "Report reader and connector health",
        "description": "8192-byte cap. Recommended 30–60 seconds; offline threshold 180 seconds.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Heartbeat"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Heartbeat accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Accepted"
                }
              }
            }
          },
          "400": {
            "description": "Invalid heartbeat or reader identity.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "POST required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body too large.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Storage unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/photo-policy.php": {
      "post": {
        "operationId": "getPhotoPolicy",
        "summary": "Obtain optional event-photo upload policy; does not record attendance",
        "description": "16 KiB cap. Face or fingerprint event with a stable 64-character lowercase hex ID. Eligible WhatsApp or configured attendance email may request photos. Use the returned upload URL and grant.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AttendanceEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Enabled policy or disabled reason.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhotoPolicy"
                }
              }
            }
          },
          "400": {
            "description": "Invalid device credential or photo request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhotoPolicy"
                }
              }
            }
          },
          "405": {
            "description": "POST required; body may be empty."
          },
          "413": {
            "description": "Body too large; body may be empty."
          }
        }
      }
    },
    "/connector-logo.php": {
      "get": {
        "operationId": "getRegisteredBranchLogo",
        "summary": "Retrieve the authenticated device branch logo",
        "description": "Use only when the photo policy supplies the same-origin logo URL. 2 MiB recommended client download bound.",
        "responses": {
          "200": {
            "description": "Registered branch logo image.",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "Invalid device credential or request; body may be empty."
          },
          "404": {
            "description": "No usable branch logo; body may be empty."
          }
        }
      },
      "servers": [
        {
          "url": "https://www.entryluma.com/dashboard",
          "description": "Use the same-origin logo_url returned by photo policy."
        }
      ]
    },
    "/photo-upload.php": {
      "post": {
        "operationId": "uploadAttendanceJpeg",
        "summary": "Upload an event JPEG using a photo-policy grant",
        "description": "Use the policy-provided HTTPS URL. EntryLuma-hosted storage accepts at most 2 MiB, 1920 pixels per side and 3 million pixels. Submit the resulting receipt with the original event.",
        "security": [
          {
            "PhotoGrant": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "image/jpeg": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Capture accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "receipt"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "receipt": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Grant, image or storage rejected."
          },
          "405": {
            "description": "Use POST."
          },
          "413": {
            "description": "JPEG exceeds 2 MiB."
          },
          "503": {
            "description": "Application unavailable."
          }
        }
      }
    },
    "/zones.php": {
      "post": {
        "operationId": "cameraZoneReport",
        "summary": "Read camera configuration or submit a CCTV event",
        "description": "Use a registered camera credential. configuration, open and resolve have a 4096-byte request limit. live_event can be up to 720000 bytes. An accepted live event can queue notifications according to applied camera delivery settings.",
        "security": [
          {
            "CameraToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "required": [
                      "api_version",
                      "operation"
                    ],
                    "properties": {
                      "api_version": {
                        "type": "integer",
                        "enum": [
                          1
                        ]
                      },
                      "operation": {
                        "type": "string",
                        "enum": [
                          "configuration"
                        ]
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "api_version",
                      "operation",
                      "revision",
                      "rule_key",
                      "episode_id",
                      "observed_at"
                    ],
                    "properties": {
                      "api_version": {
                        "type": "integer",
                        "enum": [
                          1
                        ]
                      },
                      "operation": {
                        "type": "string",
                        "enum": [
                          "open"
                        ]
                      },
                      "revision": {
                        "type": "integer"
                      },
                      "rule_key": {
                        "type": "string",
                        "pattern": "^[a-f0-9]{16}$"
                      },
                      "episode_id": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9_-]{16,64}$"
                      },
                      "observed_at": {
                        "type": "string",
                        "format": "date-time",
                        "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "api_version",
                      "operation",
                      "revision",
                      "rule_key",
                      "episode_id"
                    ],
                    "properties": {
                      "api_version": {
                        "type": "integer",
                        "enum": [
                          1
                        ]
                      },
                      "operation": {
                        "type": "string",
                        "enum": [
                          "resolve"
                        ]
                      },
                      "revision": {
                        "type": "integer"
                      },
                      "rule_key": {
                        "type": "string",
                        "pattern": "^[a-f0-9]{16}$"
                      },
                      "episode_id": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9_-]{16,64}$"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "api_version",
                      "operation",
                      "event_key",
                      "kind",
                      "occurred_at"
                    ],
                    "properties": {
                      "api_version": {
                        "type": "integer",
                        "enum": [
                          1
                        ]
                      },
                      "operation": {
                        "type": "string",
                        "enum": [
                          "live_event"
                        ]
                      },
                      "event_key": {
                        "type": "string",
                        "pattern": "^[a-f0-9]{32}$"
                      },
                      "kind": {
                        "type": "string",
                        "enum": [
                          "alert",
                          "resolution"
                        ]
                      },
                      "occurred_at": {
                        "type": "integer",
                        "format": "int64",
                        "description": "Unix epoch seconds. At receipt, at most one hour old or two minutes ahead."
                      },
                      "image": {
                        "type": "string",
                        "format": "byte",
                        "maxLength": 700000,
                        "description": "Optional raw base64 JPEG."
                      }
                    }
                  }
                ]
              },
              "examples": {
                "configuration": {
                  "value": {
                    "api_version": 1,
                    "operation": "configuration"
                  }
                },
                "open": {
                  "value": {
                    "api_version": 1,
                    "operation": "open",
                    "revision": 2,
                    "rule_key": "1234567890abcdef",
                    "episode_id": "example-episode-0001",
                    "observed_at": "2026-11-04T07:00:00Z"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Configuration, resolved episode or idempotent repeat. Configuration includes enabled, camera_id, revision, zones and rules."
          },
          "201": {
            "description": "New camera event or episode recorded. Confirm downstream notification delivery separately."
          },
          "400": {
            "description": "Invalid operation, JSON, timestamp or episode fields."
          },
          "401": {
            "description": "Invalid camera credential."
          },
          "403": {
            "description": "Reporting disabled."
          },
          "405": {
            "description": "Use POST."
          },
          "409": {
            "description": "Episode, revision, rule or schedule conflict."
          },
          "413": {
            "description": "Request too large."
          },
          "415": {
            "description": "JSON content type required."
          },
          "503": {
            "description": "Camera API unavailable."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "DeviceToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Device-Token",
        "description": "64 lowercase hex DEVICE credential; not the messaging API key."
      },
      "PhotoGrant": {
        "type": "http",
        "scheme": "bearer",
        "description": "Short-lived upload grant returned by photo policy."
      },
      "CameraToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Camera-Token",
        "description": "Camera-specific 64-character lowercase hex token."
      }
    },
    "schemas": {
      "AttendanceEvent": {
        "type": "object",
        "required": [
          "event_id",
          "device_serial",
          "person_id",
          "occurred_at",
          "event_type",
          "method",
          "verified"
        ],
        "properties": {
          "event_id": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "description": "Recommended canonical integrator ID. Stable across retries; required for photos."
          },
          "device_serial": {
            "type": "string",
            "minLength": 1,
            "description": "Exact registered reader serial. Mandatory integrator profile, even though legacy webhook parser tolerates omission."
          },
          "person_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "Branch Person ID; preserve leading zeros."
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time",
            "description": "Original event timestamp with timezone. Never refresh on retries."
          },
          "event_type": {
            "type": "string",
            "enum": [
              "check_in",
              "check_out",
              "break_in",
              "break_out",
              "overtime_in",
              "overtime_out"
            ]
          },
          "method": {
            "type": "string",
            "minLength": 1,
            "description": "Verified vendor method, e.g. fingerprint/face/card/pin. Captured-photo policy currently permits fingerprint and face only."
          },
          "verified": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "Canonical notification-producing event profile requires successful vendor authentication."
          },
          "macAddress": {
            "type": "string",
            "pattern": "^(?:[a-fA-F0-9]{2}:){5}[a-fA-F0-9]{2}$"
          },
          "photo_receipt": {
            "type": "string",
            "description": "Opaque receipt bound to this event; obtain before first attendance submission."
          }
        },
        "additionalProperties": false,
        "example": {
          "event_id": "8a3b9a1ce16a3e8ae2390b6e936f40bfca289c5dbe00884d8db7b3b50b32aa11",
          "device_serial": "ACME-READER-001",
          "macAddress": "02:00:00:00:00:01",
          "person_id": "00000001",
          "occurred_at": "2026-10-27T10:00:00+08:00",
          "event_type": "check_in",
          "method": "fingerprint",
          "verified": true
        }
      },
      "AttendanceResponse": {
        "type": "object",
        "required": [
          "accepted",
          "status"
        ],
        "properties": {
          "accepted": {
            "type": "boolean"
          },
          "status": {
            "type": "string",
            "enum": [
              "recorded",
              "duplicate",
              "historical",
              "unknown_person",
              "unverified",
              "unknown_type",
              "future_clock",
              "needs_adapter",
              "identity_mismatch",
              "branch_archived"
            ]
          },
          "event_id": {
            "type": "integer",
            "description": "Numeric server record ID, not submitted event ID."
          },
          "inbound_id": {
            "type": "integer"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        }
      },
      "Heartbeat": {
        "type": "object",
        "required": [
          "device_serial",
          "connector_version",
          "reader_state",
          "pending",
          "blocked",
          "review",
          "oldest_pending_age"
        ],
        "properties": {
          "device_serial": {
            "type": "string",
            "minLength": 1
          },
          "connector_version": {
            "type": "string",
            "pattern": "^[A-Za-z0-9._-]{1,30}$"
          },
          "reader_state": {
            "type": "string",
            "enum": [
              "checking",
              "connected",
              "disconnected",
              "authentication_error"
            ]
          },
          "pending": {
            "type": "integer",
            "minimum": 0,
            "maximum": 31536000
          },
          "blocked": {
            "type": "integer",
            "minimum": 0,
            "maximum": 31536000
          },
          "review": {
            "type": "integer",
            "minimum": 0,
            "maximum": 31536000
          },
          "oldest_pending_age": {
            "type": "integer",
            "minimum": 0,
            "maximum": 31536000
          },
          "installation_id": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "description": "Optional advisory identifier, not an activation key."
          }
        },
        "additionalProperties": false,
        "example": {
          "device_serial": "ACME-READER-001",
          "connector_version": "acme-1.0.0",
          "reader_state": "connected",
          "pending": 0,
          "blocked": 0,
          "review": 0,
          "oldest_pending_age": 0,
          "installation_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
        }
      },
      "Accepted": {
        "type": "object",
        "required": [
          "accepted"
        ],
        "properties": {
          "accepted": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        }
      },
      "PhotoPolicy": {
        "type": "object",
        "required": [
          "enabled"
        ],
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "reason": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "capture",
              "capture_logo"
            ]
          },
          "retention_limit": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000
          },
          "upload_url": {
            "type": "string",
            "format": "uri",
            "description": "Configured separate media service. Use approved HTTPS destination, no device token."
          },
          "grant": {
            "type": "string",
            "description": "Opaque short-lived media-upload grant; do not decrypt or log."
          },
          "logo_url": {
            "type": "string",
            "format": "uri",
            "nullable": true
          }
        }
      }
    }
  }
}
