ezeio2:apiref:scancode

scancode

Create, Read, Update or Delete records related to access control codes in the ezeio system.

Description

https://api.eze.io/v1/scancode/{serial}/{command}

The ezeio can store up to 324 scan code records. Each record has settings for when it is valid, limits on number of uses and what actions the code will perform when used.

The mechanics of how the code is entered/triggered in the ezeio is handled by a driver. The driver may interface with a keypad, card reader or other device, but this is not relevant to the scancode API. Please contact eze System for details.

The scancode API allows a third party system to manage the codes in the ezeio database. Currently the eze.io user portal do not allow access to the scancode data, but this is on our development roadmap.

The scan code record

Each scan code has the following properties:

`slot`	The record number in the ezeio (1-324)
`code`	The key/card scancode (max 10 characters, required when creating the record, optional on updates)
`name`	A plain-text name of the record (optional, default blank)
`userid`	An associated user id number (32 bit integer) (optional, default 0)
`notbefore`	An absolute time defining when the scancode if first valid (default 'now')
`notafter`	An absolute time defining when the scancode is no longer valid (default 'now'+30 days
`validweekdays`	An array of (7) flags (0/1) corresponding to Sunday-Saturday. Scancode is only valid if the corresponding flag is set. (default all '1')
`validfrom`	Time of day in HH:MM format. The scancode is only valid after this time. (optional, default 00:00)
`validto`	Time of day in HH:MM format. The scancode is only valid before this time. (optional, default 24:00)
`maxuse`	Max number of times the scancode can be used. (0-32767, optional, default 32767)
`maxlife`	Time in minutes from the first time the scancode is accepted until it will expire (0-32767, optional, default null)
`command`	The command code that will be reported to the driver when scancode is validated (0-255, optional, default 0)
`param1`	A parameter code that will be reported to the driver when scancode is validated (0-32767, optional, default 0)
`param2`	A parameter code that will be reported to the driver when scancode is validated (0-32767, optional, default 0)

URL Parameters

`serial`	ezeio serial number (XYZ123)
`command`	Command. See below

Possible commands:

To retrieve an existing record:

https://api.eze.io/v1/scancode/XYZ987/get[17]

The system will reply with a record similar to this (whitespace added for readability):

{
    "reqtime": "2024-10-21T21:01:54Z",
    "actions": [
        "Fetched 1 records"
    ],
    "scancodes": [
        {
            "slot": 17,
            "name": "Bob front gate access",
            "userid": 4711,
            "code": 131072,
            "notbefore": "2024-10-01 00:00:00",
            "notafter": "2025-12-31 23:59:59",
            "validweekdays": [
                0,
                1,
                1,
                1,
                1,
                1,
                0
            ],
            "validfrom": "07:30",
            "validto": "19:00",
            "maxuse": 400,
            "maxlife": null,
            "remainuse": 259,
            "usebefore": null,
            "command": 1,
            "param1": 0,
            "param2": 0
        }
    ],
    "status": "OK",
    "exec_time": 0.0208
}

In the example above, we see that Bob's scan code is 131072. When he enters/scans this code, and all time constraints are validated, the command code “1” will be sent to the driver, which we assume will trigger the gate to open.

If the scancode is used before the notbefore, or after the notafter, it will be ignored.

In the example above, the scancode will only be accepted on weekdays (not Saturdays or Sundays), and only between 07:30 and 19:00.

The maxuse setting will limit the number of times the code is accepted. The remaining count is reported in remainuse.

As an alternative to limiting the number of times a scancode can be used, the maxlife setting can be set to automatically expire the code a certain time after its first use. So for example, if we had set the maxlife in the example above to 1440 (number of minutes in 24h), Bob could start using the code any time between the notbefore and notafter times, but after first use he would only be able the use the code for 24 hours. Note that a scancode can either use the maxuse OR the maxlife feature (not both at the same time).

To retrieve an existing record:

https://api.eze.io/v1/scancode/XYZ987/getall

This will return all existing records. The format is identical to above, but with multiple records in the scancodes-array.

To create a new record or to update an existing record: set

https://api.eze.io/v1/scancode/XYZ987/set

This should be sent to the api as a 'POST' message, with a application/json body in the following format:

[
  {
    "slot": 17,
    "name": "Bob front gate access",
    "userid": 4711,
    "code": 131072,
    "notbefore": "2024-10-01 00:00:00",
    "notafter": "2025-12-31 23:59:59",
    "validweekdays": [
      0,
      1,
      1,
      1,
      1,
      1,
      0
    ],
    "validfrom": "07:30",
    "validto": "19:00",
    "maxuse": 400,
    "maxlife": null,
    "command": 1,
    "param1": 0,
    "param2": 0
  }
]

The slot property is mandatory, but all other properties are optional and will be populated with default values if the record is new, or left unchanged if the record exists. The system will reply with a status showing what action(s) were taken, like this:

{
  "reqtime": "2024-10-30T01:22:19Z",
  "actions": [
    "Updated #17"
  ],
  "status": "OK",
  "exec_time": 0.011
}

To delete a record: del

https://api.eze.io/v1/scancode/XYZ987/del[17]

Deletes record 17

To delete a record: delall

https://api.eze.io/v1/scancode/XYZ987/delall

Deletes all scancode records.