Incidents

Per-order incidents raised by either participant. An incident is an immutable record — type, optional description, author, and timestamp — with no lifecycle. Paths are relative to the /api/v1 prefix; all routes require Authorization: Bearer {token}.

Both endpoints are restricted to the order's participants (its customer or assigned driver). See the Orders resource.

See Common errors.

Endpoints

Method URI Role Description
POST /orders/{orderId}/incidents any Report an incident (order participant)
GET /orders/{orderId}/incidents any List the order's incidents (participant)

POST /orders/{orderId}/incidents

Reports an incident on the order. The response carries the caller's reporter_role (CLIENT or DRIVER).

Request body

Field Type Required Rules
type string yes one of ACCESO_BLOQUEADO, CLIENTE_NO_RESPONDE, DIRECCION_INCORRECTA, PROBLEMA_VEHICULO, AGUA_INSUFICIENTE, PROBLEMA_PAGO, OTRO
description string conditional required when type=OTRO; otherwise optional/nullable, ≤ 1000 chars

Response 201

{
  "incident": {
    "id": 7,
    "type": "ACCESO_BLOQUEADO",
    "description": null,
    "reporter_role": "DRIVER",
    "reporter": { "id": 3, "name": "Carlos RodrĂ­guez" },
    "created_at": "2026-06-26T12:30:00+00:00"
  }
}

Errors

Status Body When
404 { "error": "OrderNotFound" } Unknown order
403 { "error": "Forbidden", "message": "No participas en este pedido." } Caller is not a participant of the order

GET /orders/{orderId}/incidents

Lists the order's incidents, newest first.

Response 200

{
  "incidents": [
    {
      "id": 7,
      "type": "ACCESO_BLOQUEADO",
      "description": null,
      "reporter_role": "DRIVER",
      "reporter": { "id": 3, "name": "Carlos RodrĂ­guez" },
      "created_at": "2026-06-26T12:30:00+00:00"
    }
  ]
}

Errors

Status Body When
404 { "error": "OrderNotFound" } Unknown order
403 { "error": "Forbidden", "message": "No participas en este pedido." } Caller is not a participant of the order

Examples

# Driver reports a blocked access
curl -X POST /api/v1/orders/42/incidents \
  -H "Authorization: Bearer {driver_token}" \
  -H "Content-Type: application/json" \
  -d '{"type": "ACCESO_BLOQUEADO"}'

# "OTRO" requires a description
curl -X POST /api/v1/orders/42/incidents \
  -H "Authorization: Bearer {driver_token}" \
  -H "Content-Type: application/json" \
  -d '{"type": "OTRO", "description": "Portón dañado, sin acceso vehicular."}'