Conductores

Administra a las personas que operan los vehículos de tu flota — lista, crea y actualiza perfiles de conductores.

Requisitos previos

Todos los endpoints requieren un token JWT válido, una clave de API y el encabezado tenant. Consultá Autenticación.

Listar conductores

Obtiene una lista paginada de conductores con soporte de filtrado.

GET/apidev/v1/fleet/drivers

PermisoAPICLI_FLEET_DRIVERS_READ

Límite de solicitudes30 solicitudes/min (ventana deslizante)

Caché120s

Parámetros de consulta

Parámetro	Tipo	Requerido	Por defecto	Descripción
`limit`	integer	No	`25`	Registros por página. Mín: `1`, Máx: `100`
`offset`	integer	No	`0`	Registros a omitir
`status`	string	No	—	`A` (activo) o `I` (inactivo)
`name`	string	No	—	Coincidencia parcial sobre el nombre o correo del conductor. Longitud máxima 80
`document`	string	No	—	Coincidencia parcial sobre el número de documento. Longitud máxima 30
`driver_group`	string	No	—	Coincidencia parcial sobre el nombre del grupo de conductores. Longitud máxima 80

Campos de la respuesta

Campo	Tipo	Descripción
`id`	string	Identificador único del conductor (BigInt como string)
`name`	string \| null	Nombre completo del conductor
`document`	string \| null	Número de documento de identidad
`email`	string \| null	Dirección de correo electrónico
`phone`	string \| null	Número de teléfono
`image_url`	string \| null	URL de la foto del conductor
`external_code`	string \| null	Código de integración externa
`active`	boolean	Si el conductor está activo actualmente
`status`	string	`"A"` (activo) o `"I"` (inactivo)
`driver_group`	string \| null	Grupo o categoría del conductor
`assigned_vehicle`	object \| null	Vehículo asignado (ver más abajo)

Objeto assigned_vehicle:

Campo	Tipo	Descripción
`id`	string	Identificador del vehículo
`name`	string \| null	Nombre para mostrar del vehículo
`license_plate`	string \| null	Patente del vehículo

Ejemplo de código

cURL
JavaScript
Python

curl -s "https://$TENANT/apidev/v1/fleet/drivers?limit=10&status=A" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

const response = await fetch(
  `https://${TENANT}/apidev/v1/fleet/drivers?limit=10&status=A`,
  { headers }
);

const { data, meta } = await response.json();
console.log(`Fetched ${data.length} of ${meta.total} drivers`);

response = requests.get(
    f"https://{TENANT}/apidev/v1/fleet/drivers",
    headers=headers,
    params={"limit": 10, "status": "A"},
)

result = response.json()
for driver in result["data"]:
    vehicle = driver["assigned_vehicle"]
    print(f"{driver['name']} — {vehicle['name'] if vehicle else 'Unassigned'}")

Respuesta de ejemplo

{
  "success": true,
  "data": [
    {
      "id": "104820579455",
      "name": "Carlos Martinez",
      "document": "12345678",
      "email": "carlos@company.com",
      "phone": "+59899654321",
      "image_url": null,
      "external_code": "DRV-042",
      "active": true,
      "status": "A",
      "driver_group": "Long Haul",
      "assigned_vehicle": {
        "id": "104820579301",
        "name": "Movil 10",
        "license_plate": "ABC123"
      }
    },
    {
      "id": "104820579460",
      "name": "Maria Lopez",
      "document": "87654321",
      "email": "maria@company.com",
      "phone": "+59899123456",
      "image_url": null,
      "external_code": null,
      "active": true,
      "status": "A",
      "driver_group": "Urban",
      "assigned_vehicle": null
    }
  ],
  "meta": {
    "total": 28,
    "limit": 10,
    "offset": 0
  }
}

Crear conductor

Crea un nuevo perfil de conductor. Solo name es requerido.

POST/apidev/v1/fleet/drivers

PermisoAPICLI_FLEET_DRIVERS_WRITE

Límite de solicitudes30 solicitudes/min (ventana deslizante)

CachéNinguna

Cuerpo de la solicitud

Campo	Tipo	Requerido	Longitud máxima	Descripción
`name`	string	Sí	200	Nombre completo del conductor
`document`	string	No	100	Número de documento de identidad
`document_type`	number	No	—	Identificador del tipo de documento
`email`	string	No	200	Dirección de correo electrónico
`phone`	string	No	50	Número de teléfono fijo
`mobile`	string	No	50	Número de teléfono móvil
`status`	string	No	10	`"A"` o `"I"` (por defecto: `"A"`)
`driver_type_id`	string	No	40	Identificador de la categoría del conductor
`vehicle_id`	string	No	40	Vehículo a asignar
`supervisor_id`	string	No	40	Conductor supervisor
`external_code`	string	No	100	Código de integración externa
`ibutton`	string	No	100	Código de identificación iButton
`pin`	string	No	20	PIN del conductor
`notes`	string	No	2000	Notas de texto libre
`image_url`	string	No	500	URL de la foto del conductor
`street`	string	No	200	Dirección de la calle
`street_number`	string	No	20	Número de la calle
`apartment`	string	No	20	Apartamento o unidad
`corner`	string	No	200	Esquina
`country_id`	string	No	40	Identificador del país
`department_id`	string	No	40	Identificador del departamento/estado
`latitude`	string	No	40	Latitud del domicilio
`longitude`	string	No	40	Longitud del domicilio
`birth_date`	string	No	20	Fecha de nacimiento (ISO 8601)
`hire_date`	string	No	20	Fecha de contratación (ISO 8601)
`termination_date`	string	No	20	Fecha de baja (ISO 8601)
`legal_name`	string	No	200	Razón social/nombre legal
`tax_id`	string	No	50	Número de identificación fiscal

