{ "openapi": "3.1.0", "info": { "title": "ENGARAGE Open API", "version": "1.0.0", "summary": "Read and write your workshop data from your own systems.", "description": "The ENGARAGE Open API gives your own systems the same view of your workshop that\nthe app has: customers, vehicles, bookings, work orders, quotations, inventory and\nprocurement.\n\n## Availability\nThe API is included with the **Pro** plan. Keys are issued per workshop from\n**Account Settings → API Docs & Keys**, and every request is scoped to the workshop\nthat issued the key — there is no way to read another workshop's data.\n\n## Authentication\nSend your secret key on every request, either as an `X-API-Key` header or as\n`Authorization: Bearer `. Keys are shown once, at creation; store them\nsomewhere safe and never ship one in client-side code.\n\n## Environments\nEvery key is either **live** (`eng_live_…`) or **sandbox** (`eng_test_…`). A sandbox\nkey runs against an isolated fixture dataset with identical validation, envelopes and\nerror codes, so you can build and test a client — including writes — without touching\nproduction data. Reset the sandbox at any time from the portal or with\n`POST /sandbox/reset`.\n\n## Scopes\nA key carries one of `read`, `write` or `admin`, and they nest: `admin` implies\n`write`, which implies `read`. GET needs `read`, POST and PATCH need `write`, and\nDELETE needs `admin`.\n\n## Pagination\nList endpoints take `page` and `limit` (max 200) and return a `meta` block with\n`total`, `page`, `limit` and `total_pages`. Sort with `sort=field` or `sort=-field`.\n\n## Rate limits\n600 requests per minute per live key and 1200 per sandbox key.\nEvery response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`; a `429` carries\n`retry_after` in seconds.\n\n## Errors\nFailures always return the same envelope, so one handler covers them all:\n\n```json\n{ \"error\": { \"code\": \"validation_error\", \"message\": \"…\", \"field\": \"name\" } }\n```", "contact": { "name": "ENGARAGE Support", "email": "support@engarage.io", "url": "https://engarage.io" } }, "servers": [ { "url": "https://app.engarage.io/api/v1", "description": "Live and sandbox share one base URL — the key decides which dataset you reach." } ], "tags": [ { "name": "Meta", "description": "Key introspection, health and sandbox control." }, { "name": "Customers", "description": "Customers." }, { "name": "Vehicles", "description": "Vehicles, Vehicle Models." }, { "name": "Bookings", "description": "Bookings." }, { "name": "Work Orders", "description": "Work Orders." }, { "name": "Quotations", "description": "Quotations." }, { "name": "Inventory", "description": "Parts, Suppliers, Purchase Orders." }, { "name": "Catalogue", "description": "Services." }, { "name": "Workshop", "description": "Mechanics." } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "paths": { "/ping": { "get": { "tags": [ "Meta" ], "operationId": "ping", "summary": "Health check", "description": "Confirms the API is reachable and your key is valid. The cheapest call to wire up first.", "responses": { "200": { "description": "The API is up and the key is valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "version": { "type": "string" }, "environment": { "type": "string", "enum": [ "live", "sandbox" ] }, "time": { "type": "string", "format": "date-time" } } }, "example": { "ok": true, "version": "1.0.0", "environment": "sandbox", "time": "2026-09-08T04:20:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/me": { "get": { "tags": [ "Meta" ], "operationId": "getMe", "summary": "Describe the calling key", "description": "Who you are: the workshop the key belongs to, its environment, scopes and rate limit. Useful for showing \"connected as…\" in your own UI.", "responses": { "200": { "description": "Key context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyContext" }, "example": { "workshop": { "id": 128, "name": "Workshop Engarage Demo" }, "key": { "name": "Partner ERP Integration", "environment": "sandbox", "scopes": [ "read", "write" ], "last_used_at": "2026-09-08T04:19:12Z" }, "plan": "pro", "rate_limit": { "limit": 1200, "window": "1 minute" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/sandbox/reset": { "post": { "tags": [ "Meta" ], "operationId": "resetSandbox", "summary": "Reset the sandbox dataset", "description": "Throws away everything your sandbox key has created or changed and reseeds the fixtures. Rejected with `409` if called with a live key — there is deliberately no way to reset production.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Sandbox reseeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "ok": true, "message": "Sandbox dataset reset." } } } }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/customers": { "get": { "tags": [ "Customers" ], "operationId": "listCustomers", "summary": "List customers", "description": "A customer owns vehicles and work orders. Phone number is the natural key most workshops search on, so it is indexed and filterable.", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Partial match across `name`, `phone` and `email`." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "name", "-name" ], "default": "-created_at" }, "description": "Sort field. Prefix with `-` for descending." }, { "name": "phone", "in": "query", "schema": { "type": "string" }, "description": "Exact phone number match." }, { "name": "email", "in": "query", "schema": { "type": "string" }, "description": "Exact email match." }, { "name": "status", "in": "query", "schema": { "type": "integer" }, "description": "Record status. 1 = active." } ], "responses": { "200": { "description": "A page of customers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": 1, "name": "Nurul Aisyah binti Rahman", "phone": "123456789", "country_code": "60", "email": "aisyah@example.com", "gender": "female", "dob": "1991-04-18", "note": "Prefers WhatsApp reminders.", "status": 1, "vehicle_count": 2, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } ], "meta": { "total": 8, "page": 1, "limit": 50, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Customers" ], "operationId": "createCustomer", "summary": "Create a customer", "description": "Creates a customer in the workshop that owns the key. Requires the `write` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerInput" }, "example": { "name": "Nurul Aisyah binti Rahman", "phone": "123456789", "country_code": "60", "email": "aisyah@example.com", "gender": "female", "dob": "1991-04-18", "note": "Prefers WhatsApp reminders." } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" } } }, "example": { "data": { "id": 1, "name": "Nurul Aisyah binti Rahman", "phone": "123456789", "country_code": "60", "email": "aisyah@example.com", "gender": "female", "dob": "1991-04-18", "note": "Prefers WhatsApp reminders.", "status": 1, "vehicle_count": 2, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/customers/{id}": { "get": { "tags": [ "Customers" ], "operationId": "getCustomer", "summary": "Retrieve a customer", "description": "Fetch a single customer by id. Ids from another workshop return `404`.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "responses": { "200": { "description": "The customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" } } }, "example": { "data": { "id": 1, "name": "Nurul Aisyah binti Rahman", "phone": "123456789", "country_code": "60", "email": "aisyah@example.com", "gender": "female", "dob": "1991-04-18", "note": "Prefers WhatsApp reminders.", "status": 1, "vehicle_count": 2, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Customers" ], "operationId": "updateCustomer", "summary": "Update a customer", "description": "Partial update — send only the fields you want to change. Requires the `write` scope.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerInput" }, "example": { "name": "Nurul Aisyah binti Rahman", "phone": "123456789" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" } } }, "example": { "data": { "id": 1, "name": "Nurul Aisyah binti Rahman", "phone": "123456789", "country_code": "60", "email": "aisyah@example.com", "gender": "female", "dob": "1991-04-18", "note": "Prefers WhatsApp reminders.", "status": 1, "vehicle_count": 2, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/vehicles": { "get": { "tags": [ "Vehicles" ], "operationId": "listVehicles", "summary": "List vehicles", "description": "Vehicles hang off a customer. `plate_no` is what every counter workflow looks up, so filter on it rather than scanning the list.", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Partial match across `plate_no` and `chassis_no`." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "plate_no", "-plate_no" ], "default": "-created_at" }, "description": "Sort field. Prefix with `-` for descending." }, { "name": "plate_no", "in": "query", "schema": { "type": "string" }, "description": "Exact registration-plate match." }, { "name": "customer_id", "in": "query", "schema": { "type": "integer" }, "description": "Only vehicles owned by this customer." }, { "name": "status", "in": "query", "schema": { "type": "integer" }, "description": "Record status. 1 = active." } ], "responses": { "200": { "description": "A page of vehicles.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vehicle" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": 1, "customer_id": 1, "customer_name": "Nurul Aisyah binti Rahman", "plate_no": "WXY 1234", "chassis_no": "JHMCM56557C404453", "ref_car_id": 1, "make": "Perodua", "model": "Myvi 1.5 AV", "segment": "Hatchback", "fuel_type": "Petrol", "year": "2021", "next_service": "2026-12-01", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } ], "meta": { "total": 8, "page": 1, "limit": 50, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Vehicles" ], "operationId": "createVehicle", "summary": "Create a vehicle", "description": "Creates a vehicle in the workshop that owns the key. Requires the `write` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleInput" }, "example": { "customer_id": 1, "plate_no": "WXY 1234", "ref_car_id": 1, "chassis_no": "JHMCM56557C404453", "year": "2021", "next_service": "2026-12-01" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Vehicle" } } }, "example": { "data": { "id": 1, "customer_id": 1, "customer_name": "Nurul Aisyah binti Rahman", "plate_no": "WXY 1234", "chassis_no": "JHMCM56557C404453", "ref_car_id": 1, "make": "Perodua", "model": "Myvi 1.5 AV", "segment": "Hatchback", "fuel_type": "Petrol", "year": "2021", "next_service": "2026-12-01", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/vehicles/{id}": { "get": { "tags": [ "Vehicles" ], "operationId": "getVehicle", "summary": "Retrieve a vehicle", "description": "Fetch a single vehicle by id. Ids from another workshop return `404`.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "responses": { "200": { "description": "The vehicle.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Vehicle" } } }, "example": { "data": { "id": 1, "customer_id": 1, "customer_name": "Nurul Aisyah binti Rahman", "plate_no": "WXY 1234", "chassis_no": "JHMCM56557C404453", "ref_car_id": 1, "make": "Perodua", "model": "Myvi 1.5 AV", "segment": "Hatchback", "fuel_type": "Petrol", "year": "2021", "next_service": "2026-12-01", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Vehicles" ], "operationId": "updateVehicle", "summary": "Update a vehicle", "description": "Partial update — send only the fields you want to change. Requires the `write` scope.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleInput" }, "example": { "customer_id": 1, "plate_no": "WXY 1234" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Vehicle" } } }, "example": { "data": { "id": 1, "customer_id": 1, "customer_name": "Nurul Aisyah binti Rahman", "plate_no": "WXY 1234", "chassis_no": "JHMCM56557C404453", "ref_car_id": 1, "make": "Perodua", "model": "Myvi 1.5 AV", "segment": "Hatchback", "fuel_type": "Petrol", "year": "2021", "next_service": "2026-12-01", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Vehicles" ], "operationId": "deleteVehicle", "summary": "Delete a vehicle", "description": "Soft-deletes the record. Requires the `admin` scope.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "responses": { "204": { "description": "Deleted. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/vehicle-models": { "get": { "tags": [ "Vehicles" ], "operationId": "listVehicleModels", "summary": "List vehicle models", "description": "Read-only reference data shared by every workshop. Look a model up here to get the `ref_car_id` that `POST /vehicles` requires.", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Partial match across `make` and `model`." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "make", "-make", "model", "-model" ], "default": "make" }, "description": "Sort field. Prefix with `-` for descending." }, { "name": "make", "in": "query", "schema": { "type": "string" }, "description": "Exact manufacturer match." }, { "name": "segment", "in": "query", "schema": { "type": "string" }, "description": "Exact segment match, e.g. \"SUV\"." }, { "name": "fuel_type", "in": "query", "schema": { "type": "string" }, "description": "Exact fuel-type match." }, { "name": "status", "in": "query", "schema": { "type": "integer" }, "description": "Record status. 1 = active." } ], "responses": { "200": { "description": "A page of vehicle models.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleModel" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": 1, "make": "Perodua", "model": "Myvi 1.5 AV", "segment": "Hatchback", "fuel_type": "Petrol", "oil_capacity": "3.2L", "car_battery": "NS60", "status": 1 } ], "meta": { "total": 8, "page": 1, "limit": 50, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/vehicle-models/{id}": { "get": { "tags": [ "Vehicles" ], "operationId": "getVehicleModel", "summary": "Retrieve a vehicle model", "description": "Fetch a single vehicle model by id. Ids from another workshop return `404`.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "responses": { "200": { "description": "The vehicle model.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VehicleModel" } } }, "example": { "data": { "id": 1, "make": "Perodua", "model": "Myvi 1.5 AV", "segment": "Hatchback", "fuel_type": "Petrol", "oil_capacity": "3.2L", "car_battery": "NS60", "status": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/bookings": { "get": { "tags": [ "Bookings" ], "operationId": "listBookings", "summary": "List bookings", "description": "A booking is a request for a slot. Accepting one creates a work order; this endpoint covers the request itself.", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Partial match across `remark`." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "scheduled_at", "-scheduled_at", "created_at", "-created_at" ], "default": "-scheduled_at" }, "description": "Sort field. Prefix with `-` for descending." }, { "name": "status", "in": "query", "schema": { "type": "integer" }, "description": "Booking status. 1 = pending, 2 = accepted, 3 = rejected." }, { "name": "customer_id", "in": "query", "schema": { "type": "integer" }, "description": "Only bookings for this customer." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Only bookings at or after this date." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Only bookings at or before this date." } ], "responses": { "200": { "description": "A page of bookings.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": 1, "customer_id": 1, "customer_name": "Nurul Aisyah binti Rahman", "vehicle_id": 1, "plate_no": "WXY 1234", "scheduled_at": "2026-09-15T09:30:00Z", "remark": "Engine oil + filter, brakes squealing.", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } ], "meta": { "total": 8, "page": 1, "limit": 50, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Bookings" ], "operationId": "createBooking", "summary": "Create a booking", "description": "Creates a booking in the workshop that owns the key. Requires the `write` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingInput" }, "example": { "customer_id": 1, "vehicle_id": 1, "scheduled_at": "2026-09-15T09:30:00Z", "remark": "Engine oil + filter, brakes squealing.", "status": 1 } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" } } }, "example": { "data": { "id": 1, "customer_id": 1, "customer_name": "Nurul Aisyah binti Rahman", "vehicle_id": 1, "plate_no": "WXY 1234", "scheduled_at": "2026-09-15T09:30:00Z", "remark": "Engine oil + filter, brakes squealing.", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/bookings/{id}": { "get": { "tags": [ "Bookings" ], "operationId": "getBooking", "summary": "Retrieve a booking", "description": "Fetch a single booking by id. Ids from another workshop return `404`.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "responses": { "200": { "description": "The booking.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" } } }, "example": { "data": { "id": 1, "customer_id": 1, "customer_name": "Nurul Aisyah binti Rahman", "vehicle_id": 1, "plate_no": "WXY 1234", "scheduled_at": "2026-09-15T09:30:00Z", "remark": "Engine oil + filter, brakes squealing.", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Bookings" ], "operationId": "updateBooking", "summary": "Update a booking", "description": "Partial update — send only the fields you want to change. Requires the `write` scope.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingInput" }, "example": { "customer_id": 1, "vehicle_id": 1 } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" } } }, "example": { "data": { "id": 1, "customer_id": 1, "customer_name": "Nurul Aisyah binti Rahman", "vehicle_id": 1, "plate_no": "WXY 1234", "scheduled_at": "2026-09-15T09:30:00Z", "remark": "Engine oil + filter, brakes squealing.", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/work-orders": { "get": { "tags": [ "Work Orders" ], "operationId": "listWorkOrders", "summary": "List work orders", "description": "A work order is the spine of the system: it carries the vehicle, the customer, the assigned mechanic and bay, and every line item. Its `status` walks 1 → 10; see the status table in the guide.", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Partial match across `wo_no`, `invoice_no`, `quotation_no` and `complaint`." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "total_payment", "-total_payment", "paid_at", "-paid_at" ], "default": "-created_at" }, "description": "Sort field. Prefix with `-` for descending." }, { "name": "status", "in": "query", "schema": { "type": "integer" }, "description": "Work-order status, 1–10." }, { "name": "customer_id", "in": "query", "schema": { "type": "integer" }, "description": "Only jobs for this customer." }, { "name": "wo_no", "in": "query", "schema": { "type": "string" }, "description": "Exact work-order number." }, { "name": "invoice_no", "in": "query", "schema": { "type": "string" }, "description": "Exact invoice number." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Created at or after this date." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Created at or before this date." } ], "responses": { "200": { "description": "A page of work orders.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkOrder" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": 1, "wo_no": "WO-2609-0042", "quotation_no": "QT-2609-0031", "invoice_no": "INV-2609-0028", "status": 7, "status_label": "Paid", "customer_id": 1, "customer_name": "Nurul Aisyah binti Rahman", "vehicle_id": 1, "plate_no": "WXY 1234", "mechanic_id": 3, "bay_id": 2, "complaint": "Brakes squealing on cold start.", "remark": "Front pads replaced, discs skimmed.", "mileage": "86540", "total_payment": 486.5, "payment_sst": 0, "method": "card", "booking_at": "2026-09-15T09:30:00Z", "completed_at": "2026-09-15T15:10:00Z", "invoiced_at": "2026-09-15T15:22:00Z", "paid_at": "2026-09-15T15:40:00Z", "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } ], "meta": { "total": 8, "page": 1, "limit": 50, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/work-orders/{id}": { "get": { "tags": [ "Work Orders" ], "operationId": "getWorkOrder", "summary": "Retrieve a work order", "description": "Fetch a single work order by id. Ids from another workshop return `404`.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "responses": { "200": { "description": "The work order.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkOrder" } } }, "example": { "data": { "id": 1, "wo_no": "WO-2609-0042", "quotation_no": "QT-2609-0031", "invoice_no": "INV-2609-0028", "status": 7, "status_label": "Paid", "customer_id": 1, "customer_name": "Nurul Aisyah binti Rahman", "vehicle_id": 1, "plate_no": "WXY 1234", "mechanic_id": 3, "bay_id": 2, "complaint": "Brakes squealing on cold start.", "remark": "Front pads replaced, discs skimmed.", "mileage": "86540", "total_payment": 486.5, "payment_sst": 0, "method": "card", "booking_at": "2026-09-15T09:30:00Z", "completed_at": "2026-09-15T15:10:00Z", "invoiced_at": "2026-09-15T15:22:00Z", "paid_at": "2026-09-15T15:40:00Z", "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Work Orders" ], "operationId": "updateWorkOrder", "summary": "Update a work order", "description": "Partial update — send only the fields you want to change. Requires the `write` scope.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkOrderInput" }, "example": { "status": 7, "mechanic_id": 3 } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkOrder" } } }, "example": { "data": { "id": 1, "wo_no": "WO-2609-0042", "quotation_no": "QT-2609-0031", "invoice_no": "INV-2609-0028", "status": 7, "status_label": "Paid", "customer_id": 1, "customer_name": "Nurul Aisyah binti Rahman", "vehicle_id": 1, "plate_no": "WXY 1234", "mechanic_id": 3, "bay_id": 2, "complaint": "Brakes squealing on cold start.", "remark": "Front pads replaced, discs skimmed.", "mileage": "86540", "total_payment": 486.5, "payment_sst": 0, "method": "card", "booking_at": "2026-09-15T09:30:00Z", "completed_at": "2026-09-15T15:10:00Z", "invoiced_at": "2026-09-15T15:22:00Z", "paid_at": "2026-09-15T15:40:00Z", "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/work-orders/{id}/items": { "get": { "tags": [ "Work Orders" ], "operationId": "listWorkOrderItems", "summary": "Line items on a work order", "description": "Parts, services, packages and miscellaneous charges billed on this job.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "responses": { "200": { "description": "Line items on a work order.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkOrderItems" } } } }, "example": { "data": [ { "id": 5501, "type": "part", "part_id": 812, "service_id": null, "package_id": null, "quantity": 4, "total_price": 168, "total_discount": 0, "tax_rate": 0 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/quotations": { "get": { "tags": [ "Quotations" ], "operationId": "listQuotations", "summary": "List quotations", "description": "A work order can carry several quotations across revisions; the one with `status` 2 is the accepted one.", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Partial match across `quotation_no`." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "-created_at", "updated_at", "-updated_at" ], "default": "-created_at" }, "description": "Sort field. Prefix with `-` for descending." }, { "name": "status", "in": "query", "schema": { "type": "integer" }, "description": "Quotation status. 2 = accepted/converted." }, { "name": "work_order_id", "in": "query", "schema": { "type": "integer" }, "description": "Only quotations on this work order." }, { "name": "quotation_no", "in": "query", "schema": { "type": "string" }, "description": "Exact quotation number." } ], "responses": { "200": { "description": "A page of quotations.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Quotation" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": 1, "quotation_no": "QT-2609-0031", "work_order_id": 42, "wo_no": "WO-2609-0042", "customer_id": 1, "status": 2, "discount": 20, "deposit": 100, "deposit_method": "cash", "deposit_at": "2026-09-15T10:05:00Z", "total": 486.5, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } ], "meta": { "total": 8, "page": 1, "limit": 50, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/quotations/{id}": { "get": { "tags": [ "Quotations" ], "operationId": "getQuotation", "summary": "Retrieve a quotation", "description": "Fetch a single quotation by id. Ids from another workshop return `404`.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "responses": { "200": { "description": "The quotation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Quotation" } } }, "example": { "data": { "id": 1, "quotation_no": "QT-2609-0031", "work_order_id": 42, "wo_no": "WO-2609-0042", "customer_id": 1, "status": 2, "discount": 20, "deposit": 100, "deposit_method": "cash", "deposit_at": "2026-09-15T10:05:00Z", "total": 486.5, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/parts": { "get": { "tags": [ "Inventory" ], "operationId": "listParts", "summary": "List parts", "description": "Your inventory. `quantity` is on-hand stock; it moves when work orders are paid, so treat it as authoritative rather than caching it.", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Partial match across `name`, `part_no`, `brand` and `model`." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "name", "-name", "quantity", "-quantity", "price", "-price", "created_at", "-created_at" ], "default": "name" }, "description": "Sort field. Prefix with `-` for descending." }, { "name": "part_no", "in": "query", "schema": { "type": "string" }, "description": "Exact part number." }, { "name": "brand", "in": "query", "schema": { "type": "string" }, "description": "Exact brand match." }, { "name": "supplier_id", "in": "query", "schema": { "type": "integer" }, "description": "Only parts from this supplier." }, { "name": "status", "in": "query", "schema": { "type": "integer" }, "description": "Record status. 1 = active." }, { "name": "low_stock", "in": "query", "schema": { "type": "boolean" }, "description": "When true, only parts at or below their stock-alert threshold." } ], "responses": { "200": { "description": "A page of parts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Part" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": 1, "name": "Engine Oil Filter", "part_no": "OF-15400-RTA", "brand": "Denso", "model": "Myvi", "variant": "1.5L", "description": "Spin-on oil filter.", "unit": "pcs", "bin_number": "A-04-2", "cost_price": 12.5, "price": 24, "quantity": 36, "stock_alert_threshold": 10, "supplier_id": 4, "is_low_stock": false, "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } ], "meta": { "total": 8, "page": 1, "limit": 50, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Inventory" ], "operationId": "createPart", "summary": "Create a part", "description": "Creates a part in the workshop that owns the key. Requires the `write` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartInput" }, "example": { "name": "Engine Oil Filter", "part_no": "OF-15400-RTA", "brand": "Denso", "model": "Myvi", "variant": "1.5L", "description": "Spin-on oil filter.", "unit": "pcs", "bin_number": "A-04-2", "cost_price": 12.5, "price": 24, "quantity": 36, "stock_alert_threshold": 10, "supplier_id": 4 } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Part" } } }, "example": { "data": { "id": 1, "name": "Engine Oil Filter", "part_no": "OF-15400-RTA", "brand": "Denso", "model": "Myvi", "variant": "1.5L", "description": "Spin-on oil filter.", "unit": "pcs", "bin_number": "A-04-2", "cost_price": 12.5, "price": 24, "quantity": 36, "stock_alert_threshold": 10, "supplier_id": 4, "is_low_stock": false, "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/parts/{id}": { "get": { "tags": [ "Inventory" ], "operationId": "getPart", "summary": "Retrieve a part", "description": "Fetch a single part by id. Ids from another workshop return `404`.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "responses": { "200": { "description": "The part.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Part" } } }, "example": { "data": { "id": 1, "name": "Engine Oil Filter", "part_no": "OF-15400-RTA", "brand": "Denso", "model": "Myvi", "variant": "1.5L", "description": "Spin-on oil filter.", "unit": "pcs", "bin_number": "A-04-2", "cost_price": 12.5, "price": 24, "quantity": 36, "stock_alert_threshold": 10, "supplier_id": 4, "is_low_stock": false, "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Inventory" ], "operationId": "updatePart", "summary": "Update a part", "description": "Partial update — send only the fields you want to change. Requires the `write` scope.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartInput" }, "example": { "name": "Engine Oil Filter", "part_no": "OF-15400-RTA" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Part" } } }, "example": { "data": { "id": 1, "name": "Engine Oil Filter", "part_no": "OF-15400-RTA", "brand": "Denso", "model": "Myvi", "variant": "1.5L", "description": "Spin-on oil filter.", "unit": "pcs", "bin_number": "A-04-2", "cost_price": 12.5, "price": 24, "quantity": 36, "stock_alert_threshold": 10, "supplier_id": 4, "is_low_stock": false, "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Inventory" ], "operationId": "deletePart", "summary": "Delete a part", "description": "Soft-deletes the record. Requires the `admin` scope.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "responses": { "204": { "description": "Deleted. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/services": { "get": { "tags": [ "Catalogue" ], "operationId": "listServices", "summary": "List services", "description": "The service catalogue billed on work orders and quotations.", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Partial match across `name`, `service_no` and `category`." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "name", "-name", "price", "-price", "created_at", "-created_at" ], "default": "name" }, "description": "Sort field. Prefix with `-` for descending." }, { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Exact category match." }, { "name": "status", "in": "query", "schema": { "type": "integer" }, "description": "Record status. 1 = active." } ], "responses": { "200": { "description": "A page of services.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": 1, "name": "Engine Oil Service", "service_no": "SRV-001", "category": "Engine", "price": 80, "price_sst": 80, "sst": 0, "hours": 0.75, "skill_level": "junior", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } ], "meta": { "total": 8, "page": 1, "limit": 50, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Catalogue" ], "operationId": "createService", "summary": "Create a service", "description": "Creates a service in the workshop that owns the key. Requires the `write` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceInput" }, "example": { "name": "Engine Oil Service", "service_no": "SRV-001", "category": "Engine", "price": 80, "price_sst": 80, "sst": 0, "hours": 0.75, "skill_level": "junior" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Service" } } }, "example": { "data": { "id": 1, "name": "Engine Oil Service", "service_no": "SRV-001", "category": "Engine", "price": 80, "price_sst": 80, "sst": 0, "hours": 0.75, "skill_level": "junior", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/services/{id}": { "get": { "tags": [ "Catalogue" ], "operationId": "getService", "summary": "Retrieve a service", "description": "Fetch a single service by id. Ids from another workshop return `404`.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "responses": { "200": { "description": "The service.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Service" } } }, "example": { "data": { "id": 1, "name": "Engine Oil Service", "service_no": "SRV-001", "category": "Engine", "price": 80, "price_sst": 80, "sst": 0, "hours": 0.75, "skill_level": "junior", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Catalogue" ], "operationId": "updateService", "summary": "Update a service", "description": "Partial update — send only the fields you want to change. Requires the `write` scope.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceInput" }, "example": { "name": "Engine Oil Service", "service_no": "SRV-001" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Service" } } }, "example": { "data": { "id": 1, "name": "Engine Oil Service", "service_no": "SRV-001", "category": "Engine", "price": 80, "price_sst": 80, "sst": 0, "hours": 0.75, "skill_level": "junior", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Catalogue" ], "operationId": "deleteService", "summary": "Delete a service", "description": "Soft-deletes the record. Requires the `admin` scope.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "responses": { "204": { "description": "Deleted. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/suppliers": { "get": { "tags": [ "Inventory" ], "operationId": "listSuppliers", "summary": "List suppliers", "description": "Suppliers referenced by parts and purchase orders.", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Partial match across `name`, `company_reg`, `email` and `phone_no`." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "name", "-name", "created_at", "-created_at" ], "default": "name" }, "description": "Sort field. Prefix with `-` for descending." }, { "name": "status", "in": "query", "schema": { "type": "integer" }, "description": "Record status. 1 = active." }, { "name": "state", "in": "query", "schema": { "type": "string" }, "description": "Exact state match." } ], "responses": { "200": { "description": "A page of suppliers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Supplier" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": 1, "name": "Southern Auto Parts Sdn Bhd", "company_reg": "201801023456", "sales_p": "Mr Tan", "phone_no": "0377881234", "email": "sales@southernauto.example", "address_1": "Lot 12, Jalan Perindustrian 3", "address_2": null, "postcode": "47100", "city": "Puchong", "state": "Selangor", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } ], "meta": { "total": 8, "page": 1, "limit": 50, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Inventory" ], "operationId": "createSupplier", "summary": "Create a supplier", "description": "Creates a supplier in the workshop that owns the key. Requires the `write` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierInput" }, "example": { "name": "Southern Auto Parts Sdn Bhd", "company_reg": "201801023456", "sales_p": "Mr Tan", "phone_no": "0377881234", "email": "sales@southernauto.example", "address_1": "Lot 12, Jalan Perindustrian 3", "address_2": null, "postcode": "47100", "city": "Puchong", "state": "Selangor" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Supplier" } } }, "example": { "data": { "id": 1, "name": "Southern Auto Parts Sdn Bhd", "company_reg": "201801023456", "sales_p": "Mr Tan", "phone_no": "0377881234", "email": "sales@southernauto.example", "address_1": "Lot 12, Jalan Perindustrian 3", "address_2": null, "postcode": "47100", "city": "Puchong", "state": "Selangor", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/suppliers/{id}": { "get": { "tags": [ "Inventory" ], "operationId": "getSupplier", "summary": "Retrieve a supplier", "description": "Fetch a single supplier by id. Ids from another workshop return `404`.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "responses": { "200": { "description": "The supplier.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Supplier" } } }, "example": { "data": { "id": 1, "name": "Southern Auto Parts Sdn Bhd", "company_reg": "201801023456", "sales_p": "Mr Tan", "phone_no": "0377881234", "email": "sales@southernauto.example", "address_1": "Lot 12, Jalan Perindustrian 3", "address_2": null, "postcode": "47100", "city": "Puchong", "state": "Selangor", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Inventory" ], "operationId": "updateSupplier", "summary": "Update a supplier", "description": "Partial update — send only the fields you want to change. Requires the `write` scope.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierInput" }, "example": { "name": "Southern Auto Parts Sdn Bhd", "company_reg": "201801023456" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Supplier" } } }, "example": { "data": { "id": 1, "name": "Southern Auto Parts Sdn Bhd", "company_reg": "201801023456", "sales_p": "Mr Tan", "phone_no": "0377881234", "email": "sales@southernauto.example", "address_1": "Lot 12, Jalan Perindustrian 3", "address_2": null, "postcode": "47100", "city": "Puchong", "state": "Selangor", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Inventory" ], "operationId": "deleteSupplier", "summary": "Delete a supplier", "description": "Soft-deletes the record. Requires the `admin` scope.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "responses": { "204": { "description": "Deleted. No content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/purchase-orders": { "get": { "tags": [ "Inventory" ], "operationId": "listPurchaseOrders", "summary": "List purchase orders", "description": "Read-only view of procurement. Raising and receiving stock stays in the app so the stock ledger cannot be bypassed.", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Partial match across `po_no` and `supplier_invoice_no`." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "-created_at", "total", "-total", "ordered_at", "-ordered_at" ], "default": "-created_at" }, "description": "Sort field. Prefix with `-` for descending." }, { "name": "status", "in": "query", "schema": { "type": "integer" }, "description": "Purchase-order status." }, { "name": "supplier_id", "in": "query", "schema": { "type": "integer" }, "description": "Only orders to this supplier." }, { "name": "po_no", "in": "query", "schema": { "type": "string" }, "description": "Exact purchase-order number." } ], "responses": { "200": { "description": "A page of purchase orders.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseOrder" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": 1, "po_no": "PO-2609-0011", "supplier_id": 4, "supplier_name": "Southern Auto Parts Sdn Bhd", "supplier_invoice_no": "SAP-88213", "total": 1420, "tax_rate": 0, "discount": 0, "shipping_cost": 25, "status": 3, "notes": "Monthly filter restock.", "ordered_at": "2026-09-01T08:00:00Z", "approved_at": "2026-09-01T09:12:00Z", "paid_at": null, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } ], "meta": { "total": 8, "page": 1, "limit": 50, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/purchase-orders/{id}": { "get": { "tags": [ "Inventory" ], "operationId": "getPurchaseOrder", "summary": "Retrieve a purchase order", "description": "Fetch a single purchase order by id. Ids from another workshop return `404`.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "responses": { "200": { "description": "The purchase order.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PurchaseOrder" } } }, "example": { "data": { "id": 1, "po_no": "PO-2609-0011", "supplier_id": 4, "supplier_name": "Southern Auto Parts Sdn Bhd", "supplier_invoice_no": "SAP-88213", "total": 1420, "tax_rate": 0, "discount": 0, "shipping_cost": 25, "status": 3, "notes": "Monthly filter restock.", "ordered_at": "2026-09-01T08:00:00Z", "approved_at": "2026-09-01T09:12:00Z", "paid_at": null, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/mechanics": { "get": { "tags": [ "Workshop" ], "operationId": "listMechanics", "summary": "List mechanics", "description": "Read-only roster used to resolve `mechanic_id` on work orders.", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Partial match across `name`, `nickname`, `email` and `reg_no`." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "name", "-name", "created_at", "-created_at" ], "default": "name" }, "description": "Sort field. Prefix with `-` for descending." }, { "name": "status", "in": "query", "schema": { "type": "integer" }, "description": "Record status. 1 = active." } ], "responses": { "200": { "description": "A page of mechanics.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Mechanic" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": 1, "name": "Mohd Faizal bin Osman", "nickname": "Faizal", "email": "faizal@example.com", "phone_no": "0198887766", "reg_no": "MEC-003", "skill": "Brakes, suspension", "qualification": "SKM Level 3", "exp_year": "8", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } ], "meta": { "total": 8, "page": 1, "limit": 50, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mechanics/{id}": { "get": { "tags": [ "Workshop" ], "operationId": "getMechanic", "summary": "Retrieve a mechanic", "description": "Fetch a single mechanic by id. Ids from another workshop return `404`.", "parameters": [ { "$ref": "#/components/parameters/ResourceId" } ], "responses": { "200": { "description": "The mechanic.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Mechanic" } } }, "example": { "data": { "id": 1, "name": "Mohd Faizal bin Osman", "nickname": "Faizal", "email": "faizal@example.com", "phone_no": "0198887766", "reg_no": "MEC-003", "skill": "Brakes, suspension", "qualification": "SKM Level 3", "exp_year": "8", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Your secret key, e.g. `eng_live_…`. Preferred for server-to-server calls." }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "The same secret key sent as `Authorization: Bearer `." } }, "schemas": { "PageMeta": { "type": "object", "description": "Pagination block returned by every list endpoint.", "properties": { "total": { "type": "integer", "description": "Total records matching the query." }, "page": { "type": "integer", "description": "Current page (1-based)." }, "limit": { "type": "integer", "description": "Records per page." }, "total_pages": { "type": "integer", "description": "Number of pages available." } } }, "Error": { "type": "object", "description": "Every failure uses this envelope.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code." }, "message": { "type": "string", "description": "Human-readable explanation." }, "field": { "type": "string", "description": "The offending field, when the error is about one." } } } } }, "KeyContext": { "type": "object", "properties": { "workshop": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "key": { "type": "object", "properties": { "name": { "type": "string" }, "environment": { "type": "string", "enum": [ "live", "sandbox" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "last_used_at": { "type": "string", "format": "date-time" } } }, "plan": { "type": "string" }, "rate_limit": { "type": "object", "properties": { "limit": { "type": "integer" }, "window": { "type": "string" } } } } }, "Customer": { "type": "object", "title": "Customer", "description": "People and companies your workshop serves.", "properties": { "id": { "type": "integer", "description": "Unique customer id.", "readOnly": true }, "name": { "type": "string", "description": "Full name or company name." }, "phone": { "type": [ "string", "null" ], "description": "Contact number, without the country code." }, "country_code": { "type": [ "string", "null" ], "description": "Dialling code for `phone`, e.g. \"60\"." }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Contact email." }, "gender": { "type": [ "string", "null" ], "description": "Free-text gender as captured at the counter." }, "dob": { "type": [ "string", "null" ], "format": "date", "description": "Date of birth." }, "note": { "type": [ "string", "null" ], "description": "Internal note shown to counter staff." }, "status": { "type": [ "integer", "null" ], "description": "Record status. 1 = active." }, "vehicle_count": { "type": "integer", "description": "Vehicles currently registered to this customer." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created (ISO-8601, UTC).", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO-8601, UTC).", "readOnly": true } }, "example": { "id": 1, "name": "Nurul Aisyah binti Rahman", "phone": "123456789", "country_code": "60", "email": "aisyah@example.com", "gender": "female", "dob": "1991-04-18", "note": "Prefers WhatsApp reminders.", "status": 1, "vehicle_count": 2, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } }, "CustomerInput": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name or company name.", "maxLength": 120 }, "phone": { "type": "string", "description": "Contact number, without the country code.", "maxLength": 20 }, "country_code": { "type": "string", "description": "Dialling code for `phone`.", "maxLength": 6 }, "email": { "type": "string", "description": "Contact email.", "maxLength": 120 }, "gender": { "type": "string", "description": "Gender.", "maxLength": 20 }, "dob": { "type": "string", "description": "Date of birth (YYYY-MM-DD)." }, "note": { "type": "string", "description": "Internal note.", "maxLength": 500 } }, "required": [ "name" ] }, "Vehicle": { "type": "object", "title": "Vehicle", "description": "Vehicles registered against your customers.", "properties": { "id": { "type": "integer", "description": "Unique vehicle id.", "readOnly": true }, "customer_id": { "type": "integer", "description": "Owning customer." }, "customer_name": { "type": [ "string", "null" ], "description": "Owning customer name (read-only convenience)." }, "plate_no": { "type": "string", "description": "Registration plate." }, "chassis_no": { "type": [ "string", "null" ], "description": "VIN / chassis number." }, "ref_car_id": { "type": [ "integer", "null" ], "description": "Catalogue model id — see `GET /vehicle-models`." }, "make": { "type": [ "string", "null" ], "description": "Manufacturer, from the ENGARAGE vehicle catalogue." }, "model": { "type": [ "string", "null" ], "description": "Model, from the ENGARAGE vehicle catalogue." }, "segment": { "type": [ "string", "null" ], "description": "Vehicle segment, e.g. \"SUV\"." }, "fuel_type": { "type": [ "string", "null" ], "description": "Petrol, diesel, hybrid or EV." }, "year": { "type": [ "string", "null" ], "description": "Model year." }, "next_service": { "type": [ "string", "null" ], "format": "date", "description": "Next service due date." }, "status": { "type": [ "integer", "null" ], "description": "Record status. 1 = active." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created (ISO-8601, UTC).", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO-8601, UTC).", "readOnly": true } }, "example": { "id": 1, "customer_id": 1, "customer_name": "Nurul Aisyah binti Rahman", "plate_no": "WXY 1234", "chassis_no": "JHMCM56557C404453", "ref_car_id": 1, "make": "Perodua", "model": "Myvi 1.5 AV", "segment": "Hatchback", "fuel_type": "Petrol", "year": "2021", "next_service": "2026-12-01", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } }, "VehicleInput": { "type": "object", "properties": { "customer_id": { "type": "integer", "description": "Owning customer id." }, "plate_no": { "type": "string", "description": "Registration plate.", "maxLength": 20 }, "ref_car_id": { "type": "integer", "description": "Catalogue model id — look it up with `GET /vehicle-models`." }, "chassis_no": { "type": "string", "description": "VIN / chassis number.", "maxLength": 40 }, "year": { "type": "string", "description": "Model year.", "maxLength": 8 }, "next_service": { "type": "string", "description": "Next service due date." } }, "required": [ "customer_id", "plate_no", "ref_car_id" ] }, "VehicleModel": { "type": "object", "title": "Vehicle Model", "description": "ENGARAGE's shared make/model catalogue.", "properties": { "id": { "type": "integer", "description": "Catalogue id — this is the `ref_car_id` used when creating a vehicle.", "readOnly": true }, "make": { "type": [ "string", "null" ], "description": "Manufacturer." }, "model": { "type": [ "string", "null" ], "description": "Model and variant." }, "segment": { "type": [ "string", "null" ], "description": "Vehicle segment, e.g. \"SUV\"." }, "fuel_type": { "type": [ "string", "null" ], "description": "Petrol, diesel, hybrid or EV." }, "oil_capacity": { "type": [ "string", "null" ], "description": "Engine oil capacity, as published by the manufacturer." }, "car_battery": { "type": [ "string", "null" ], "description": "Recommended battery specification." }, "status": { "type": [ "integer", "null" ], "description": "Record status. 1 = active." } }, "example": { "id": 1, "make": "Perodua", "model": "Myvi 1.5 AV", "segment": "Hatchback", "fuel_type": "Petrol", "oil_capacity": "3.2L", "car_battery": "NS60", "status": 1 } }, "Booking": { "type": "object", "title": "Booking", "description": "Appointments customers have made with your workshop.", "properties": { "id": { "type": "integer", "description": "Unique booking id.", "readOnly": true }, "customer_id": { "type": [ "integer", "null" ], "description": "Customer who booked." }, "customer_name": { "type": [ "string", "null" ], "description": "Customer name (read-only convenience)." }, "vehicle_id": { "type": [ "integer", "null" ], "description": "Vehicle being brought in." }, "plate_no": { "type": [ "string", "null" ], "description": "Vehicle plate (read-only convenience)." }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Requested slot." }, "remark": { "type": [ "string", "null" ], "description": "What the customer wants done." }, "status": { "type": [ "integer", "null" ], "description": "Booking status. 1 = pending, 2 = accepted, 3 = rejected." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created (ISO-8601, UTC).", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO-8601, UTC).", "readOnly": true } }, "example": { "id": 1, "customer_id": 1, "customer_name": "Nurul Aisyah binti Rahman", "vehicle_id": 1, "plate_no": "WXY 1234", "scheduled_at": "2026-09-15T09:30:00Z", "remark": "Engine oil + filter, brakes squealing.", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } }, "BookingInput": { "type": "object", "properties": { "customer_id": { "type": "integer", "description": "Customer id." }, "vehicle_id": { "type": "integer", "description": "Vehicle id." }, "scheduled_at": { "type": "string", "description": "Requested slot (ISO-8601)." }, "remark": { "type": "string", "description": "What the customer wants done.", "maxLength": 500 }, "status": { "type": "integer", "description": "Booking status." } }, "required": [ "customer_id", "scheduled_at" ] }, "WorkOrder": { "type": "object", "title": "Work Order", "description": "Jobs on the shop floor, from booking through to paid.", "properties": { "id": { "type": "integer", "description": "Unique work-order id.", "readOnly": true }, "wo_no": { "type": [ "string", "null" ], "description": "Human-readable work-order number." }, "quotation_no": { "type": [ "string", "null" ], "description": "Quotation number, once quoted." }, "invoice_no": { "type": [ "string", "null" ], "description": "Invoice number, once invoiced." }, "status": { "type": "integer", "description": "Status code 1–10." }, "status_label": { "type": "string", "description": "Human label for `status`." }, "customer_id": { "type": [ "integer", "null" ], "description": "Customer the job is for." }, "customer_name": { "type": [ "string", "null" ], "description": "Customer name." }, "vehicle_id": { "type": [ "integer", "null" ], "description": "Vehicle in the bay." }, "plate_no": { "type": [ "string", "null" ], "description": "Vehicle plate." }, "mechanic_id": { "type": [ "integer", "null" ], "description": "Assigned mechanic." }, "bay_id": { "type": [ "integer", "null" ], "description": "Assigned bay." }, "complaint": { "type": [ "string", "null" ], "description": "The customer's reported problem." }, "remark": { "type": [ "string", "null" ], "description": "Internal note." }, "mileage": { "type": [ "string", "null" ], "description": "Odometer reading on arrival." }, "total_payment": { "type": [ "number", "null" ], "description": "Invoice total, including tax." }, "payment_sst": { "type": [ "number", "null" ], "description": "Tax portion of the total." }, "method": { "type": [ "string", "null" ], "description": "Payment method, once paid." }, "booking_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the job was booked." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When work finished." }, "invoiced_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the invoice was raised." }, "paid_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When payment was received." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created (ISO-8601, UTC).", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO-8601, UTC).", "readOnly": true } }, "example": { "id": 1, "wo_no": "WO-2609-0042", "quotation_no": "QT-2609-0031", "invoice_no": "INV-2609-0028", "status": 7, "status_label": "Paid", "customer_id": 1, "customer_name": "Nurul Aisyah binti Rahman", "vehicle_id": 1, "plate_no": "WXY 1234", "mechanic_id": 3, "bay_id": 2, "complaint": "Brakes squealing on cold start.", "remark": "Front pads replaced, discs skimmed.", "mileage": "86540", "total_payment": 486.5, "payment_sst": 0, "method": "card", "booking_at": "2026-09-15T09:30:00Z", "completed_at": "2026-09-15T15:10:00Z", "invoiced_at": "2026-09-15T15:22:00Z", "paid_at": "2026-09-15T15:40:00Z", "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } }, "WorkOrderInput": { "type": "object", "properties": { "status": { "type": "integer", "description": "Move the job along the status ladder." }, "mechanic_id": { "type": "integer", "description": "Assign a mechanic." }, "bay_id": { "type": "integer", "description": "Assign a bay." }, "remark": { "type": "string", "description": "Internal note.", "maxLength": 1000 }, "complaint": { "type": "string", "description": "The customer's reported problem.", "maxLength": 1000 }, "mileage": { "type": "string", "description": "Odometer reading.", "maxLength": 20 } } }, "WorkOrderItems": { "type": "object", "description": "Line items on a work order", "properties": { "id": { "type": "integer", "description": "Line-item id.", "readOnly": true }, "type": { "type": [ "string", "null" ], "description": "What is being billed: `part`, `package`, `service` or `misc`." }, "part_id": { "type": [ "integer", "null" ], "description": "Inventory part, when `type` is part." }, "service_id": { "type": [ "integer", "null" ], "description": "Service, when `type` is service." }, "package_id": { "type": [ "integer", "null" ], "description": "Package, when `type` is package." }, "quantity": { "type": [ "number", "null" ], "description": "Quantity billed." }, "total_price": { "type": [ "number", "null" ], "description": "Line total before discount." }, "total_discount": { "type": [ "number", "null" ], "description": "Discount applied to the line." }, "tax_rate": { "type": [ "number", "null" ], "description": "Tax rate applied, as a percentage." } }, "example": { "id": 5501, "type": "part", "part_id": 812, "service_id": null, "package_id": null, "quantity": 4, "total_price": 168, "total_discount": 0, "tax_rate": 0 } }, "Quotation": { "type": "object", "title": "Quotation", "description": "Priced estimates issued against a work order.", "properties": { "id": { "type": "integer", "description": "Unique quotation id.", "readOnly": true }, "quotation_no": { "type": [ "string", "null" ], "description": "Human-readable quotation number." }, "work_order_id": { "type": [ "integer", "null" ], "description": "Work order this quotes." }, "wo_no": { "type": [ "string", "null" ], "description": "Work-order number." }, "customer_id": { "type": [ "integer", "null" ], "description": "Customer quoted." }, "status": { "type": [ "integer", "null" ], "description": "Quotation status. 2 = accepted." }, "discount": { "type": [ "number", "null" ], "description": "Discount value applied." }, "deposit": { "type": [ "number", "null" ], "description": "Deposit collected." }, "deposit_method": { "type": [ "string", "null" ], "description": "How the deposit was paid." }, "deposit_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the deposit was collected." }, "total": { "type": [ "number", "null" ], "description": "Quoted total." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created (ISO-8601, UTC).", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO-8601, UTC).", "readOnly": true } }, "example": { "id": 1, "quotation_no": "QT-2609-0031", "work_order_id": 42, "wo_no": "WO-2609-0042", "customer_id": 1, "status": 2, "discount": 20, "deposit": 100, "deposit_method": "cash", "deposit_at": "2026-09-15T10:05:00Z", "total": 486.5, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } }, "Part": { "type": "object", "title": "Part", "description": "Stocked parts and consumables.", "properties": { "id": { "type": "integer", "description": "Unique part id.", "readOnly": true }, "name": { "type": "string", "description": "Part name." }, "part_no": { "type": [ "string", "null" ], "description": "Manufacturer or internal part number." }, "brand": { "type": [ "string", "null" ], "description": "Brand." }, "model": { "type": [ "string", "null" ], "description": "Vehicle model this fits." }, "variant": { "type": [ "string", "null" ], "description": "Variant / specification." }, "description": { "type": [ "string", "null" ], "description": "Longer description." }, "unit": { "type": [ "string", "null" ], "description": "Unit of measure, e.g. \"pcs\", \"litre\"." }, "bin_number": { "type": [ "string", "null" ], "description": "Storage location." }, "cost_price": { "type": [ "number", "null" ], "description": "What you pay your supplier." }, "price": { "type": [ "number", "null" ], "description": "What you charge the customer." }, "quantity": { "type": [ "number", "null" ], "description": "On-hand stock." }, "stock_alert_threshold": { "type": [ "number", "null" ], "description": "Level at which the part counts as low stock." }, "supplier_id": { "type": [ "integer", "null" ], "description": "Default supplier." }, "is_low_stock": { "type": "boolean", "description": "True when on-hand stock is at or below the threshold." }, "status": { "type": [ "integer", "null" ], "description": "Record status. 1 = active." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created (ISO-8601, UTC).", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO-8601, UTC).", "readOnly": true } }, "example": { "id": 1, "name": "Engine Oil Filter", "part_no": "OF-15400-RTA", "brand": "Denso", "model": "Myvi", "variant": "1.5L", "description": "Spin-on oil filter.", "unit": "pcs", "bin_number": "A-04-2", "cost_price": 12.5, "price": 24, "quantity": 36, "stock_alert_threshold": 10, "supplier_id": 4, "is_low_stock": false, "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } }, "PartInput": { "type": "object", "properties": { "name": { "type": "string", "description": "Part name.", "maxLength": 150 }, "part_no": { "type": "string", "description": "Part number. Must be unique within your workshop.", "maxLength": 80 }, "brand": { "type": "string", "description": "Brand.", "maxLength": 80 }, "model": { "type": "string", "description": "Vehicle model this fits.", "maxLength": 80 }, "variant": { "type": "string", "description": "Variant / specification.", "maxLength": 80 }, "description": { "type": "string", "description": "Longer description.", "maxLength": 500 }, "unit": { "type": "string", "description": "Unit of measure.", "maxLength": 20 }, "bin_number": { "type": "string", "description": "Storage location.", "maxLength": 40 }, "cost_price": { "type": "number", "description": "Supplier cost." }, "price": { "type": "number", "description": "Selling price." }, "quantity": { "type": "number", "description": "On-hand stock." }, "stock_alert_threshold": { "type": "number", "description": "Low-stock threshold." }, "supplier_id": { "type": "integer", "description": "Default supplier." } }, "required": [ "name" ] }, "Service": { "type": "object", "title": "Service", "description": "Labour and service items you sell.", "properties": { "id": { "type": "integer", "description": "Unique service id.", "readOnly": true }, "name": { "type": "string", "description": "Service name." }, "service_no": { "type": [ "string", "null" ], "description": "Internal service code." }, "category": { "type": [ "string", "null" ], "description": "Grouping, e.g. \"Engine\"." }, "price": { "type": [ "number", "null" ], "description": "Price before tax." }, "price_sst": { "type": [ "number", "null" ], "description": "Price including tax." }, "sst": { "type": [ "number", "null" ], "description": "Tax rate applied, as a percentage." }, "hours": { "type": [ "number", "null" ], "description": "Standard labour hours." }, "skill_level": { "type": [ "string", "null" ], "description": "Skill required to perform it." }, "status": { "type": [ "integer", "null" ], "description": "Record status. 1 = active." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created (ISO-8601, UTC).", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO-8601, UTC).", "readOnly": true } }, "example": { "id": 1, "name": "Engine Oil Service", "service_no": "SRV-001", "category": "Engine", "price": 80, "price_sst": 80, "sst": 0, "hours": 0.75, "skill_level": "junior", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } }, "ServiceInput": { "type": "object", "properties": { "name": { "type": "string", "description": "Service name.", "maxLength": 150 }, "service_no": { "type": "string", "description": "Internal service code.", "maxLength": 60 }, "category": { "type": "string", "description": "Grouping.", "maxLength": 80 }, "price": { "type": "number", "description": "Price before tax." }, "price_sst": { "type": "number", "description": "Price including tax." }, "sst": { "type": "number", "description": "Tax rate percentage." }, "hours": { "type": "number", "description": "Standard labour hours." }, "skill_level": { "type": "string", "description": "Skill required.", "maxLength": 40 } }, "required": [ "name" ] }, "Supplier": { "type": "object", "title": "Supplier", "description": "Vendors you buy parts from.", "properties": { "id": { "type": "integer", "description": "Unique supplier id.", "readOnly": true }, "name": { "type": "string", "description": "Supplier name." }, "company_reg": { "type": [ "string", "null" ], "description": "Company registration number." }, "sales_p": { "type": [ "string", "null" ], "description": "Sales contact person." }, "phone_no": { "type": [ "string", "null" ], "description": "Contact number." }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Contact email." }, "address_1": { "type": [ "string", "null" ], "description": "Address line 1." }, "address_2": { "type": [ "string", "null" ], "description": "Address line 2." }, "postcode": { "type": [ "string", "null" ], "description": "Postcode." }, "city": { "type": [ "string", "null" ], "description": "City." }, "state": { "type": [ "string", "null" ], "description": "State." }, "status": { "type": [ "integer", "null" ], "description": "Record status. 1 = active." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created (ISO-8601, UTC).", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO-8601, UTC).", "readOnly": true } }, "example": { "id": 1, "name": "Southern Auto Parts Sdn Bhd", "company_reg": "201801023456", "sales_p": "Mr Tan", "phone_no": "0377881234", "email": "sales@southernauto.example", "address_1": "Lot 12, Jalan Perindustrian 3", "address_2": null, "postcode": "47100", "city": "Puchong", "state": "Selangor", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } }, "SupplierInput": { "type": "object", "properties": { "name": { "type": "string", "description": "Supplier name.", "maxLength": 150 }, "company_reg": { "type": "string", "description": "Company registration number.", "maxLength": 60 }, "sales_p": { "type": "string", "description": "Sales contact person.", "maxLength": 120 }, "phone_no": { "type": "string", "description": "Contact number.", "maxLength": 20 }, "email": { "type": "string", "description": "Contact email.", "maxLength": 120 }, "address_1": { "type": "string", "description": "Address line 1.", "maxLength": 180 }, "address_2": { "type": "string", "description": "Address line 2.", "maxLength": 180 }, "postcode": { "type": "string", "description": "Postcode.", "maxLength": 12 }, "city": { "type": "string", "description": "City.", "maxLength": 80 }, "state": { "type": "string", "description": "State.", "maxLength": 80 } }, "required": [ "name" ] }, "PurchaseOrder": { "type": "object", "title": "Purchase Order", "description": "Orders raised against your suppliers.", "properties": { "id": { "type": "integer", "description": "Unique purchase-order id.", "readOnly": true }, "po_no": { "type": [ "string", "null" ], "description": "Purchase-order number." }, "supplier_id": { "type": [ "integer", "null" ], "description": "Supplier ordered from." }, "supplier_name": { "type": [ "string", "null" ], "description": "Supplier name." }, "supplier_invoice_no": { "type": [ "string", "null" ], "description": "The supplier's own invoice number." }, "total": { "type": [ "number", "null" ], "description": "Order total." }, "tax_rate": { "type": [ "number", "null" ], "description": "Tax rate applied, as a percentage." }, "discount": { "type": [ "number", "null" ], "description": "Discount applied." }, "shipping_cost": { "type": [ "number", "null" ], "description": "Shipping charged." }, "status": { "type": [ "integer", "null" ], "description": "Purchase-order status." }, "notes": { "type": [ "string", "null" ], "description": "Internal note." }, "ordered_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the order was raised." }, "approved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was approved." }, "paid_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was paid." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created (ISO-8601, UTC).", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO-8601, UTC).", "readOnly": true } }, "example": { "id": 1, "po_no": "PO-2609-0011", "supplier_id": 4, "supplier_name": "Southern Auto Parts Sdn Bhd", "supplier_invoice_no": "SAP-88213", "total": 1420, "tax_rate": 0, "discount": 0, "shipping_cost": 25, "status": 3, "notes": "Monthly filter restock.", "ordered_at": "2026-09-01T08:00:00Z", "approved_at": "2026-09-01T09:12:00Z", "paid_at": null, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } }, "Mechanic": { "type": "object", "title": "Mechanic", "description": "Technicians on your team.", "properties": { "id": { "type": "integer", "description": "Unique mechanic id.", "readOnly": true }, "name": { "type": [ "string", "null" ], "description": "Full name." }, "nickname": { "type": [ "string", "null" ], "description": "Name shown on the shop-floor board." }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Email." }, "phone_no": { "type": [ "string", "null" ], "description": "Contact number." }, "reg_no": { "type": [ "string", "null" ], "description": "Staff / registration number." }, "skill": { "type": [ "string", "null" ], "description": "Skills, as captured on the profile." }, "qualification": { "type": [ "string", "null" ], "description": "Qualifications." }, "exp_year": { "type": [ "string", "null" ], "description": "Years of experience." }, "status": { "type": [ "integer", "null" ], "description": "Record status. 1 = active." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created (ISO-8601, UTC).", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "When the record last changed (ISO-8601, UTC).", "readOnly": true } }, "example": { "id": 1, "name": "Mohd Faizal bin Osman", "nickname": "Faizal", "email": "faizal@example.com", "phone_no": "0198887766", "reg_no": "MEC-003", "skill": "Brakes, suspension", "qualification": "SKM Level 3", "exp_year": "8", "status": 1, "created_at": "2026-09-01T08:15:00Z", "updated_at": "2026-09-06T11:42:00Z" } } }, "parameters": { "Page": { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page to fetch, 1-based." }, "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Records per page." }, "ResourceId": { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Record id." } }, "responses": { "Unauthorized": { "description": "The key is missing, invalid, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Invalid API key." } } } } }, "Forbidden": { "description": "The key lacks the required scope, or the workshop is not on a plan that includes the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not have the `write` scope." } } } } }, "NotFound": { "description": "No such record in your workshop.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No customer found with id 999." } } } } }, "Conflict": { "description": "The request cannot be applied in this state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Only sandbox keys can reset the sandbox." } } } } }, "ValidationError": { "description": "The request body or query string failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_error", "message": "The name field is required.", "field": "name" } } } } }, "RateLimited": { "description": "Too many requests. See `retry_after`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Retry in 12s." } } } } } } } }