Native End-User Integration

In this pattern your app renders the parking experience and your backend calls the Izix Public API on behalf of each user. Izix keeps the rules, capacity and gate hardware.

Profiles and rights are created first, see Profile Provisioning.

Architecture and authentication

flowchart LR
    APP["Your mobile or web app"] -- "your own session" --> BE["Your backend"]
    BE -- "Bearer token (client credentials)" --> API["Izix Public API"]
    API --> GATE["Izix gate hardware"]

• Your backend authenticates with client credentials and identifies the user on each call with profile_external_reference (or profile_id).
• Never ship the client secret in a mobile app. All Izix calls go through your backend, which checks that the signed-in user only acts on their own profile.
• Scopes: access-rights.read, openable-accesses.read, reservations.read, reservations.create, reservations.delete, reservations.available-periods.read, reservations.cost.read, open-gate.action.

Home screen: what can this user do now

GET /openable-accesses?filters[profile_external_reference]={ref} returns, per access right:

• the parking (parking_lot) and its gates, each with specifications: the id used to open, the direction, and the geofencing settings force_geolocation and max_opening_distance
• current_availability (available spots, occupancy, capacity)
• availability_status (available, plus a reason when not)
• allowed_entrance_methods (for example the plates accepted)
• ongoing_reservation_session when the user is currently parked or holds an active reservation

One call is usually enough to draw the home screen.

Booking a spot

sequenceDiagram
    autonumber
    actor U as User
    participant APP as Your app and backend
    participant API as Izix Public API
    APP->>API: GET /access-rights?filters[profile_external_references][]={ref}
    API-->>APP: Rights with access_policy, planning_period, timetable
    U->>APP: Picks a parking and a time slot
    APP->>API: GET /available-periods (optional, to show free slots)
    APP->>API: POST /reservations (dry_run: true)
    API-->>APP: 200 if bookable, 400 or 422 with reason otherwise
    U->>APP: Confirms
    APP->>API: POST /reservations (dry_run: false)
    API-->>APP: 201 reservation
    APP-->>U: Confirmation

Rules to respect:

• from and to are aligned on quarter hours (00, 15, 30, 45).
• from cannot be in the past (5 minutes of tolerance).
• The booking window is limited by the right's planning_period.
• A dry run answers 200 when the reservation could be created, and 400 (for example invalid_access_right) or 422 with a code and detail otherwise. A real booking answers 201 with reservation_id.
• When the parking is paid, estimate the price with GET /reservations/cost?access_policy_id=...&valid_from=...&valid_to=..., and read the cost of existing reservations with GET /reservations?include_costs=true.

See Reservation management and Availability checks for details.

Cancelling

DELETE /reservations/{reservationId}. A reservation that has already started cannot be deleted: its end time is set to now instead. A reservation that is already over answers 400 cannot_delete_past_reservation.

Opening the gate

sequenceDiagram
    autonumber
    actor U as User
    participant APP as Your app and backend
    participant API as Izix Public API
    participant GATE as Izix gate hardware
    APP->>API: GET /openable-accesses
    API-->>APP: Gates and their specification IDs
    U->>APP: Taps "Open" next to a gate
    APP->>APP: Read device location if force_geolocation is true
    APP->>API: POST /gates/{gateSpecificationId}/open (access_policy_id, profile, latitude, longitude)
    API->>API: Check rights, and position when geofencing is forced
    API->>GATE: Open command
    GATE-->>API: Executed
    API-->>APP: 204, or 4xx with reason
    APP-->>U: Gate open, or explanation

Geofencing is configured per gate specification. When force_geolocation is true, send latitude and longitude; an opening attempted further than max_opening_distance from the gate is refused with 400 business_error.

When the user's plate is registered on the profile, ANPR cameras open the barrier without any call from your app. Remote opening remains useful for unregistered plates or as a fallback.

Error handling

Errors return code, error, status, detail and event_id. Show detail to the user when relevant, and quote event_id when contacting Izix support. See Error Handling.