Tenant API Service

POST Create Pricing Zone

Creates a new pricing zone with geographical boundaries.

POST/pricing-zones

Description: Creates a pricing zone with name, radius, and coordinate points for geographical pricing rules.

curl -X POST "{{baseUrl}}/api/v1/pricing-zones" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{
    "name": "Test Zone",
    "radius": 20,
    "points": [
      {"lat": 35.850035911668925, "lng": 14.494603872299194}
    ]
  }'

GET Get All Pricing Zones

Retrieves all pricing zones in the system.

GET/pricing-zones

Description: Lists all pricing zones with their geographical boundaries and configuration.

curl -X GET "{{baseUrl}}/api/v1/pricing-zones" \
  -H "X-Api-Key: {{api-key}}"

GET Get Pricing Zone by ID

Retrieves a specific pricing zone by its ID.

GET/pricing-zones/{id}

Description: Gets detailed information about a specific pricing zone including all coordinate points.

curl -X GET "{{baseUrl}}/api/v1/pricing-zones/123" \
  -H "X-Api-Key: {{api-key}}"

PUT Update Pricing Zone

Updates an existing pricing zone configuration.

PUT/pricing-zones/{id}

Description: Modifies pricing zone details including name, radius, and coordinate points.

curl -X PUT "{{baseUrl}}/api/v1/pricing-zones/123" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{
    "name": "Updated Test Pricing Zone",
    "radius": 1500,
    "points": [
      {"lat": 35.9000, "lng": 14.5150, "address": "Updated Valletta, Malta"},
      {"lat": 35.9050, "lng": 14.5200, "address": "Updated Sliema, Malta"}
    ]
  }'

DELETE Delete Pricing Zone

Removes a pricing zone from the system.

DELETE/pricing-zones/{id}

Description: Permanently deletes a pricing zone by its ID.

curl -X DELETE "{{baseUrl}}/api/v1/pricing-zones/123" \
  -H "X-Api-Key: {{api-key}}"

POST Create Pricing Rule

Creates a new pricing rule with comprehensive criteria and settings.

POST/pricing-rules

Description: Creates a pricing rule with booking criteria, payment types, vehicle types, and time-based conditions.

curl -X POST "{{baseUrl}}/api/v1/pricing-rules" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{
    "name": "Test Pricing Rule",
    "description": "Example description",
    "status": "DRAFT",
    "type": "GENERAL",
    "quota": {
      "type": "COMMON",
      "value": 40.0,
      "unit": "FIXED"
    },
    "criteria": {
      "booking": {
        "sources": ["WEB"],
        "types": ["ASAP"]
      },
      "payment": {
        "paymentTypes": ["CASH"]
      },
      "vehicle": {
        "types": ["cab"]
      },
      "dateRange": {
        "dateFrom": "2025-11-05",
        "dateTo": "2025-11-06",
        "daysOfWeek": ["FRIDAY"],
        "isExtendedWeekend": false,
        "timeFrom": "00:30",
        "timeTo": "00:40"
      },
      "zonesIds": [1],
      "pointsIds": [2]
    },
    "settings": {
      "waitingTime": {
        "waitTimeGracePeriod": 2
      },
      "pricePerMinute": {
        "isFinalPriceRecalculationEnabled": false
      },
      "surgeMap": {
        "showRule": true,
        "showRuleValue": true
      }
    }
  }'

GET Get All Pricing Rules

Retrieves all pricing rules in the system.

GET/pricing-rules

Description: Lists all pricing rules with their criteria and settings.

curl -X GET "{{baseUrl}}/api/v1/pricing-rules" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{}'

GET Get Pricing Rule by ID

Retrieves a specific pricing rule by its ID.

GET/pricing-rules/{ruleId}

Description: Gets detailed information about a specific pricing rule including all criteria and settings.

curl -X GET "{{baseUrl}}/api/v1/pricing-rules/123" \
  -H "X-Api-Key: {{api-key}}"

PUT Update Pricing Rule

Updates an existing pricing rule configuration.

PUT/pricing-rules/{ruleId}

Description: Modifies pricing rule details including criteria, quota, and settings.

