Ratings

Rate the driver after a delivered order, read an order's rating, and (for drivers) fetch a rating summary. Paths are relative to the /api/v1 prefix; all routes require Authorization: Bearer {token}.

A delivered order's receipt embeds its rating once submitted.

See Common errors.

Endpoints

Method	URI	Role	Description
`POST`	`/ratings`	any	Rate the driver of a delivered order
`POST`	`/orders/{orderId}/rating`	any	Alias of `/ratings` (orderId from the path)
`GET`	`/ratings/order/{orderId}`	any	The caller's rating for an order (nullable)
`GET`	`/driver/rating`	DRIVER	The authenticated driver's rating summary

Only the order's customer may rate it, exactly once.

POST /ratings

Rates the driver of a delivered order. POST /orders/{orderId}/rating is an alias that supplies orderId from the path.

Request body

Field	Type	Required	Rules
`orderId`	integer	yes	the delivered order's id (the alias merges it from the route)
`score`	integer	yes	1–5
`tags`	string[]	no	up to 6 items, each ≤ 40 chars
`comment`	string	no	≤ 500 chars, nullable

Response 201

{
  "rating": {
    "id": 11,
    "order_id": 42,
    "from_user_id": 1,
    "to_driver_id": 3,
    "score": 5,
    "comment": "Puntual",
    "tags": ["fast", "friendly"],
    "created_at": "2026-06-26T12:45:00.000000Z",
    "updated_at": "2026-06-26T12:45:00.000000Z"
  },
  "driver": { "avgRating": 4.8, "totalRatings": 25 }
}

driver reflects the driver's current aggregates.

Errors

Status	Body	When
`404`	`{ "error": "OrderNotFound" }`	Unknown order
`403`	`{ "error": "Forbidden" }`	Caller is not the order's customer
`409`	`{ "error": "OrderNotDelivered" }`	Order has not been delivered
`409`	`{ "error": "NoDriverAssigned" }`	Order has no assigned driver
`409`	`{ "error": "AlreadyRated" }`	The order was already rated

/ratings is an alias of /orders/{orderId}/rating (identical behavior).

GET /ratings/order/{orderId}

Returns the caller's own rating for the given order, or null if they haven't rated it.

Response 200 — { "rating": { … } } or { "rating": null }.

GET /driver/rating

Rating summary for the authenticated driver: average, total, the 1–5 score distribution, and the latest commented ratings (anonymized — no rater identity).

Response 200

{
  "average": 4.8,
  "total": 25,
  "distribution": { "1": 0, "2": 1, "3": 2, "4": 5, "5": 17 },
  "recent": [
    { "score": 5, "comment": "Puntual", "tags": ["fast"], "created_at": "2026-06-26T12:45:00+00:00" }
  ]
}

Errors

Status	Body	When
`404`	`{ "error": "DriverNotFound" }`	The caller has no driver profile

Examples

# Rate the driver of a delivered order
curl -X POST /api/v1/ratings \
  -H "Authorization: Bearer {client_token}" \
  -H "Content-Type: application/json" \
  -d '{"orderId": 42, "score": 5, "tags": ["fast", "friendly"], "comment": "Puntual"}'