Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/edgar2420/QrPermision/llms.txt

Use this file to discover all available pages before exploring further.

A permission in PermisosQR represents a single authorized exit event. It begins the moment an operator scans an available QR code and assigns it to an employee — recording the exit time, the employee’s name, and the maximum duration allowed. The permission stays open until the employee returns and the QR is scanned again. At that point the system calculates exactly how long the employee was absent, how much of that exceeded the allowed window, and whether they were compliant. Every field is immutable once the return is recorded, giving you a tamper-proof audit trail.

​
Enabling a Permission

To open a permission, the QR code must be in available status. The system locks the QR row with FOR UPDATE during the transaction to prevent race conditions. On success, the QR’s status immediately changes to active.
​
qrId
integer
required
The numeric ID of the QR code to activate. Must refer to a QR currently in available status.
​
receivedBy
string
required
Full name of the employee receiving the permission. Stored as a free-text string — no user account required.
​
allowedMinutes
integer
default:"15"
Maximum number of minutes the employee is permitted to be absent. Defaults to 15 if omitted or non-numeric.
​
notes
string
Optional free-text annotation (e.g., reason for exit, destination). Stored in the permission record and visible in history.
API reference 
curl -X POST http://localhost:4000/api/permissions/enable \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"qrId": 5, "receivedBy": "María García", "allowedMinutes": 30}'
Response — 201 Created 
{
  "success": true,
  "data": {
    "id": 88,
    "qr_id": 5,
    "enabled_by": 2,
    "received_by": "María García",
    "returned_by": null,
    "allowed_minutes": 30,
    "exit_time": "2024-06-15T09:12:00.000Z",
    "return_time": null,
    "time_used_minutes": null,
    "delay_minutes": null,
    "is_compliant": null,
    "notes": null,
    "created_at": "2024-06-15T09:12:00.000Z"
  }
}
If the QR is not in available status the API returns 400 with the message "El QR no está disponible. Estado actual: <current_status>".

​
Returning a Permission

When the employee returns, scanning the same QR (now active) triggers the return flow. The system finds the open permission record, computes all timing fields, writes them atomically, and resets the QR’s status to available. Required fields
FieldTypeNotes
qrIdintegerThe same QR ID that was enabled
notesstringOptional. Appended to the permission record
API reference 
curl -X POST http://localhost:4000/api/permissions/return \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"qrId": 5}'
Response — 200 OK 
{
  "success": true,
  "data": {
    "id": 88,
    "qr_id": 5,
    "enabled_by": 2,
    "received_by": "María García",
    "returned_by": null,
    "allowed_minutes": 30,
    "exit_time": "2024-06-15T09:12:00.000Z",
    "return_time": "2024-06-15T09:38:45.000Z",
    "time_used_minutes": "26.75",
    "delay_minutes": "0.00",
    "is_compliant": true,
    "notes": null,
    "created_at": "2024-06-15T09:12:00.000Z"
  }
}

​
Compliance Calculation

All three compliance fields are calculated in JavaScript on the server at the moment return_time is recorded and stored as DECIMAL(10, 2) columns. The calculation uses millisecond-precision timestamps: 
time_used_minutes = (return_time − exit_time) / 60000
delay_minutes     = MAX(0, time_used_minutes − allowed_minutes)
is_compliant      = delay_minutes <= 0
Both time_used_minutes and delay_minutes are rounded to two decimal places with parseFloat(...toFixed(2)) before storage. A permission where the employee returned exactly on time or early has delay_minutes = 0.00 and is_compliant = true. Example walkthrough 
exit_time      = 09:12:00
return_time    = 09:44:30
allowed        = 30 minutes

time_used      = (09:44:30 − 09:12:00) / 60000  →  32.50 min
delay          = MAX(0, 32.50 − 30)              →   2.50 min
is_compliant   = 2.50 <= 0                       →  false

​
Permission History

GET /api/permissions/history returns a paginated, reverse-chronological list of all permission records. Each row is enriched with the QR’s current status, the operator who enabled it, and (if already returned) the operator who recorded the return. Query parameters
ParameterTypeDescription
pageintegerPage number (default: 1)
limitintegerRecords per page (default: 20)
qrIdintegerFilter to a specific QR code
startDatestringISO 8601 date — filters created_at ≥
endDatestringISO 8601 date — the server appends 23:59:59
isCompliantbooleantrue or false
Role-based visibility: Operators with the admin_operator role can only see permissions they personally enabled — the enabledBy filter is injected automatically from the JWT. Super Admins (super_admin) receive the full, unfiltered history across all operators.
Example 
curl "http://localhost:4000/api/permissions/history?page=1&limit=20&isCompliant=false" \
  -H "Authorization: Bearer <token>"
Response shape 
{
  "success": true,
  "data": [ /* array of permission objects */ ],
  "total": 47,
  "page": 1,
  "limit": 20,
  "pages": 3
}

​
Deleting a Permission Record

Super Admins can permanently delete any permission record. If the deleted permission was still open (return_time IS NULL), the associated QR code is automatically reset to available so it can be used again. 
curl -X DELETE http://localhost:4000/api/permissions/88 \
  -H "Authorization: Bearer <token>"
Response — 200 OK 
{
  "success": true,
  "message": "Registro eliminado permanentemente"
}
Deletion is permanent and cannot be undone. Compliance statistics, operator reports, and dashboard averages all recalculate from the surviving records — removing a non-compliant permission will improve aggregate metrics. Use this action only to correct data-entry mistakes.

Build docs developers (and LLMs) love

Get started for freeTalk to us