### Example GET Request to Retrieve Customers Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/1_Introduction/02_Get_started.mdx A cURL command demonstrating how to fetch all customer data from the Fleet Management API. It specifies the HTTP method, endpoint, and required headers for authentication and content type. ```sh curl -X GET "https://fleetmanagement.magiclaneapis.com/v1/customers" \ -H "Authorization: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` -------------------------------- ### Fleet Management API Request Structure and Authentication Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/1_Introduction/02_Get_started.mdx Details the components of an API request to the Fleet Management API, including endpoint URLs, HTTP methods, and the critical role of the Authorization header for API key authentication. It also outlines the process for account creation, project setup, and API key generation. ```APIDOC API Request Components: - Endpoint URL: The specific address for interacting with resources (e.g., /v1/customers). - HTTP Method: The action to perform (GET, POST, PUT, DELETE). - Headers: Include authentication and content type information. - Authorization: - Content-Type: application/json - Request Body: Data sent for POST/PUT requests (JSON format). API Key Authentication: - Required for all requests. - Sent in the 'Authorization' header. - Without a valid key, requests will result in a 401 Unauthorized error. Key Management: - Create an account at developer.magiclane.com/api/login. - Log in to your Dashboard. - Navigate to the 'Projects' tab. - Click 'Create project' and provide a name and description. - Projects are generated with an initial API key. - Generate additional API keys with custom expiration dates via 'Generate additional API Key'. - Ensure API keys are kept secure and updated before expiration to avoid service limitations. ``` -------------------------------- ### Example Vehicle Constraints Configuration Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/06_VehicleConstraints.mdx An example JSON payload demonstrating how to configure vehicle constraints, including start date, package limits, order counts, distance, revenue, and fuel price. ```json { "vehiclesConstraints": [ { "fuelPrice": 1.09, "startDate": 1596758400000, "maxNumberOfPackages": 53, "minNumberOfOrders": 0, "maxNumberOfOrders": 300, "minDistance": 0, "maxDistance": 800, "maxRevenue": 85 } ] } ``` -------------------------------- ### Get All Vehicles Response Example Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/04_Vehicle.mdx Example JSON response body for a successful request to retrieve a list of vehicles. It includes details such as vehicle ID, type, status, location, and operational parameters. ```json { "vehicles": [ { "id": 135932, "type": 0, "status": 0, "name": "Car vehicle 1", "manufacturer": "Renault", "model": "Master", "fuelType": 2, "lastPosition": [ 48.870569, 2.356448 ], "consumption": 6.5, "plate": "AA-123-AA", "maxLoadWeight": 60, "maxLoadCube": 50, "height": 0, "width": 0, "weight": 0, "length": 0, "axleLoad": 0, "fixedCost": 0, "costPerHour": 0, "startTime": 420, "endTime": 1439 }, { "id": 135933, "type": 0, "status": 0, "name": "Car vehicle 2", "manufacturer": "Renault", "model": "Master", "fuelType": 2, "lastPosition": [ 48.82674, 2.342116 ], "consumption": 6.5, "plate": "AA-124-AA", "maxLoadWeight": 60, "maxLoadCube": 50, "height": 0, "width": 0, "weight": 0, "length": 0, "axleLoad": 0, "fixedCost": 0, "costPerHour": 0, "startTime": 420, "endTime": 1439 } ] } ``` -------------------------------- ### Fuel Price Request/Response Body Example Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/10_FuelPrice.mdx Provides an example of the JSON structure for creating a fuel price record (request body) and the structure of a successful response. ```json { "dieselStandard": 1.5, "dieselPremium": 2, "gasolineStandard": 1.51, "gasolinePremium": 1.48, "electric": 0.18, "lpg": 0.6 } ``` ```json { "creationTimestamp": 1602684618476, "dieselStandard": 1.5, "dieselPremium": 2, "gasolineStandard": 1.51, "gasolinePremium": 1.48, "electric": 0.18, "lpg": 0.6 } ``` -------------------------------- ### Example Fleet Management Configuration Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/05_ConfigurationParameters.mdx An example JSON object demonstrating a typical configuration for fleet management optimization. It includes settings for optimization name, time windows, order dropping, route balancing, optimization criteria, and various route-specific parameters. ```json { "configurationParameters": { "name": "Test Optimization", "ignoreTimeWindow": false, "allowDroppingOrders": true, "groupingOrders": false, "balancedRoutes": 0, "optimizationCriterion": 1, "arrangeCriterion": 0, "optimizationQuality": 2, "maxTimeToOptimize": 600, "maxWaitTime": 18000, "routeType": 0, "restrictions": 0, "distanceUnit": 0, "orderSequenceOptions": [] } } ``` -------------------------------- ### Route Data Example Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/08_Route.mdx An example JSON structure representing data associated with a route, including traveled distance and revenue. ```json { "traveledDistance": 0.07019499689340591, "distanceToNextOrder": 0.5936400294303894, "revenueAtArrival": 0, "visitTimestamp": 0 } ], "totalTime": 91, "totalDistance": 0.6638350486755371 ``` -------------------------------- ### Get Single Vehicle Response Example Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/04_Vehicle.mdx Example JSON response body for a successful request to retrieve a single vehicle by its ID. It contains detailed information about the specified vehicle. ```json { "id": 135932, "type": 0, "status": 0, "name": "Car vehicle 1", "manufacturer": "Renault", "model": "Master", "fuelType": 2, "lastPosition": [ 48.870569, 2.356448 ], "consumption": 6.5, "plate": "AA-123-AA", "maxLoadWeight": 60, "maxLoadCube": 50, "height": 0, "width": 0, "weight": 0, "length": 0, "axleLoad": 0, "fixedCost": 0, "costPerHour": 0, "startTime": 420, "endTime": 1439 } ``` -------------------------------- ### GET /routes - Fetch All Routes Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/08_Route.mdx Fetches all available routes from the fleet management system. Requires an API key for authorization. Supports optional search parameters. ```APIDOC GET /v1/routes Description: Fetches all available routes. URL: https://fleetmanagement.magiclaneapis.com/v1/routes Headers: Authorization: YOUR_API_KEY Query Parameters: search (string, optional): General search term. Returned error codes: 200 Successful: Successful operation. 400 Bad Request: The values sent for page and per_page parameters are incorrect; should be greater than 0. 401 Unauthorized: API key is missing or invalid. 405 Method Not Allowed: Incorrect method type. 500 Internal Server Error: Database error occurred. ``` -------------------------------- ### Route Data Structure Example Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/08_Route.mdx Example JSON structure representing detailed data for a specific route, including location, timing, package status, and travel metrics. This snippet illustrates the typical payload returned when querying route information. ```JSON { "state": "", "extra": "", "city": "", "country": "" } }, "matchedLocation": [ 48.82734625, 2.3421875 ], "actualLocation": [ 0, 0 ], "indexInRoute": 0, "indexInOptimization": 1, "arrivalTime": 1596783612000, "timeToNextOrder": 79, "waitTime": 0, "numberOfPackagesAtArrival": 0, "collectedNumberOfPackages": 0, "deliveredNumberOfPackages": 0, "weightAtArrival": 0, "collectedWeight": 0, "deliveredWeight": 0, "cubeAtArrival": 0, "collectedCube": 0, "deliveredCube": 0, "traveledDistance": 0.07019499689340591, "distanceToNextOrder": 0.5936400294303894, "revenueAtArrival": 0, "visitTimestamp": 0 } ], "totalTime": 91, "totalDistance": 0.6638350486755371 ``` -------------------------------- ### GET /requests - Fetch All Requests Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/012_Request.mdx Fetches a list of all requests. Supports filtering, sorting, and pagination. Requires an API key for authorization. ```APIDOC Request Object Fields: id (Integer): Unique identifier for the request. optimizationId (Integer): The ID of the associated optimization. Only available if the request is an optimization request. routeId (Integer): The ID of the associated route. Only available if the request is a route request. status (Integer): Current status of the request: 0 - Created, 1 - Pending, 2 - Finished, 3 - Canceled. message (String): Status message for the request. creationTimestamp (Integer): Timestamp when the request was created. Endpoint: Get All Requests Method: GET Endpoint: /requests URL: https://fleetmanagement.magiclaneapis.com/v1/requests Headers: Authorization: YOUR_API_KEY Description: Fetches a list of all requests. Returned error codes: 200 Successful: Successful operation. 400 Bad Request: Invalid input or missing required fields. 401 Unauthorized: API key is missing or invalid. 405 Method Not Allowed: Incorrect method type. 500 Internal Server Error: Database error occurred. Example Response Body (200): { "requests": [ { "id": 23412, "optimizationId": 32754, "status": 0, "message": "Operation done successfully!", "creationTimestamp": 1747834619 }, { "id": 23456, "routeId": 46578, "status": 0, "message": "Operation done successfully!", "creationTimestamp": 1745676643 }, { "id": 23567, "routeId": 46587, "status": 0, "message": "Operation done successfully!", "creationTimestamp": 1747786578 } ] } ``` -------------------------------- ### Example Territory Request Body Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/09_Territory.mdx An example JSON structure representing a request body, likely used for operations like fetching or modifying territory data. The actual content is dynamically generated. ```json { "message": "Operation done successfully" } ``` -------------------------------- ### Get All Templates API Endpoint Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/011_Template.mdx Fetches a list of all templates with optional filtering. Supports various query parameters for searching, filtering, and sorting. ```APIDOC GET /v1/templates Description: Fetches a list of all templates with optional filtering. URL: https://fleetmanagement.magiclaneapis.com/v1/templates Headers: Authorization: YOUR_API_KEY Query Parameters: search (string, optional): General search term across optimizations. id (string, optional): Filter by optimization ID (id=value:exact for exact match). name (string, optional): Filter by optimization name (name=value:exact for exact match). creationTime (string, optional): Filter by creation time (creationTime=value:exact for exact match). ignoreTimeWindow (string, optional): Filter optimizations that ignore time windows (ignoreTimeWindow=value:exact for exact match). balancedRoutes (string, optional): Determines if routes have a similar number of orders. routeType (string, optional): Filter by route type (routeType=value). vehicleCategory (string, optional): Filter by vehicle type (electric or non-electric). sameVehicleConstraints (string, optional): Determines if only one vehicle constraint will be used for all vehicles. sameDeparture (string, optional): Determines if all routes start from the same departure point. sameDestination (string, optional): Determines if all routes end at the same destination. sort (string, optional): Sorting format: column1:asc/desc,column2:asc/desc. Available columns: id, name, creationTime, ignoreTimeWindow, optimizeBy, optimizationQuality, maxOptimizeTime, routeType, matricesBuildType, restrictions, maxWaitTimeOrders, arrangeCriterion, balancedRoutes. page (integer, optional): Page number for pagination. per_page (integer, optional): Number of items per page. Returned Error Codes: 200 Successful: Successful operation. 400 Bad Request: Invalid input or missing required fields. 401 Unauthorized: API key is missing or invalid. 405 Method Not Allowed: Incorrect method type. 500 Internal Server Error: Database error occurred. Example Response (200 Successful): { "templatesParameters": [ { "id": 87987, "name": "Paris - test Optimization 50 vehicles in Berlin", "ignoreTimeWindow": false, "balancedRoutes": 0, "optimizationCriterion": 1, "arrangeCriterion": 0, "optimizationQuality": 2, "maxTimeToOptimize": 600, "maxWaitTime": 800, "routeType": 2, "matrixBuiltType": 1, "restrictions": 0, "vehicleCategory": 0, "sameDepartureForAll": false, "sameDestinationForAll": false, "sameVehicleConstraintsForAll": true }, { "id": 87988, "name": "Paris - test Optimization 25 vehicles in Berlin", "ignoreTimeWindow": false, "balancedRoutes": 0, "optimizationCriterion": 1, "arrangeCriterion": 0, "optimizationQuality": 2, "maxTimeToOptimize": 600, "maxWaitTime": 800, "routeType": 2, "matrixBuiltType": 1, "restrictions": 0, "vehicleCategory": 0, "sameDepartureForAll": false, "sameDestinationForAll": false, "sameVehicleConstraintsForAll": true } ] } ``` -------------------------------- ### Example Request Body for Fleet Optimization API Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/08_Route.mdx This JSON structure represents a comprehensive request body for a fleet optimization or ride management API call. It includes identifiers for the optimization and ride, detailed configuration parameters for the optimization engine, constraints specific to the vehicle, and full details for the vehicle itself. Furthermore, it specifies the departure and destination locations with their addresses and coordinates, and an array of orders, each with its own information, location, and customer details. This example is crucial for understanding the data model required to interact with the MagicLane Fleet Management system's optimization capabilities. ```json { "id": 250806, "optimizationId": 137211, "configurationParameters": { "orderSequenceOptions": [], "distanceUnit": 0, "maxTimeToOptimize": 300, "optimizationQuality": 2, "routeType": 0, "arrangeCriterion": 0, "restrictions": 0, "maxWaitTime": 18000, "balancedRoutes": 0, "groupingOrders": false, "optimizationCriterion": 0, "allowDroppingOrders": false, "ignoreTimeWindow": false, "name": "Paris - test optimization - Part 1" }, "vehicleConstraints": { "startDate": 1596758400000, "maxNumberOfPackages": 53, "minNumberOfOrders": 0, "maxNumberOfOrders": 99999999, "minDistance": 0, "maxDistance": 100000000, "maxRevenue": 85, "fuelPrice": 1.0700000524520874 }, "rideStatus": 1, "vehicle": { "length": 0, "weight": 0, "width": 0, "licensePlate": "", "consumption": 6.5, "fuelType": 2, "make": "", "id": 134764, "name": "Car vehicle", "model": "", "costPerHour": 0, "type": 0, "status": 0, "maxLoadWeight": 60, "height": 0, "maxLoadCube": 50, "idDriver": 134764, "endTime": 1439, "fixedCost": 0, "startTime": 420, "lastPosition": [ 2147483647, 2147483647 ] }, "destination": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "arrivalTime": 1596783691000, "traveledDistance": 0.6638350486755371 }, "departure": { "depotId": 0, "alias": "Departure2", "address": { "streetNumber": "34", "postalCode": "86000", "streetName": "Boulevard Chasseigne", "county": "Nouvelle-Aquitaine", "state": "", "extra": "", "city": "Poitiers", "country": "France" }, "location": [ 48.82674, 2.342116 ], "matchedLocation": [ 48.82679375, 2.3420853125 ], "numberOfpackages": 0, "weight": 0, "cube": 0, "departureTime": 1596783600000, "timeToNext": 12, "distanceToNext": 0.07019499689340591 }, "shape": "mn_iH_mhMCVuGuBQIy@s@SDOLIxFzAOlAIfHJJi@mAa@BW", "creationTimestamp": 1742220618730, "neededFuel": 0.04314928129315376, "matrixBuildType": 1, "price": 0.04616973176598549, "totalWaitTime": 0, "totalServiceTime": 0, "orders": [ { "orderInfo": { "revenue": 0, "serviceTime": 0, "timeWindow": [ 420, 1086 ], "creationTimestamp": 1742220613856, "cube": 0, "numberOfPackages": 0, "depotId": 0, "customData": "", "weight": 0, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 876534, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c1@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1786643, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "matchedLocation": [ 48.82734625, 2.3421875 ], "actualLocation": [ 0, 0 ], "indexInRoute": 0, "indexInOptimization": 1, "arrivalTime": 1596783612000, "timeToNextOrder": 79, "waitTime": 0, "numberOfPackagesAtArrival": 0, "collectedNumberOfPackages": 0, "deliveredNumberOfPackages": 0, "weightAtArrival": 0, "collectedWeight": 0, "deliveredWeight": 0, "cubeAtArrival": 0, "collectedCube": 0, "deliveredCube": 0 } ] } ``` -------------------------------- ### Customer List Response Body Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/01_Customer.mdx Example JSON structure for a successful response when retrieving a list of customers. It includes an array of customer objects, each with detailed information. ```json { "customers": [ { "id": 1838721, "alias": "Magic Customer", "firstName": "Magic", "lastName": "Customer", "address": { "country": "France", "state": "Île-de-France", "county": "Paris", "city": "Paris", "postalCode": "75010", "streetName": "Rue Gustave Goublier", "streetNumber": "2", "extra": "" }, "email": "magiccustomer@example.com", "phoneNumber": "+1202555018", "location": [ 48.870852, 2.356148 ], "customData": "" }, { "id": 1838722, "alias": "Magic Customer2", "firstName": "Magic", "lastName": "Customer2", "address": { "country": "", "state": "", "county": "", "city": "", "postalCode": "", "streetName": "", "streetNumber": "" }, "email": "magiccustomer2@example.com", "phoneNumber": "+1202555018", "location": [ 48.870852, 2.356148 ], "customData": "communicationPreference: email" } ] } ``` -------------------------------- ### Example Request/Response for Fleet Optimization Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/011_Template.mdx Demonstrates a typical JSON request body for fleet optimization tasks, including parameters like vehicle count, optimization criteria, and route types. It also shows a successful JSON response body indicating operation completion. ```json { "id": 87988, "name": "Paris - test Optimization 50 vehicles in Berlin", "ignoreTimeWindow": false, "balancedRoutes": 0, "optimizationCriterion": 1, "arrangeCriterion": 0, "optimizationQuality": 2, "maxTimeToOptimize": 600, "maxWaitTime": 800, "routeType": 2, "matrixBuiltType": 1, "restrictions": 0, "vehicleCategory": 0, "sameDepartureForAll": false, "sameDestinationForAll": false, "sameVehicleConstraintsForAll": true } ``` ```json { "message": "Operation done successfully" } ``` -------------------------------- ### Delete MiscLocations Response Body Example (Success) Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/03_MiscLocation.mdx Example of a successful JSON response body when miscellaneous locations are deleted. ```JSON { "message": "Operation done successfully" } ``` -------------------------------- ### Delete MiscLocations Request Body Example Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/03_MiscLocation.mdx Example of the JSON request body containing an array of miscellaneous location IDs to be deleted. ```JSON [ 98765, 98766, 98767 ] ``` -------------------------------- ### Example API Response Body - Fleet Management Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/01_Customer.mdx This JSON structure represents a typical response from a fleet management API, showcasing order details and optimization settings. It includes nested objects for order information, customer details, and configuration parameters for route optimization. ```json { "history": [ { "order": { "revenue": 0, "serviceTime": 0, "timeWindow": [ 420, 1086 ], "creationTimestamp": 1744096603223, "cube": 0, "numberOfPackages": 0, "depotId": 0, "customData": "", "weight": 0, "phoneNumber": "+12025550181", "lastName": "", "status": 0, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 933799, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c1@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839506, "location": [ 48.827327, 2.342267 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, "optimizationsAndRoutes": [ { "optimization": { "configurationParameters": { "orderSequenceOptions": [], "distanceUnit": 0, "maxTimeToOptimize": 300, "optimizationQuality": 2, "routeType": 0, "arrangeCriterion": 0, "restrictions": 0, "maxWaitTime": 18000, "balancedRoutes": 0, "groupingOrders": false, "optimizationCriterion": 0, "allowDroppingOrders": false, "ignoreTimeWindow": false, "name": "Paris - test optimization" }, "id": 139950, "creationTimestamp": 1744096603789, "orders": [ { "revenue": 0, "serviceTime": 600, "timeWindow": [ 420, 1086 ], "creationTimestamp": 1744096603173, "cube": 0, "numberOfPackages": 0, "depotId": 0, "customData": "", "weight": 0, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1, "type": 0, "priority": 0, "id": 933798, "location": [ 48.870852, 2.356148 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" }, "customerInfo": { "phoneNumber": "+12025550181", "email": "c0@yahoo.com", "lastName": "", "firstName": "", "alias": "", "customData": "", "id": 1839505, "location": [ 48.870852, 2.356148 ], "address": { "streetNumber": "", "postalCode": "", "streetName": "", "county": "", "state": "", "extra": "", "city": "", "country": "" } } }, { "revenue": 0, "serviceTime": 0, "timeWindow": [ 420, 1086 ], "creationTimestamp": 1744096603223, "cube": 0, "numberOfPackages": 0, "depotId": 0, "customData": "", "weight": 0, "phoneNumber": "+12025550181", "lastName": "", "status": 1, "firstName": "", "alias": "", "state": 1 } ] } } ] } ] } ``` -------------------------------- ### Get Miscellaneous Location by ID Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/03_MiscLocation.mdx Retrieves a specific miscellaneous location by its unique identifier. Requires an API key for authorization. Supports GET requests to the specified endpoint. ```APIDOC GET /misc-locations/{id} URL: https://fleetmanagement.magiclaneapis.com/v1/misc-locations/{id} Headers: Authorization: YOUR_API_KEY Path Parameters: id (integer, required): The unique location ID. Returned Error Codes: 200 Successful: Successful operation. 400 Bad Request: Invalid input or missing required fields. 401 Unauthorized: API key is missing or invalid. 404 Not Found: MiscLocation not found in database. 405 Method Not Allowed: Incorrect method type. 500 Internal Server Error: Database error occurred. Example Response (200): { "id": 16262, "isDepot": true, "alias": "Depot 1", "location": [ 48.870569, 2.356448 ], "address": { "country": "France", "state": "Ile-de-France", "county": "Paris", "city": "Paris", "postalCode": "75001", "streetName": "Rue de Rivoli", "streetNumber": "1" } } ``` -------------------------------- ### Get Customer History API Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/01_Customer.mdx Retrieves the order history and associated optimizations for a specific customer using their unique ID. Supports GET method on the /customers/{id}/history endpoint. ```APIDOC GET /customers/{id}/history URL: https://fleetmanagement.magiclaneapis.com/v1/customers/{id}/history Headers: Authorization: YOUR_API_KEY Content-Type: application/json Path Parameters: id (integer, required): The unique customer ID. Responses: 200 Successful: Successful operation. 400 Bad Request: The customer was not found or its history couldn’t be retrieved. 401 Unauthorized: API key is missing or invalid. 404 Not Found: Customer not found in database. 405 Method Not Allowed: Incorrect method type. 500 Internal Server Error: Database error occurred. ``` -------------------------------- ### Get Order by ID API Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/2_Core_Concepts/02_Order.mdx Retrieves a specific order by its unique identifier. This endpoint requires an API key for authorization and returns detailed order information upon success. It outlines the GET method, endpoint structure, required headers, path parameters, and potential error responses. ```APIDOC GET /orders/{id} - Retrieves a specific order by ID. - Base URL: https://fleetmanagement.magiclaneapis.com/v1 - Headers: - Authorization: YOUR_API_KEY - Path Parameters: - id (integer, required): The unique order ID. - Success Response (200 OK): - Description: Successful operation. - Body: JSON object containing order details. { "id": 879887, "creationTimestamp": 1752123517222, "customerInfo": { "id": 1838721, "alias": "Magic Customer", "firstName": "Magic", "lastName": "Customer", "address": { "country": "", "state": "", "county": "", "city": "", "postalCode": "", "streetName": "", "streetNumber": "" }, "email": "magiccustomer@example.com", "phoneNumber": "+1202555018", "location": [ 48.870852, 2.356148 ], "customData": "" }, "location": [ 48.870852, 2.356148 ], "alias": "Magic Order", "firstName": "Magic", "lastName": "Order", "address": { "country": "", "state": "", "county": "", "city": "", "postalCode": "", "streetName": "", "streetNumber": "" }, "phoneNumber": "+1202555018", "customData": "", "type": 0, "status": 0, "state": 1, "priority": 0, "numberOfPackages": 3, "weight": 5.1, "cube": 2.5, "revenue": 12, "timeWindow": [ 420, 1086 ], "serviceTime": 0, "depotId": 0 } - Error Responses: - 400 Bad Request: Invalid input or missing required fields. - 401 Unauthorized: API key is missing or invalid. - 404 Not Found: Order not found in database. - 405 Method Not Allowed: Incorrect method type. - 500 Internal Server Error: Database error occurred. ``` -------------------------------- ### Create Optimization API Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/1_Introduction/01_Introduction.mdx Initiates the route optimization process by submitting all defined elements: orders, vehicles, constraints, and optimization parameters. The API returns an `optimizationId` and `requestId` for tracking the process. ```APIDOC POST /optimizations Request: An object that includes orders, vehicles, constraints, and optimization settings Response: Returns an `optimizationId` and `requestId` to track the process ``` -------------------------------- ### API Flexibility and Error Handling Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/1_Introduction/01_Introduction.mdx Details on the API's asynchronous operation capabilities, robust error handling mechanisms, and customization parameters for tailoring optimization to specific business needs. ```APIDOC API Flexibility: - Async Operations: Supports asynchronous execution for optimizations, updates, and reassignments. - Example: InitiateOptimization(async=True) - Error Handling: - Provides detailed error messages and codes for debugging failed requests. - Example Error Response: { "errorCode": "ORDER_NOT_FOUND", "message": "The specified order ID does not exist." } - Customization: - Offers flexible configuration parameters to tailor API behavior and optimization algorithms. ``` -------------------------------- ### Create Order API Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/1_Introduction/01_Introduction.mdx Defines delivery or pickup items, including location, time windows, and priorities. Orders are linked to customers using `customerId`. The API accepts an array of order objects and returns them with system-generated IDs. ```APIDOC POST /orders Request: An array of order objects Response: Returns order objects with system-generated `id`s ``` -------------------------------- ### Create Customer API Source: https://github.com/lzavoianu/magiclanefleetmanagement/blob/main/1_Introduction/01_Introduction.mdx Adds new customer records to the system. Each order must be linked to a customer via their customerId. The API expects an array of customer objects and returns the created customer objects with system-generated IDs. ```APIDOC POST /customers Request: An array of customer objects Response: Returns customer objects with system-generated `id`s ```