curl -X PUT "{{baseUrl}}/api/v1/pricing-rules/123" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{
    "name": "Updated Pricing Rule",
    "description": "Updated test pricing rule",
    "status": "DRAFT",
    "type": "GENERAL",
    "quota": {
      "type": "COMMON",
      "value": 7.5,
      "unit": "PERCENT"
    },
    "criteria": {
      "booking": {
        "sources": ["WEB"],
        "types": ["ASAP"]
      },
      "payment": {
        "paymentTypes": ["CASH"]
      },
      "vehicle": {
        "types": ["cab"]
      },
      "dateRange": {
        "dateFrom": "2025-11-05",
        "dateTo": "2025-11-06",
        "daysOfWeek": ["FRIDAY"],
        "isExtendedWeekend": false,
        "timeFrom": "00:30",
        "timeTo": "00:40"
      },
      "zonesIds": [1, 2],
      "pointsIds": [1, 2]
    }
  }'

DELETE Delete Pricing Rule

Removes a pricing rule from the system.

DELETE/pricing-rules/{ruleId}

Description: Permanently deletes a pricing rule by its ID.

curl -X DELETE "{{baseUrl}}/api/v1/pricing-rules/123" \
  -H "X-Api-Key: {{api-key}}"

POST Create Customer

Creates a new customer with personal information.

POST/customers

Description: Creates a customer with first name, last name, email, mobile phone, and locale information.

curl -X POST "{{baseUrl}}/api/v1/customers" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{
    "firstName": "Bruce",
    "lastName": "Wayne",
    "email": "bruce.wayne@waynenterprice.com",
    "mobilePhone": "+35612345678",
    "locale": "en_US"
  }'

GET Get Customer by ID

Retrieves a specific customer by their ID.

GET/customers/{id}

Description: Gets detailed information about a specific customer including all personal details.

curl -X GET "{{baseUrl}}/api/v1/customers/123e4567-e89b-12d3-a456-426614174000" \
  -H "X-Api-Key: {{api-key}}"

GET Get All Customers

Retrieves all customers with pagination support.

GET/customers

Description: Lists all customers with pagination and optional mobile phone filtering.

curl -X GET "{{baseUrl}}/api/v1/customers" \
  -H "X-Api-Key: {{api-key}}"

GET Get Customers with Pagination

Retrieves customers with specific page and size parameters.

GET/customers?page={page}&size={size}

Description: Lists customers with pagination control for page number and page size.

curl -X GET "{{baseUrl}}/api/v1/customers?page=0&size=10" \
  -H "X-Api-Key: {{api-key}}"

GET Search Customers by Mobile Phone

Searches for customers using their mobile phone number.

GET/customers?mobilePhone={phoneNumber}

Description: Finds customers by their mobile phone number.

curl -X GET "{{baseUrl}}/api/v1/customers?mobilePhone=%2B35612345678" \
  -H "X-Api-Key: {{api-key}}"

GET Get All Vehicle Types

Retrieves all available vehicle types with their details.

GET/vehicle-types

Description: Lists all vehicle types with capacity, icons, pricing information, and pagination support.

curl -X GET "{{baseUrl}}/api/v1/vehicle-types" \
  -H "X-Api-Key: {{api-key}}"

GET Get Vehicle Types with Pagination

Retrieves vehicle types with pagination parameters.

GET/vehicle-types?page={page}&size={size}

Description: Lists vehicle types with pagination control for better data management.

curl -X GET "{{baseUrl}}/api/v1/vehicle-types?page=0&size=10" \
  -H "X-Api-Key: {{api-key}}"

GET Get All Vehicle Locations

Retrieves all vehicle locations with filtering by status.

GET/vehicle-locations

Description: Lists vehicle locations with status filtering (IDLE, JOB_AWAITING, ACCEPTED, PICKED_UP, SHIFT_ENDED) and pagination.

curl -X GET "{{baseUrl}}/api/v1/vehicle-locations?status=IDLE&page=0&size=25" \
  -H "X-Api-Key: {{api-key}}"

GET Get Vehicle Location by Number Plate

Retrieves a specific vehicle location by its number plate.

GET/vehicle-locations/{numberPlate}

Description: Gets detailed location information for a specific vehicle including coordinates, status, and shift details.

curl -X GET "{{baseUrl}}/api/v1/vehicle-locations/ABC123" \
  -H "X-Api-Key: {{api-key}}"

