REST API v1

Documentación de la API

Conecta tus sistemas a Rutas20 mediante nuestra API REST. Gestiona viajes, usuarios, tickets de soporte y registros de combustible desde cualquier plataforma.

Base URL https://rutas20.com/api/v1/

Autenticación

Todas las peticiones deben incluir una API key válida en el header Authorization. Puedes generar y gestionar tus claves desde el panel de API Keys.

GET /api/v1/viajes/
Ejemplo de header 
Authorization: Bearer ruta20_AbCdEfGh1234...
Importante: Las API keys tienen acceso completo a los datos. Nunca las compartas ni las expongas en código cliente (frontend/app móvil pública).

Códigos de error

Todos los errores devuelven JSON con el campo error.

Código Significado
200OK — operación exitosa
201Created — recurso creado
204No Content — eliminado correctamente
400Bad Request — datos inválidos o campos faltantes
401Unauthorized — API key inválida o ausente
404Not Found — recurso no encontrado
405Method Not Allowed — método HTTP no soportado

Viajes

Gestiona los viajes/rutas de la flota.

GET /api/v1/viajes/ Listar todos los viajes
Respuesta 200
{
  "count": 2,
  "results": [
    {
      "id": 1,
      "titulo": "Madrid → Valencia",
      "codigo_seguimiento": "ABC123DEF456",
      "estado": "en_proceso",
      "fecha": "2026-05-02",
      "hora_salida": "08:00:00",
      "notas": "",
      "chofer_id": 3,
      "chofer": "Juan García",
      "cliente_id": 5,
      "cliente": "Empresa SL",
      "vehiculo_id": 2,
      "creado": "2026-05-01T10:00:00+00:00",
      "actualizado": "2026-05-02T08:05:00+00:00"
    }
  ]
}
POST /api/v1/viajes/ Crear un viaje
Body (JSON)
{
  "titulo": "Barcelona → Bilbao",
  "chofer_id": 3,
  "vehiculo_id": 2,
  "fecha": "2026-05-10",
  "hora_salida": "07:30",  // opcional
  "cliente_id": 5,         // opcional
  "notas": "Carga frágil", // opcional
  "estado": "pendiente"    // opcional
}
Respuesta 201
{
  "id": 42,
  "titulo": "Barcelona → Bilbao",
  "codigo_seguimiento": "XYZ987...",
  "estado": "pendiente",
  ...
}
GET /api/v1/viajes/{id}/ Obtener un viaje
Respuesta 200
{ "id": 1, "titulo": "...", ... }
PUT /api/v1/viajes/{id}/ Actualizar un viaje (también acepta PATCH para campos parciales)
Body (JSON) — solo los campos que quieras cambiar
{ "estado": "finalizado", "notas": "Entregado sin incidencias" }
DELETE /api/v1/viajes/{id}/ Eliminar un viaje — devuelve 204

Valores válidos para estado

pendiente aceptado iniciado en_proceso finalizado

Usuarios

CRUD completo de usuarios de la plataforma.

Método Endpoint Descripción
GET /api/v1/usuarios/ Lista todos los usuarios
POST /api/v1/usuarios/ Crea un usuario. Campos: username, password (obligatorios) + first_name, last_name, email
GET /api/v1/usuarios/{id}/ Obtiene un usuario
PUT/PATCH /api/v1/usuarios/{id}/ Actualiza campos: first_name, last_name, email, is_active, password
DELETE /api/v1/usuarios/{id}/ Elimina el usuario — devuelve 204
Ejemplo respuesta GET /api/v1/usuarios/1/
{
  "id": 1,
  "username": "jgarcia",
  "first_name": "Juan",
  "last_name": "García",
  "email": "jgarcia@empresa.com",
  "is_active": true,
  "rol": "chofer",
  "date_joined": "2026-01-15T09:00:00+00:00"
}

Tickets

Gestiona tickets de soporte e incidencias.

Método Endpoint Descripción
GET /api/v1/tickets/ Lista todos los tickets
POST /api/v1/tickets/ Crea un ticket. Campos: titulo, descripcion, usuario_id (obligatorios)
GET /api/v1/tickets/{id}/ Obtiene un ticket
PUT/PATCH /api/v1/tickets/{id}/ Actualiza: titulo, descripcion, estado, respuesta
DELETE /api/v1/tickets/{id}/ Elimina el ticket — devuelve 204

Valores válidos para estado

borrador enviado revisando respondido
Ejemplo respuesta GET /api/v1/tickets/1/
{
  "id": 1,
  "codigo": "TK/0001",
  "titulo": "Error al registrar viaje",
  "descripcion": "Al guardar aparece error 500",
  "estado": "revisando",
  "respuesta": "",
  "usuario_id": 4,
  "usuario": "Ana Martínez",
  "creado": "2026-04-20T14:30:00+00:00",
  "actualizado": "2026-04-21T09:00:00+00:00"
}

Combustible

Registros de repostaje de la flota.

Método Endpoint Descripción
GET /api/v1/combustible/ Lista todos los registros
POST /api/v1/combustible/ Crea un registro. Campos: vehiculo_id, odometro, numero_ticket, litros
GET /api/v1/combustible/{id}/ Obtiene un registro
PUT/PATCH /api/v1/combustible/{id}/ Actualiza: vehiculo_id, odometro, numero_ticket, litros
DELETE /api/v1/combustible/{id}/ Elimina el registro — devuelve 204
Ejemplo respuesta GET /api/v1/combustible/
{
  "count": 1,
  "results": [
    {
      "id": 1,
      "secuencia": "RC/0001",
      "vehiculo_id": 2,
      "vehiculo": "MAN TGX · ABC-1234",
      "odometro": "125430.0",
      "numero_ticket": "T-982",
      "litros": "80.50",
      "registrado_por_id": 3,
      "creado": "2026-05-01T07:00:00+00:00",
      "actualizado": "2026-05-01T07:00:00+00:00"
    }
  ]
}

Ejemplo cURL

Ejemplos listos para copiar y probar desde terminal.

Listar viajes
curl -H "Authorization: Bearer TU_API_KEY" \
     https://rutas20.com/api/v1/viajes/
Crear un viaje
curl -X POST \
     -H "Authorization: Bearer TU_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"titulo":"Sevilla → Cádiz","chofer_id":3,"vehiculo_id":1,"fecha":"2026-05-15"}' \
     https://rutas20.com/api/v1/viajes/
Actualizar estado de un viaje
curl -X PATCH \
     -H "Authorization: Bearer TU_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"estado":"finalizado"}' \
     https://rutas20.com/api/v1/viajes/42/