Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Codefied-CodePix/Karokar-backend/llms.txt

Use this file to discover all available pages before exploring further.

The Assignments API exposes the employee-facing side of KaroKar’s vehicle handover model. An Assignment record is never created directly via this API — it is produced automatically by the AssignmentService when the bookings module emits a BookingAssigned domain event (triggered by PATCH /bookings/:id/assign). This event-driven design keeps the booking and assignment modules loosely coupled: the booking module owns the approval workflow while the assignment module owns the employee acceptance lifecycle. Once an assignment exists, this API lets callers retrieve its current state and lets the assigned employee accept it.
All requests require an Authorization: Bearer <token> header. The assignment.accept permission is required to accept an assignment; retrieval requires only a valid token.

​
AssignmentStatus Values

An assignment moves through the following statuses during its lifecycle:
StatusMeaning
PENDINGAssignment created; awaiting employee acceptance.
ACCEPTEDEmployee has accepted the vehicle handover.
REJECTEDEmployee rejected the assignment (transition not yet exposed via HTTP).
ACTIVEHandover is in progress (set by downstream activation).
COMPLETEDAssignment concluded normally.
CLOSEDAssignment closed by an administrative action.
The REJECTED, ACTIVE, COMPLETED, and CLOSED transitions are managed internally by the platform and are not currently exposed as HTTP endpoints.

​
Assignment Entity Fields

Every Assignment response object contains the following fields:
​
id
string (UUID)
Unique identifier for the assignment, auto-generated.
​
bookingId
string (UUID) | null
UUID of the booking that triggered this assignment, or null if the assignment was created outside the booking workflow.
​
vehicleId
string (UUID)
UUID of the vehicle being assigned to the employee.
​
corporateOrganizationId
string (UUID)
UUID of the corporate organisation under which the assignment is made.
​
employeeId
string (UUID)
UUID of the employee receiving the vehicle.
​
status
AssignmentStatus
Current lifecycle status of the assignment. See the status table above.
​
startDate
string (ISO 8601)
The date-time from which the assignment is effective.
​
endDate
string (ISO 8601) | null
The date-time at which the assignment is expected to end, or null for open-ended assignments.
​
createdAt
string (ISO 8601)
Timestamp when the assignment record was created.
​
updatedAt
string (ISO 8601)
Timestamp of the last update to the assignment record.

​
GET /assignments/:id

Retrieve a single assignment by its UUID. No special permission is required beyond a valid authentication token. Required permission: none

​
Path Parameters

​
id
string (UUID)
required
UUID of the assignment to retrieve.

​
Response

Returns the Assignment object if found, or null if no assignment with the given UUID exists.

​
Example

curl http://localhost:3000/assignments/e5f6a7b8-c9d0-1234-efab-345678901234 \
  -H "Authorization: Bearer <token>"

{
  "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "bookingId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "vehicleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "corporateOrganizationId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "employeeId": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "status": "PENDING",
  "startDate": "2025-09-01T08:00:00.000Z",
  "endDate": "2025-09-30T17:00:00.000Z",
  "createdAt": "2025-08-20T10:35:00.000Z",
  "updatedAt": "2025-08-20T10:35:00.000Z"
}

​
PATCH /assignments/:id/accept

Accept an assignment on behalf of the assigned employee, indicating that they acknowledge the vehicle handover. The caller must hold the assignment.accept permission. Required permission: assignment.accept
This endpoint is currently wired in the controller and router but the underlying acceptAssignment service method is marked as NotImplementedException. The endpoint will return 501 Not Implemented until the service logic is completed.

​
Path Parameters

​
id
string (UUID)
required
UUID of the assignment to accept.

​
Request Body

No request body required.

​
Response

Returns the updated Assignment object with status: "ACCEPTED" once the service implementation is complete.

​
Errors

HTTPCodeCondition
403—Caller lacks assignment.accept permission
404—Assignment not found
501—Service method not yet implemented

​
Example

curl -X PATCH http://localhost:3000/assignments/e5f6a7b8-c9d0-1234-efab-345678901234/accept \
  -H "Authorization: Bearer <token>"

​
Event-Driven Creation

Assignments are not created through a direct HTTP POST endpoint. Instead, the following sequence occurs automatically:
  1. A vendor operator calls PATCH /bookings/:id/assign with an employeeId.
  2. The BookingService transitions the booking to ASSIGNED status and emits a BookingAssigned domain event.
  3. An event listener inside the assignments module handles the booking.assigned event and calls AssignmentService.createAssignment(input).
  4. The new Assignment is persisted with status: PENDING and the AssignmentCreated event is emitted.
// CreateAssignmentInput (internal — not an HTTP body)
{
  bookingId: string | null;
  vehicleId: string;
  corporateOrganizationId: string;
  employeeId: string;
  startDate: Date;
  endDate?: Date | null;
}
After calling PATCH /bookings/:id/assign, poll GET /bookings/:id to confirm the ASSIGNED status, then use the booking’s metadata to discover the resulting assignment ID via your own query layer or a webhook subscription.

Build docs developers (and LLMs) love

Get started for freeTalk to us