Parking Permits

Integration Guide

This guide explains how to integrate with the parking permits API based on different permit configurations. Understanding these patterns will help you implement the correct flow for your specific use case.

Permit Types Overview

There are two main permit types, distinguished by the checkin_required field:

1. Standard Permits (checkin_required: false)

Standard permits have predefined registration numbers. Vehicles with these registration numbers are automatically allowed to park during the permit's valid period without any additional action.

• Registration numbers must be provided when creating the permit.
• The permit is immediately active for all specified vehicles.
• No check-in/check-out flow is needed.

2. Check-in Required Permits (checkin_required: true)

Check-in permits do not have predefined registration numbers. Instead, vehicles must be explicitly checked in before they are allowed to park.

• Do not provide registration_numbers when creating the permit.
• Use the check-in endpoint to register a vehicle when parking begins.
• Only one vehicle can be checked in at a time per permit.
• Update the check-in with an end_at time when parking ends, or leave it open-ended.

Time Validity Configuration

Permits can be configured with different time validity rules:

Full Validity (24/7)

When no days restrictions are specified, the permit is valid at all times within the start_at and end_at date range.

Day and Time Restrictions

When days are specified, the permit is only valid during those specific days and times. For example, a permit with Monday 08:00-18:00 is only valid on Mondays between those hours, even if the overall permit period spans several months.

• Multiple time slots can be defined for the same day.
• Time slots on the same day cannot overlap.
• Days can be specified as: mon-sun, monday-sunday, or 0-6 (where 0 = Sunday).

Common Integration Scenarios

Scenario A: Resident Parking

A resident has a parking permit valid 24/7 for their registered vehicle.

{
    "ticket_id": "resident-permit-123",
    "parking_lot_ids": [12],
    "start_at": "2024-01-01T00:00:00Z",
    "end_at": "2024-12-31T23:59:59Z",
    "registration_numbers": ["ABC123"],
    "checkin_required": false
}

Scenario B: Employee Parking with Work Hours

An employee can park Monday to Friday during work hours only.

{
    "ticket_id": "employee-permit-456",
    "parking_lot_ids": [12, 15],
    "start_at": "2024-01-01T00:00:00Z",
    "end_at": "2024-12-31T23:59:59Z",
    "registration_numbers": ["XYZ789"],
    "checkin_required": false,
    "days": [
        { "day": "monday", "start_at": "07:00", "end_at": "18:00" },
        { "day": "tuesday", "start_at": "07:00", "end_at": "18:00" },
        { "day": "wednesday", "start_at": "07:00", "end_at": "18:00" },
        { "day": "thursday", "start_at": "07:00", "end_at": "18:00" },
        { "day": "friday", "start_at": "07:00", "end_at": "18:00" }
    ]
}

Scenario C: Flexible Visitor Parking

A company has visitor parking spots. Visitors must check in when they arrive.

Step 1: Create the permit (once)

{
    "ticket_id": "visitor-permit-789",
    "parking_lot_ids": [12],
    "start_at": "2024-01-01T00:00:00Z",
    "end_at": "2024-12-31T23:59:59Z",
    "checkin_required": true
}

Step 2: Check in a visitor when they arrive

{
  "registration_number": "VISITOR1",
  "start_at": "2024-03-15T09:00:00Z",
  "end_at": "2024-03-15T17:00:00Z",
  "parking_lot_id": 12
}

Step 3: Update the check-in if the visitor leaves early or stays longer

{
  "registration_number": "VISITOR1",
  "end_at": "2024-03-15T15:30:00Z",
  "parking_lot_id": 12
}

Scenario D: Flexible Workplace with Day Restrictions

An employee can check in any vehicle, but only on their assigned days.

{
    "ticket_id": "flex-permit-321",
    "parking_lot_ids": [12],
    "start_at": "2024-01-01T00:00:00Z",
    "end_at": "2024-12-31T23:59:59Z",
    "checkin_required": true,
    "days": [
        { "day": "tuesday", "start_at": "07:00", "end_at": "19:00" },
        { "day": "thursday", "start_at": "07:00", "end_at": "19:00" }
    ]
}

Updating Permits

To update an existing permit, send a new POST request with the same ticket_id. The system will update the permit with the new values. Note that:

• Parking lots will be replaced with the new list.
• Days will be replaced with the new list.
• For standard permits, registration numbers will be synced (new ones added, removed ones deleted).

Deleting Permits

When a permit is deleted, all associated data (registration numbers, day restrictions, parking lot associations) is permanently removed.