openapi: 3.1.0
info:
  title: AutoNexa API
  version: "1.0.0"
  summary: REST API for UAE car rental and leasing companies.
  description: |
    The AutoNexa API gives server-to-server access to one rental company's fleet, customers, bookings,
    rental agreements, invoices, tolls and fines, plus a Fines Feed and GPS telematics ingest.

    * Every API key belongs to one company; all data returned and written is scoped to that company.
    * Authenticate with `Authorization: Bearer <key>` or `x-api-key: <key>`.
    * Lists return `{ data, next_cursor }`. Pass `limit` (1-200, default 50) and `cursor` (or `page`).
    * Errors return `{ error: { code, message } }`.
    * Rate limit: 120 requests per minute per key (`X-RateLimit-*` headers, `Retry-After` on 429).
    * API access requires the Scale plan (or an active trial).
  contact:
    name: AutoNexa
    url: https://autonexa.ae/developers
servers:
  - url: https://platform.autonexa.ae/functions/v1/api
    description: AutoNexa API
security:
  - bearerAuth: []
  - apiKeyHeader: []
tags:
  - name: Vehicles
  - name: Availability
  - name: Customers
  - name: Bookings
  - name: Contracts
  - name: Invoices
  - name: Charges
    description: Tolls, parking and traffic fines (Fines Feed).
  - name: Telematics