Ejemplo de código

cURL
JavaScript
Python

curl -s -X POST "https://$TENANT/apidev/v1/fleet/drivers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Carlos Martinez",
    "document": "12345678",
    "document_type": 1,
    "email": "carlos@company.com",
    "mobile": "+59899654321",
    "vehicle_id": "104820579301"
  }'

const response = await fetch(
  `https://${TENANT}/apidev/v1/fleet/drivers`,
  {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Carlos Martinez",
      document: "12345678",
      document_type: 1,
      email: "carlos@company.com",
      mobile: "+59899654321",
      vehicle_id: "104820579301",
    }),
  }
);

const { data } = await response.json();
console.log(`Driver created with ID: ${data.id}`);

response = requests.post(
    f"https://{TENANT}/apidev/v1/fleet/drivers",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "name": "Carlos Martinez",
        "document": "12345678",
        "document_type": 1,
        "email": "carlos@company.com",
        "mobile": "+59899654321",
        "vehicle_id": "104820579301",
    },
)

result = response.json()
print(f"Driver created with ID: {result['data']['id']}")

Respuesta de ejemplo — `201 Created`

{
  "success": true,
  "data": {
    "id": "104820579499"
  }
}

Actualizar conductor

Actualiza un perfil de conductor. Enviá solo los campos que quieras cambiar. Enviá null para limpiar un campo que admita nulos.

PUT/apidev/v1/fleet/drivers/{id}

PermisoAPICLI_FLEET_DRIVERS_WRITE

Límite de solicitudes30 solicitudes/min (ventana deslizante)

CachéNinguna

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
`id`	string	Sí	Identificador único del conductor

Cuerpo de la solicitud

Se aceptan todos los campos de Crear conductor, pero ninguno es requerido. Consultá Actualizaciones parciales para el patrón general.

Ejemplo de código

cURL
JavaScript
Python

curl -s -X PUT "https://$TENANT/apidev/v1/fleet/drivers/104820579455" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new.email@company.com",
    "phone": null,
    "vehicle_id": "104820579315"
  }'

const response = await fetch(
  `https://${TENANT}/apidev/v1/fleet/drivers/104820579455`,
  {
    method: "PUT",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({
      email: "new.email@company.com",
      phone: null,
      vehicle_id: "104820579315",
    }),
  }
);

const { data } = await response.json();
console.log(`Updated: ${data.updated_fields.join(", ")}`);

response = requests.put(
    f"https://{TENANT}/apidev/v1/fleet/drivers/104820579455",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "email": "new.email@company.com",
        "phone": None,
        "vehicle_id": "104820579315",
    },
)
print(response.json()["data"]["updated_fields"])

Respuesta de ejemplo

{
  "success": true,
  "data": {
    "id": "104820579455",
    "updated_fields": ["email", "phone", "vehicle_id"]
  },
  "meta": {}
}

Errores

Código	HTTP	Aplica a	Descripción
`VALIDATION_ERROR`	400	Listar, Crear, Actualizar	Parámetros o cuerpo inválidos (p. ej., falta `name` al crear, `limit` > 100)
`UNAUTHORIZED`	401	Todos	tenant / Authorization / X-API-Key ausente, inválido o expirado
`FORBIDDEN`	403	Todos	El usuario no tiene `APICLI_FLEET_DRIVERS_READ` o `APICLI_FLEET_DRIVERS_WRITE`
`NOT_FOUND`	404	Actualizar	El ID del conductor no existe o no pertenece a tu tenant
`RATE_LIMITED`	429	Todos	Se superaron 30 solicitudes/min

API de Dispositivos — Administra los dispositivos GPS asignados a los conductores
Telemetría — Ingesta posiciones GPS desde los dispositivos
Paginación — Parámetros estándar de paginación
Actualizaciones parciales — Cómo funcionan los endpoints PUT

Listar conductores​

Parámetros de consulta​

Campos de la respuesta​

Ejemplo de código​

Respuesta de ejemplo​

Crear conductor​

Cuerpo de la solicitud​

Ejemplo de código​

Respuesta de ejemplo — 201 Created​

Actualizar conductor​

Parámetros de ruta​

Cuerpo de la solicitud​

Ejemplo de código​

Respuesta de ejemplo​

Errores​

Relacionado​

Listar conductores

Parámetros de consulta

Campos de la respuesta

Ejemplo de código

Respuesta de ejemplo

Crear conductor

Cuerpo de la solicitud

Ejemplo de código

Respuesta de ejemplo — `201 Created`

Actualizar conductor

Parámetros de ruta

Cuerpo de la solicitud

Ejemplo de código

Respuesta de ejemplo

Errores

Relacionado