Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/JorLOrT/rappi2/llms.txt

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

The Assignments API is the operational core of the Rappi2 logistics platform. An assignment ties a single order, driver, and vehicle together for one delivery run. Creating an assignment enforces business rules across all three resources; the two lifecycle transitions (/iniciar and /finalizar) drive state changes on both the order and the driver automatically.

​
Business rules

Before an assignment can be created, all three referenced resources must satisfy the following conditions simultaneously:
ResourceRequired condition
Order (orden)estado = Pendiente
Driver (conductor)activo = true and disponibilidad = Disponible
Vehicle (vehiculo)activo = true and estado = Operativo
Any violation returns 400 with a descriptive message.

​
State machine

​
Assignment states

StateDescription
AsignadaAssignment created; driver and vehicle are booked.
EnCursoDelivery in progress; driver has left the pick-up point.
FinalizadaDelivery confirmed; driver is free again.
CanceladaAssignment cancelled before completion.
POST /asignaciones (crear)
  asignacion.estado  ──► Asignada
  orden.estado       ──► En Proceso
  conductor.disponibilidad ──► Ocupado

PATCH /asignaciones/{id}/iniciar
  asignacion.estado  ──► EnCurso
  orden.estado       ──► En Tránsito
  asignacion.fecha_inicio = now()

PATCH /asignaciones/{id}/finalizar
  asignacion.estado  ──► Finalizada
  orden.estado       ──► Entregado
  conductor.disponibilidad ──► Disponible
  asignacion.fecha_fin = now()
An assignment with estado = EnCurso cannot be deleted. Call /finalizar first, or wait for it to complete.

​
List assignments

​
GET /api/asignaciones
string
Returns a paginated list of assignments, optionally filtered by state or driver. Required permission: asignaciones:read

​
Query parameters

​
skip
integer
default:"0"
Number of records to skip for pagination.
​
limit
integer
default:"50"
Maximum number of records to return. Hard cap: 200.
​
estado
string
Filter by assignment state: Asignada, EnCurso, Finalizada, or Cancelada.
​
conductor_id
integer
Return only assignments for this driver.

​
Response 200

Array of assignment objects.
​
id
integer
required
Unique assignment identifier.
​
orden_id
integer
required
ID of the delivery order.
​
conductor_id
integer
required
ID of the assigned driver.
​
vehiculo_placa
string
required
Licence plate of the assigned vehicle.
​
estado
string
required
Current assignment state.
​
fecha_inicio
string (datetime)
Timestamp when /iniciar was called. null until then.
​
fecha_fin
string (datetime)
Timestamp when /finalizar was called. null until then.
curl "https://api.rappi2.com/api/asignaciones?estado=Asignada" \
  -H "Authorization: Bearer <token>"

​
Create an assignment

​
POST /api/asignaciones
string
Creates a new assignment. All three business-rule conditions (order Pendiente, driver Disponible, vehicle Operativo) are validated atomically. On success, the order advances to En Proceso and the driver is set to Ocupado. Required permission: asignaciones:write

​
Request body

​
orden_id
integer
required
ID of the order to assign. Must be in Pendiente state.
​
conductor_id
integer
required
ID of the driver to assign. Must be active and Disponible.
​
vehiculo_placa
string
required
Licence plate of the vehicle to use. Must be active and Operativo.

​
Response 201

The newly created assignment object. 
curl -X POST https://api.rappi2.com/api/asignaciones \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "orden_id": 101,
    "conductor_id": 5,
    "vehiculo_placa": "ABC-123"
  }'

​
Get an assignment

​
GET /api/asignaciones/{asignacion_id}
string
Returns a single assignment by ID. Returns 404 if not found. Required permission: asignaciones:read

​
Path parameters

​
asignacion_id
integer
required
Assignment ID.

​
Response 200

Assignment object. 
curl https://api.rappi2.com/api/asignaciones/88 \
  -H "Authorization: Bearer <token>"

​
Update an assignment

​
PATCH /api/asignaciones/{asignacion_id}
string
General-purpose partial update. For lifecycle transitions use the dedicated /iniciar and /finalizar endpoints instead, as they enforce state-machine rules and update related resources. Required permission: asignaciones:write

​
Path parameters

​
asignacion_id
integer
required
Assignment ID.

​
Request body

All fields are optional.
​
estado
string
New state: Asignada, EnCurso, Finalizada, or Cancelada.
​
fecha_inicio
string (datetime)
Manual override of the start timestamp.
​
fecha_fin
string (datetime)
Manual override of the end timestamp.

​
Response 200

Updated assignment object. 
curl -X PATCH https://api.rappi2.com/api/asignaciones/88 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"estado": "Cancelada"}'

​
Start a delivery

​
PATCH /api/asignaciones/{asignacion_id}/iniciar
string
Transitions the assignment from Asignada to EnCurso. Simultaneously advances the linked order to En Tránsito and records fecha_inicio. Returns 400 if the assignment is not currently Asignada. Required permission: asignaciones:write

​
Path parameters

​
asignacion_id
integer
required
Assignment ID. Must be in Asignada state.

​
Request body

No body required.

​
Response 200

Updated assignment object with estado = EnCurso and fecha_inicio set. 
curl -X PATCH https://api.rappi2.com/api/asignaciones/88/iniciar \
  -H "Authorization: Bearer <token>"

​
Finish a delivery

​
PATCH /api/asignaciones/{asignacion_id}/finalizar
string
Transitions the assignment from EnCurso to Finalizada. Simultaneously marks the order as Entregado, sets the driver back to Disponible, and records fecha_fin. Returns 400 if the assignment is not currently EnCurso. Required permission: asignaciones:write

​
Path parameters

​
asignacion_id
integer
required
Assignment ID. Must be in EnCurso state.

​
Request body

No body required.

​
Response 200

Updated assignment object with estado = Finalizada and fecha_fin set. 
curl -X PATCH https://api.rappi2.com/api/asignaciones/88/finalizar \
  -H "Authorization: Bearer <token>"

​
Cancel / delete an assignment

​
DELETE /api/asignaciones/{asignacion_id}
string
Permanently removes the assignment record along with any associated tracking and geofence data stored in MongoDB. Returns 400 if the assignment is currently EnCurso — call /finalizar first. Required permission: asignaciones:delete

​
Path parameters

​
asignacion_id
integer
required
Assignment ID. Must not be in EnCurso state.

​
Response 204

No body. 
curl -X DELETE https://api.rappi2.com/api/asignaciones/88 \
  -H "Authorization: Bearer <token>"

Build docs developers (and LLMs) love

Get started for freeTalk to us