Person Passes (/person_pass)
Person Passes
An administrator (admin, super_admin) can create person passes of any category and type via /person_pass, and cancel them.
Categories
| Category | Who | Required fields |
|---|---|---|
Guest (guest) | A resident’s visitor | Name, property, host resident |
Staff (staff) | An employee | Name; organization and position optional |
Contractor (contractor) | A contractor | Name; organization and position optional |
Types and validity
| Type | Validity |
|---|---|
one_time | Until the end of the current day (Moscow); burned on first entry |
temporary | A chosen date (≥ tomorrow, ≤ 31 Dec of the current year) |
permanent | Until 31 Dec of the current year |
Creation (admin)
/person_passFlow:
- Category — Guest / Staff / Contractor.
- Type — One-time / Temporary / Permanent.
- Full name — up to 200 characters.
- Expiration date — Temporary only.
- Organization, position — for Staff/Contractor (
/skipallowed). - Property, purpose — for Guest; then the host resident’s Telegram ID (required).
- Confirmation.
For a guest pass
hostUserIdis required: an administrator specifies the host resident; a resident is set to themselves automatically.
Access code
The 6-digit code is generated automatically. If you set a code manually and it is already taken by an active pass, the system generates a new one and warns: “The code was taken, a new one was generated.”
Verification
Use /verify_person — by 6-digit code or name.
Cancellation
Cancellation is done via the API POST /internal/person-passes/:id/cancel (internal route). Only an active pass can be cancelled; a used/expired/cancelled one returns a conflict.
Audit
All actions are recorded in the audit log: person_pass.created, person_pass.verified, person_pass.cancelled.