GET Get Waiting Times

Retrieves waiting time information for specific coordinates.

GET/waiting-times

Description: Gets waiting time estimates based on latitude and longitude coordinates.

curl -X GET "{{baseUrl}}/api/v1/waiting-times?lat=35.8997&lng=14.5146" \
  -H "X-Api-Key: {{api-key}}"

GET Get ETA by Booking ID

Fetches the estimated time of arrival (ETA) for a specific booking.

GET/eta?bookingId={bookingId}

Description: Retrieves ETA and distance associated with a booking using its unique ID.

curl -X GET "{{baseUrl}}/api/v1/eta?bookingId=123" \
  -H "X-Api-Key: {{api-key}}"

POST Create Quotation

Creates a new quotation for trip pricing estimation.

POST/quotations

Description: Creates a quotation with customer ID, booking channel, payment type, and trip waypoints to get pricing estimates.

curl -X POST "{{baseUrl}}/api/v1/quotations" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{
    "customerId": "123e4567-e89b-12d3-a456-426614174000",
    "bookingChannel": "MOBILE_APP",
    "paymentType": "ON_ACCOUNT",
    "pickUpTime": "2024-01-01T10:00:00Z",
    "tripWaypoints": [
      {
        "lat": 35.8519165,
        "lng": 14.4863253,
        "address": "Malta International Airport, Malta"
      },
      {
        "lat": 35.922935,
        "lng": 14.486780,
        "address": "eCabs, St. Julian, Malta"
      }
    ]
  }'

GET Get Quotation by ID

Retrieves a specific quotation by its ID.

GET/quotations/{id}

Description: Gets detailed quotation information including pricing for different vehicle types.

curl -X GET "{{baseUrl}}/api/v1/quotations/123" \
  -H "X-Api-Key: {{api-key}}"

POST Create Booking

Creates a new booking with comprehensive trip details.

POST/bookings

Description: Creates a booking with customer information, trip waypoints, vehicle type, passenger details, pricing, and payment information.

curl -X POST "{{baseUrl}}/api/v1/bookings" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{
    "customerId": "123e4567-e89b-12d3-a456-426614174000",
    "b2bAccount": null,
    "pickupTime": "2024-01-01T10:00:00Z",
    "asap": false,
    "quotationId": 123,
    "bookingChannel": "CALL",
    "vehicleType": {
      "code": "van"
    },
    "tripWaypoints": [
      {
        "orderNumber": 1,
        "location": {
          "lat": 35.8997,
          "lng": 14.5146,
          "address": "Valletta, Malta"
        },
        "type": "PICKUP",
        "passengers": null,
        "lastStop": false
      },
      {
        "orderNumber": 2,
        "location": {
          "lat": 35.9042,
          "lng": 14.5189,
          "address": "Sliema, Malta"
        },
        "type": "DROPOFF",
        "passengers": null,
        "lastStop": true
      }
    ],
    "passenger": {
      "firstName": "John",
      "lastName": "Doe",
      "contactNumber": "+35612345678"
    },
    "price": {
      "manualPrice": {
        "amount": {
          "value": 20.00,
          "currency": "EUR"
        },
        "reason": "Special rate"
      },
      "quotationPrice": null,
      "priceRange": null,
      "bookingFee": {
        "value": 1.00,
        "currency": "EUR"
      },
      "waitingTimeFee": null
    },
    "payment": {
      "paymentType": "CASH",
      "channel": "IN_VEHICLE",
      "status": "NOT_SETTLED"
    }
  }'

GET Get Booking by ID

Retrieves a specific booking by its ID.

GET/bookings/{id}

Description: Gets detailed booking information including customer, trip details, and status.

curl -X GET "{{baseUrl}}/api/v1/bookings/123" \
  -H "X-Api-Key: {{api-key}}"

Ride Tracking Link

Pass includeTrackingLink=true to receive the live ride tracking link alongside the booking. The link lets a recipient follow the vehicle in real time on a web page, and is the same link the customer can share from the app.

GET/bookings/{id}?includeTrackingLink=true

curl -X GET "{{baseUrl}}/api/v1/bookings/123?includeTrackingLink=true" \
  -H "X-Api-Key: {{api-key}}"

Two extra fields are added to the booking response. The booking fields themselves are unchanged, so existing integrations are unaffected whether or not the parameter is supplied.