paths:
  /v1:
    get:
      tags: [Vehicles]
      summary: Who am I
      description: Returns the organisation and scopes of the calling key.
      operationId: whoami
      responses:
        "200":
          description: Key info
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      name: { type: string }
                      version: { type: string }
                      org_id: { type: string, format: uuid }
                      scopes: { type: array, items: { $ref: "#/components/schemas/Scope" } }
        "401": { $ref: "#/components/responses/Unauthorized" }
  /v1/vehicles:
    get:
      tags: [Vehicles]
      summary: List vehicles
      operationId: listVehicles
      x-scope: read
      parameters:
        - { name: status, in: query, schema: { $ref: "#/components/schemas/VehicleStatus" } }
        - { name: category_id, in: query, schema: { type: string, format: uuid } }
        - { name: branch_id, in: query, schema: { type: string, format: uuid } }
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Vehicles
          headers: { $ref: "#/components/headers/RateLimitSet" }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/VehicleList" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /v1/vehicles/{id}:
    get:
      tags: [Vehicles]
      summary: Get a vehicle
      operationId: getVehicle
      x-scope: read
      parameters: [{ $ref: "#/components/parameters/Id" }]
      responses:
        "200":
          description: Vehicle
          content:
            application/json:
              schema: { type: object, properties: { data: { $ref: "#/components/schemas/Vehicle" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
  /v1/availability:
    get:
      tags: [Availability]
      summary: Vehicles available in a period
      description: |
        Vehicles in status `available` or `reserved` with no overlapping confirmed / checked-out booking and no
        overlapping active or pending-signature contract. Also returns a per-category summary.
      operationId: getAvailability
      x-scope: read
      parameters:
        - { name: from, in: query, required: true, schema: { type: string, format: date-time } }
        - { name: to, in: query, required: true, schema: { type: string, format: date-time } }
        - { name: category_id, in: query, schema: { type: string, format: uuid } }
        - { name: branch_id, in: query, schema: { type: string, format: uuid } }
      responses:
        "200":
          description: Available vehicles
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      allOf:
                        - $ref: "#/components/schemas/Vehicle"
                        - type: object
                          properties:
                            category: { $ref: "#/components/schemas/CategoryRates" }
                  summary:
                    type: array
                    items:
                      type: object
                      properties:
                        category_id: { type: [string, "null"], format: uuid }
                        name: { type: [string, "null"] }
                        available: { type: integer }
                        daily_rate: { type: [number, "null"] }
                  from: { type: string, format: date-time }
                  to: { type: string, format: date-time }
                  next_cursor: { type: "null" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
  /v1/customers:
    get:
      tags: [Customers]
      summary: List customers
      operationId: listCustomers
      x-scope: read
      parameters:
        - { name: q, in: query, description: Search name, email, phone or Emirates ID, schema: { type: string } }
        - { name: updated_since, in: query, schema: { type: string, format: date-time } }
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Customers
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: "#/components/schemas/Customer" } }
                  next_cursor: { $ref: "#/components/schemas/NextCursor" }
        "401": { $ref: "#/components/responses/Unauthorized" }
    post:
      tags: [Customers]
      summary: Create a customer
      operationId: createCustomer
      x-scope: write
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CustomerInput" }
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema: { type: object, properties: { data: { $ref: "#/components/schemas/Customer" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /v1/customers/{id}:
    get:
      tags: [Customers]
      summary: Get a customer
      operationId: getCustomer
      x-scope: read
      parameters: [{ $ref: "#/components/parameters/Id" }]
      responses:
        "200":
          description: Customer
          content:
            application/json:
              schema: { type: object, properties: { data: { $ref: "#/components/schemas/Customer" } } }
        "404": { $ref: "#/components/responses/NotFound" }
  /v1/bookings:
    get:
      tags: [Bookings]
      summary: List bookings
      operationId: listBookings
      x-scope: read
      parameters:
        - { name: status, in: query, schema: { $ref: "#/components/schemas/BookingStatus" } }
        - { name: customer_id, in: query, schema: { type: string, format: uuid } }
        - { name: from, in: query, description: Pick-up at or after, schema: { type: string, format: date-time } }
        - { name: to, in: query, description: Pick-up before, schema: { type: string, format: date-time } }
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Bookings
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: "#/components/schemas/Booking" } }
                  next_cursor: { $ref: "#/components/schemas/NextCursor" }
        "401": { $ref: "#/components/responses/Unauthorized" }
    post:
      tags: [Bookings]
      summary: Create a booking
      description: |
        `customer_id`, `category_id`, `vehicle_id` and branches must belong to your company. Without `customer_id`,
        `guest_name` and `guest_phone` are required. `rate`, `deposit_amount` and `quoted_total` default to the
        category's rates. The booking number is assigned automatically.
      operationId: createBooking
      x-scope: write
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/BookingInput" }
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema: { type: object, properties: { data: { $ref: "#/components/schemas/Booking" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /v1/bookings/{id}:
    get:
      tags: [Bookings]
      summary: Get a booking
      operationId: getBooking
      x-scope: read
      parameters: [{ $ref: "#/components/parameters/Id" }]
      responses:
        "200":
          description: Booking
          content:
            application/json:
              schema: { type: object, properties: { data: { $ref: "#/components/schemas/Booking" } } }
        "404": { $ref: "#/components/responses/NotFound" }
    patch:
      tags: [Bookings]
      summary: Update booking status
      operationId: updateBooking
      x-scope: write
      parameters: [{ $ref: "#/components/parameters/Id" }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [status]
              properties:
                status: { type: string, enum: [confirmed, cancelled, no_show] }
      responses:
        "200":
          description: Updated
          content:
            application/json:
              schema: { type: object, properties: { data: { $ref: "#/components/schemas/Booking" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "404": { $ref: "#/components/responses/NotFound" }
  /v1/contracts:
    get:
      tags: [Contracts]
      summary: List rental agreements
      operationId: listContracts
      x-scope: read
      parameters:
        - { name: status, in: query, schema: { $ref: "#/components/schemas/ContractStatus" } }
        - { name: customer_id, in: query, schema: { type: string, format: uuid } }
        - { name: vehicle_id, in: query, schema: { type: string, format: uuid } }
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Contracts
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: "#/components/schemas/Contract" } }
                  next_cursor: { $ref: "#/components/schemas/NextCursor" }
  /v1/contracts/{id}:
    get:
      tags: [Contracts]
      summary: Get a rental agreement
      operationId: getContract
      x-scope: read
      parameters: [{ $ref: "#/components/parameters/Id" }]
      responses:
        "200":
          description: Contract
          content:
            application/json:
              schema: { type: object, properties: { data: { $ref: "#/components/schemas/Contract" } } }
        "404": { $ref: "#/components/responses/NotFound" }
  /v1/invoices:
    get:
      tags: [Invoices]
      summary: List invoices
      operationId: listInvoices
      x-scope: read
      parameters:
        - { name: status, in: query, schema: { $ref: "#/components/schemas/InvoiceStatus" } }
        - { name: customer_id, in: query, schema: { type: string, format: uuid } }
        - { name: contract_id, in: query, schema: { type: string, format: uuid } }
        - { name: from, in: query, description: Issue date on or after, schema: { type: string, format: date } }
        - { name: to, in: query, description: Issue date on or before, schema: { type: string, format: date } }
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Invoices
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: "#/components/schemas/Invoice" } }
                  next_cursor: { $ref: "#/components/schemas/NextCursor" }
  /v1/invoices/{id}:
    get:
      tags: [Invoices]
      summary: Get an invoice
      operationId: getInvoice
      x-scope: read
      parameters: [{ $ref: "#/components/parameters/Id" }]
      responses:
        "200":
          description: Invoice
          content:
            application/json:
              schema: { type: object, properties: { data: { $ref: "#/components/schemas/Invoice" } } }
        "404": { $ref: "#/components/responses/NotFound" }
  /v1/charges:
    get:
      tags: [Charges]
      summary: List tolls, fines and charges
      operationId: listCharges
      x-scope: read
      parameters:
        - { name: status, in: query, schema: { $ref: "#/components/schemas/ChargeStatus" } }
        - { name: type, in: query, schema: { $ref: "#/components/schemas/ChargeType" } }
        - { name: from, in: query, description: occurred_at on or after, schema: { type: string, format: date-time } }
        - { name: to, in: query, description: occurred_at before, schema: { type: string, format: date-time } }
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Charges
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: "#/components/schemas/Charge" } }
                  next_cursor: { $ref: "#/components/schemas/NextCursor" }
    post:
      tags: [Charges]
      summary: Fines Feed - push charges
      description: |
        Push up to 500 tolls / fines per request. Each item is matched to a vehicle by plate and to the rental
        agreement active at `occurred_at` (vehicle swaps included). Items with an existing (`type`, `external_ref`)
        are reported as `duplicate` and not stored again, so retries are safe. Invalid items are reported per item;
        the request only fails with 400 if every item is invalid.
      operationId: pushCharges
      x-scope: "fines:write"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: array
                  maxItems: 500
                  items: { $ref: "#/components/schemas/ChargeInput" }
                - type: object
                  required: [charges]
                  properties:
                    charges: { type: array, maxItems: 500, items: { $ref: "#/components/schemas/ChargeInput" } }
      responses:
        "200":
          description: Per-item results
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required: [index, status]
                      properties:
                        index: { type: integer }
                        external_ref: { type: [string, "null"] }
                        type: { type: [string, "null"] }
                        status: { type: string, enum: [matched, unmatched, duplicate, invalid] }
                        id: { type: string, format: uuid }
                        vehicle_id: { type: [string, "null"], format: uuid }
                        contract_id: { type: [string, "null"], format: uuid }
                        customer_id: { type: [string, "null"], format: uuid }
                        error: { type: string }
                  summary:
                    type: object
                    properties:
                      matched: { type: integer }
                      unmatched: { type: integer }
                      duplicate: { type: integer }
                      invalid: { type: integer }
        "400": { $ref: "#/components/responses/BadRequest" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /v1/charges/{id}:
    get:
      tags: [Charges]
      summary: Get a charge
      operationId: getCharge
      x-scope: read
      parameters: [{ $ref: "#/components/parameters/Id" }]
      responses:
        "200":
          description: Charge
          content:
            application/json:
              schema: { type: object, properties: { data: { $ref: "#/components/schemas/Charge" } } }
        "404": { $ref: "#/components/responses/NotFound" }
  /v1/telematics/positions:
    post:
      tags: [Telematics]
      summary: Push GPS positions
      description: The device must be registered in AutoNexa (by IMEI / identifier) and assigned to a vehicle.
      operationId: pushPositions
      x-scope: "telematics:write"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [device_identifier, points]
              properties:
                device_identifier: { type: string, maxLength: 100 }
                points:
                  type: array
                  minItems: 1
                  maxItems: 500
                  items: { $ref: "#/components/schemas/PositionPoint" }
      responses:
        "202":
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      device_id: { type: string, format: uuid }
                      vehicle_id: { type: string, format: uuid }
                      accepted: { type: integer }
        "400": { $ref: "#/components/responses/BadRequest" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
webhooks:
  event:
    post:
      summary: AutoNexa event
      description: |
        Sent to each active endpoint subscribed to the event (`*`, `<group>.*` or the exact name).
        `X-AutoNexa-Signature: sha256=<hex>` is HMAC-SHA256 of the raw body with the endpoint's signing secret.
        Events: booking.created, booking.<status>, contract.created, contract.<status>, invoice.issued, invoice.paid,
        invoice.void, payment.succeeded, payment.failed, charge.created, charge.<status>, telematics.alert,
        cheque.<status>, ping (test).
      parameters:
        - { name: X-AutoNexa-Event, in: header, required: true, schema: { type: string } }
        - { name: X-AutoNexa-Signature, in: header, required: true, schema: { type: string, pattern: "^sha256=[0-9a-f]{64}$" } }
      requestBody:
        content:
          application/json:
            schema: { $ref: "#/components/schemas/WebhookEvent" }
      responses:
        "200": { description: Return any 2xx quickly to acknowledge. }
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer, bearerFormat: "cf_live_..." }
    apiKeyHeader: { type: apiKey, in: header, name: x-api-key }
  parameters:
    Id: { name: id, in: path, required: true, schema: { type: string, format: uuid } }
    Limit: { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 50 } }
    Cursor: { name: cursor, in: query, description: next_cursor from the previous page, schema: { type: string } }
    Page: { name: page, in: query, description: 1-based page number (alternative to cursor), schema: { type: integer, minimum: 1 } }
  headers:
    RateLimitSet:
      X-RateLimit-Limit: { schema: { type: integer } }
      X-RateLimit-Remaining: { schema: { type: integer } }
      X-RateLimit-Reset: { description: Unix seconds, schema: { type: integer } }
  responses:
    BadRequest: { description: Invalid request, content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } } }
    Unauthorized: { description: Missing / invalid / revoked key, content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } } }
    Forbidden: { description: Key lacks the required scope, content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } } }
    NotFound: { description: Not found, content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } } }
    Conflict: { description: Conflict, content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } } }
    RateLimited:
      description: Too many requests
      headers:
        Retry-After: { schema: { type: integer } }
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
  schemas:
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code: { type: string, examples: [invalid_parameter, unauthorized, insufficient_scope, not_found, rate_limited, plan_required] }
            message: { type: string }
    NextCursor: { type: [string, "null"] }
    Scope: { type: string, enum: [read, write, "fines:write", "telematics:write"] }
    Emirate: { type: string, enum: [DXB, AUH, SHJ, AJM, UAQ, RAK, FUJ] }
    VehicleStatus: { type: string, enum: [available, reserved, on_rent, in_service, out_of_service, sold] }
    BookingStatus: { type: string, enum: [enquiry, confirmed, checked_out, returned, closed, cancelled, no_show] }
    BookingSource: { type: string, enum: [walk_in, online, phone, whatsapp, corporate, aggregator] }
    ContractStatus: { type: string, enum: [draft, pending_signature, active, returned, closed, void] }
    InvoiceStatus: { type: string, enum: [draft, issued, partially_paid, paid, void, overdue] }
    ChargeType: { type: string, enum: [salik, darb, parkin, mawaqif, police_fine, rta_fine, damage, fuel, excess_km, late_return, cleaning, other] }
    ChargeStatus: { type: string, enum: [unmatched, matched, invoiced, charged, disputed, written_off, paid_by_company] }
    Position:
      type: [object, "null"]
      properties:
        lat: { type: number }
        lng: { type: number }
        speed_kmh: { type: [number, "null"] }
        heading: { type: [integer, "null"] }
        ignition: { type: [boolean, "null"] }
        recorded_at: { type: [string, "null"], format: date-time }
    Vehicle:
      type: object
      properties:
        id: { type: string, format: uuid }
        branch_id: { type: [string, "null"], format: uuid }
        category_id: { type: [string, "null"], format: uuid }
        plate_emirate: { $ref: "#/components/schemas/Emirate" }
        plate_code: { type: [string, "null"] }
        plate_number: { type: string }
        make: { type: string }
        model: { type: string }
        year: { type: [integer, "null"] }
        color: { type: [string, "null"] }
        vin: { type: [string, "null"] }
        status: { $ref: "#/components/schemas/VehicleStatus" }
        odometer: { type: integer }
        fuel_level: { type: integer }
        salik_tag: { type: [string, "null"] }
        mulkiya_expiry: { type: [string, "null"], format: date }
        insurance_expiry: { type: [string, "null"], format: date }
        next_service_km: { type: [integer, "null"] }
        next_service_date: { type: [string, "null"], format: date }
        gps_odometer_km: { type: [number, "null"] }
        last_position: { $ref: "#/components/schemas/Position" }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
    VehicleList:
      type: object
      properties:
        data: { type: array, items: { $ref: "#/components/schemas/Vehicle" } }
        next_cursor: { $ref: "#/components/schemas/NextCursor" }
    CategoryRates:
      type: [object, "null"]
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        name_ar: { type: [string, "null"] }
        daily_rate: { type: number }
        weekly_rate: { type: [number, "null"] }
        monthly_rate: { type: [number, "null"] }
        deposit_amount: { type: number }
    Customer:
      type: object
      properties:
        id: { type: string, format: uuid }
        type: { type: string, enum: [individual, corporate] }
        full_name: { type: string }
        company_name: { type: [string, "null"] }
        company_trn: { type: [string, "null"] }
        email: { type: [string, "null"] }
        phone: { type: [string, "null"] }
        whatsapp: { type: [string, "null"] }
        nationality: { type: [string, "null"] }
        date_of_birth: { type: [string, "null"], format: date }
        is_resident: { type: [boolean, "null"] }
        emirates_id: { type: [string, "null"] }
        emirates_id_expiry: { type: [string, "null"], format: date }
        passport_number: { type: [string, "null"] }
        passport_expiry: { type: [string, "null"], format: date }
        licence_number: { type: [string, "null"] }
        licence_country: { type: [string, "null"] }
        licence_expiry: { type: [string, "null"], format: date }
        address: { type: [string, "null"] }
        blacklisted: { type: boolean }
        credit_limit: { type: [number, "null"] }
        notes: { type: [string, "null"] }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
    CustomerInput:
      type: object
      required: [full_name]
      properties:
        type: { type: string, enum: [individual, corporate], default: individual }
        full_name: { type: string, maxLength: 200 }
        company_name: { type: string }
        company_trn: { type: string, maxLength: 30 }
        email: { type: string, format: email }
        phone: { type: string, maxLength: 30 }
        whatsapp: { type: string, maxLength: 30 }
        nationality: { type: string }
        date_of_birth: { type: string, format: date }
        is_resident: { type: boolean, default: true }
        emirates_id: { type: string, examples: ["784-1990-1234567-1"] }
        emirates_id_expiry: { type: string, format: date }
        passport_number: { type: string }
        passport_expiry: { type: string, format: date }
        licence_number: { type: string }
        licence_country: { type: string, minLength: 2, maxLength: 2, default: AE }
        licence_expiry: { type: string, format: date }
        address: { type: string }
        notes: { type: string, maxLength: 2000 }
    Booking:
      type: object
      properties:
        id: { type: string, format: uuid }
        booking_number: { type: string }
        customer_id: { type: [string, "null"], format: uuid }
        category_id: { type: [string, "null"], format: uuid }
        vehicle_id: { type: [string, "null"], format: uuid }
        pickup_branch_id: { type: [string, "null"], format: uuid }
        return_branch_id: { type: [string, "null"], format: uuid }
        pickup_at: { type: string, format: date-time }
        return_at: { type: string, format: date-time }
        delivery_address: { type: [string, "null"] }
        collection_address: { type: [string, "null"] }
        status: { $ref: "#/components/schemas/BookingStatus" }
        source: { $ref: "#/components/schemas/BookingSource" }
        rate_type: { type: string, enum: [daily, weekly, monthly] }
        rate: { type: number }
        extras: { type: array, items: { type: object } }
        discount: { type: number }
        quoted_total: { type: number }
        deposit_amount: { type: number }
        deposit_free: { type: boolean }
        guest_name: { type: [string, "null"] }
        guest_email: { type: [string, "null"] }
        guest_phone: { type: [string, "null"] }
        notes: { type: [string, "null"] }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
    BookingInput:
      type: object
      required: [category_id, pickup_at, return_at]
      properties:
        customer_id: { type: string, format: uuid }
        guest_name: { type: string }
        guest_phone: { type: string }
        guest_email: { type: string, format: email }
        category_id: { type: string, format: uuid }
        vehicle_id: { type: string, format: uuid }
        pickup_branch_id: { type: string, format: uuid }
        return_branch_id: { type: string, format: uuid }
        pickup_at: { type: string, format: date-time }
        return_at: { type: string, format: date-time }
        delivery_address: { type: string }
        collection_address: { type: string }
        status: { type: string, enum: [enquiry, confirmed], default: confirmed }
        source: { $ref: "#/components/schemas/BookingSource" }
        rate_type: { type: string, enum: [daily, weekly, monthly], default: daily }
        rate: { type: number, description: Defaults to the category rate }
        discount: { type: number, default: 0 }
        quoted_total: { type: number, description: Defaults to rate x periods - discount }
        deposit_amount: { type: number, description: Defaults to the category deposit }
        notes: { type: string }
    Contract:
      type: object
      properties:
        id: { type: string, format: uuid }
        contract_number: { type: string }
        booking_id: { type: [string, "null"], format: uuid }
        customer_id: { type: string, format: uuid }
        vehicle_id: { type: string, format: uuid }
        additional_drivers: { type: array, items: { type: object } }
        status: { $ref: "#/components/schemas/ContractStatus" }
        language: { type: string }
        start_at: { type: string, format: date-time }
        expected_end_at: { type: string, format: date-time }
        actual_end_at: { type: [string, "null"], format: date-time }
        rate_type: { type: string }
        rate: { type: number }
        km_allowance: { type: [integer, "null"] }
        excess_km_rate: { type: [number, "null"] }
        odometer_out: { type: [integer, "null"] }
        odometer_in: { type: [integer, "null"] }
        fuel_out: { type: [integer, "null"] }
        fuel_in: { type: [integer, "null"] }
        deposit_amount: { type: [number, "null"] }
        signed_at: { type: [string, "null"], format: date-time }
        tars_status: { type: string }
        tars_contract_no: { type: [string, "null"] }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
    InvoiceLine:
      type: object
      properties:
        id: { type: string, format: uuid }
        description: { type: string }
        category: { type: string }
        quantity: { type: number }
        unit_price: { type: number }
        vat_rate: { type: number }
        line_subtotal: { type: number }
        line_vat: { type: number }
        traffic_charge_id: { type: [string, "null"], format: uuid }
    Invoice:
      type: object
      properties:
        id: { type: string, format: uuid }
        invoice_number: { type: string }
        customer_id: { type: [string, "null"], format: uuid }
        contract_id: { type: [string, "null"], format: uuid }
        lease_id: { type: [string, "null"], format: uuid }
        status: { $ref: "#/components/schemas/InvoiceStatus" }
        issue_date: { type: string, format: date }
        due_date: { type: [string, "null"], format: date }
        currency: { type: string, default: AED }
        subtotal: { type: number }
        vat_amount: { type: number }
        total: { type: number }
        amount_paid: { type: number }
        notes: { type: [string, "null"] }
        created_at: { type: string, format: date-time }
        invoice_lines: { type: array, items: { $ref: "#/components/schemas/InvoiceLine" } }
    Charge:
      type: object
      properties:
        id: { type: string, format: uuid }
        type: { $ref: "#/components/schemas/ChargeType" }
        source: { type: string }
        external_ref: { type: [string, "null"] }
        plate_emirate: { oneOf: [{ $ref: "#/components/schemas/Emirate" }, { type: "null" }] }
        plate_code: { type: [string, "null"] }
        plate_number: { type: string }
        vehicle_id: { type: [string, "null"], format: uuid }
        occurred_at: { type: string, format: date-time }
        location: { type: [string, "null"] }
        description: { type: [string, "null"] }
        amount: { type: number }
        admin_fee: { type: number }
        black_points: { type: [integer, "null"] }
        status: { $ref: "#/components/schemas/ChargeStatus" }
        contract_id: { type: [string, "null"], format: uuid }
        customer_id: { type: [string, "null"], format: uuid }
        invoice_id: { type: [string, "null"], format: uuid }
        matched_at: { type: [string, "null"], format: date-time }
        created_at: { type: string, format: date-time }
    ChargeInput:
      type: object
      required: [type, external_ref, plate_number, occurred_at, amount]
      properties:
        type: { $ref: "#/components/schemas/ChargeType" }
        external_ref: { type: string, maxLength: 120, description: Ticket / trip id from the issuer (dedupe key with type) }
        plate_emirate: { $ref: "#/components/schemas/Emirate" }
        plate_code: { type: string, maxLength: 10 }
        plate_number: { type: string, maxLength: 12 }
        occurred_at: { type: string, format: date-time }
        amount: { type: number, minimum: 0 }
        location: { type: string, maxLength: 300 }
        description: { type: string, maxLength: 1000 }
        black_points: { type: integer, minimum: 0, maximum: 24 }
    PositionPoint:
      type: object
      required: [lat, lng]
      properties:
        lat: { type: number, minimum: -90, maximum: 90 }
        lng: { type: number, minimum: -180, maximum: 180 }
        ts: { type: string, format: date-time, description: Defaults to now }
        speed: { type: number, description: km/h }
        heading: { type: number, minimum: 0, maximum: 360 }
        odometer: { type: number, description: km }
        ignition: { type: boolean }
        fuel: { type: number, minimum: 0, maximum: 100, description: percent }
    WebhookEvent:
      type: object
      required: [id, event, created_at, data]
      properties:
        id: { type: string, format: uuid }
        event: { type: string, examples: [booking.created, payment.succeeded, charge.matched] }
        created_at: { type: string, format: date-time }
        data: { type: object, description: The full record that changed (booking, contract, invoice, payment, charge, alert or cheque). }