Example response:

{
  "id": 123,
  "customerId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "TRIP_STARTED",
  "pickupTime": "2024-01-01T10:00:00Z",
  "vehicleType": { "code": "van" },
  "tripWaypoints": [],
  "passenger": { "firstName": "John", "lastName": "Doe" },
  "price": {},
  "payment": {},
  "trackingLink": "https://shareridedetails.example.com/ABC123",
  "trackingLinkExpiresAt": null
}

When a link is returned

A null trackingLinkExpiresAt alongside a populated trackingLink is expected while the ride is in progress — it means the link has no expiry yet, not that it has expired. An expiry is only set once the ride ends, when the link enters a short grace period before it stops working.

Important notes

• The tracking link is a credential: anyone holding the URL can view the ride. Responses containing a link are returned with Cache-Control: no-store and must not be cached, logged, or forwarded to parties who should not see the ride.
• trackingLink is null whenever no link is available. The API does not distinguish between the possible reasons (no session yet, ride finished, feature disabled), and this is never an error — the booking payload is always returned in full.
• This feature is enabled per tenant. If it is not enabled for your account, the two fields are always null. Contact help@ecabs.com.mt to have it enabled.
• Omitting includeTrackingLink, or setting it to false, skips the tracking lookup entirely and returns the standard booking response.

GET Get All Bookings

Retrieves all bookings with pagination support.

GET/bookings

Description: Lists all bookings with support for:

• Status filtering
• Pickup time window filtering
• Shift filtering
• Driver filtering
• Pagination

If both pickupTimeFrom and pickupTimeTo are provided, the system validates that the range is correct.

curl -X GET "{{baseUrl}}/api/v1/bookings?statusIn=COMPLETED&pickupTimeFrom=2025-01-01T00:00:00Z&pickupTimeTo=2025-01-02T00:00:00Z&shiftId=12&driverIds=3&driverIds=7&page=0&size=25" \
  -H "X-Api-Key: {{api-key}}"

PUT Update Booking Status

Updates the status of an existing booking.

PUT/bookings/{id}

Description: Updates booking status using BookingStatusEnum values (RESERVED, DISPATCHED, ACCEPTED, CAB_ARRIVED_AT_PICKUP, TRIP_STARTED, CANCELLED, etc.).

curl -X PUT "{{baseUrl}}/api/v1/bookings/123" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{
    "status": "CANCELLED"
  }'

PATCH Update Driver Operational Status

Updates one driver's operational status. Use the existing numeric driver_id already shown in the Cuorium panel for the intended tenant. The driverId path accepts decimal digits with a value from 1 through 2147483647 (a positive signed 32-bit integer). Non-numeric, fractional, non-positive and out-of-range values return 400 Bad Request before any downstream call.

The ID is resolved only in the authenticated target tenant deployment. A caller cannot select another tenant, and an absent ID returns 404 Not Found without searching other tenants. Knowing an ID does not grant access: the API key and required role are checked for every request.

PATCH/drivers/{driverId}/status

Authentication: Send X-Api-Key; the API key must have the DRIVER_STATUS_WRITER role.

The supported status values are:

• ACTIVE: Makes the driver active. The driver's stored mobile number must be present.
• SUSPENDED: Makes the driver inactive and schedules reactivation in one week.
• DEACTIVATED: Makes the driver inactive indefinitely.

Repeating the driver's current status is safe and returns 200 OK without changing the driver or rearming a reactivation schedule.

Set the driver to ACTIVE:

curl -X PATCH \
  "{{baseUrl}}/api/v1/drivers/12345/status" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{
    "status": "ACTIVE"
  }'

Set the driver to SUSPENDED:

curl -X PATCH \
  "{{baseUrl}}/api/v1/drivers/12345/status" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{
    "status": "SUSPENDED"
  }'

Set the driver to DEACTIVATED:

curl -X PATCH \
  "{{baseUrl}}/api/v1/drivers/12345/status" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{
    "status": "DEACTIVATED"
  }'

Example success response:

{
  "driverId": 12345,
  "status": "SUSPENDED",
  "previousStatus": "ACTIVE"
}

The response returns the same driver ID as a JSON integer. For an idempotent request, status and previousStatus contain the same value.