Inicio Rápido
La API de VIA permite a desarrolladores integrar funcionalidades de gestión de convoys, camiones, choferes y terminales en sus aplicaciones.
Base URL
https://via.handymanny.cloud/api
Requisitos
- Token JWT válido (obtenido vía
/api/auth/login) - Header
Authorization: Bearer {token}en cada request - Content-Type:
application/json
Ejemplo Rápido
Bash
# Login
curl -X POST https://via.handymanny.cloud/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"chavez684@gmail.com","password":"Password789!"}'
# Get convoys
curl -X GET https://via.handymanny.cloud/api/convoys \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
JavaScript
const response = await fetch('https://via.handymanny.cloud/api/auth/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: 'chavez684@gmail.com',
password: 'Password789!'
})
});
const { access_token } = await response.json();
// Use token for authenticated requests
const convoys = await fetch('https://via.handymanny.cloud/api/convoys', {
headers: { 'Authorization': `Bearer ${access_token}` }
});
Python
import requests
# Login
response = requests.post(
'https://via.handymanny.cloud/api/auth/login',
json={'email': 'chavez684@gmail.com', 'password': 'Password789!'}
)
token = response.json()['access_token']
# Get convoys
convoys = requests.get(
'https://via.handymanny.cloud/api/convoys',
headers={'Authorization': f'Bearer {token}'}
)
Autenticación
VIA utiliza JWT (JSON Web Tokens) para autenticación. Los tokens expiran después de 24 horas.
Importante: Todos los endpoints (excepto
/auth/login) requieren un token JWT válido en el header Authorization.
Flujo de Autenticación
- POST a
/api/auth/logincon email y password - Guardar el
access_tokenrecibido - Incluir token en todas las requests:
Authorization: Bearer {token} - Si el token expira (401 error), hacer login nuevamente
POST
/api/auth/login
Autenticar usuario y obtener token JWT
Request Body
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
email |
string | Sí | Email del usuario |
password |
string | Sí | Contraseña del usuario |
Response (200 OK)
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"user": {
"id": 1,
"email": "chavez684@gmail.com",
"role": "admin"
}
}
Generar API Key
Para aplicaciones de servidor a servidor, puedes generar una API key permanente que no expira.
Tu API Key
Haz clic para generar una nueva clave de API
Importante: Guarda tu API key en un lugar seguro. No podrás verla nuevamente después de cerrar esta página.
Uso de API Key
cURL
curl -X GET https://via.handymanny.cloud/api/convoys \
-H "X-API-Key: YOUR_API_KEY_HERE"
Endpoints Disponibles
VIA API ofrece 46 endpoints organizados en 8 categorías:
Auth (2)
Login, verificación JWT
Convoys (8)
CRUD completo de convoys
Camiones (8)
Gestión de camiones
Choferes (8)
Gestión de choferes
Terminales (8)
Gestión de terminales
Patios (8)
Gestión de patios
Empresas (2)
Gestión de empresas
Usuarios (2)
Gestión de usuarios
Convoy Endpoints
GET
/api/convoys
Obtener lista de todos los convoys con filtros opcionales
Query Parameters
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
status |
string | No | Filtrar por estado: formando, listo, en_ruta, completado |
terminal_id |
integer | No | Filtrar por terminal de origen |
skip |
integer | No | Número de registros a saltar (paginación) |
limit |
integer | No | Número máximo de registros (default: 100) |
Response (200 OK)
[
{
"id": 1,
"convoy_id": "CON-20260228-001",
"status": "en_ruta",
"origin_terminal_id": 1,
"destination_terminal_id": 2,
"created_at": "2026-02-28T08:00:00",
"trucks": [
{
"truck_id": "ABC-123-D",
"driver_name": "Juan Pérez"
}
]
}
]
POST
/api/convoys
Crear un nuevo convoy
Request Body
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
convoy_id |
string | Sí | ID único del convoy (formato: CON-YYYYMMDD-XXX) |
origin_terminal_id |
integer | Sí | ID de terminal de origen |
destination_terminal_id |
integer | Sí | ID de terminal de destino |
status |
string | No | Estado inicial (default: formando) |
Response (201 Created)
{
"id": 42,
"convoy_id": "CON-20260228-042",
"status": "formando",
"created_at": "2026-02-28T15:30:00"
}
GET
/api/convoys/{id}
Obtener detalles de un convoy específico
PUT
/api/convoys/{id}
Actualizar un convoy existente
DELETE
/api/convoys/{id}
Eliminar un convoy
Códigos de Error
La API utiliza códigos de estado HTTP estándar para indicar el éxito o fracaso de una solicitud.
| Código | Significado | Descripción |
|---|---|---|
200 |
OK | Solicitud exitosa |
201 |
Created | Recurso creado exitosamente |
400 |
Bad Request | Parámetros inválidos o faltantes |
401 |
Unauthorized | Token JWT inválido o expirado |
403 |
Forbidden | Sin permisos para acceder al recurso |
404 |
Not Found | Recurso no encontrado |
422 |
Unprocessable Entity | Error de validación de datos |
429 |
Too Many Requests | Límite de rate excedido |
500 |
Internal Server Error | Error del servidor |
Formato de Error
{
"detail": "Token JWT inválido o expirado",
"status_code": 401,
"timestamp": "2026-02-28T15:30:00"
}
Rate Limits
Para garantizar la disponibilidad del servicio, la API implementa límites de tasa por usuario.
100
Requests por minuto
10,000
Requests por día
Headers de Rate Limit
Cada respuesta incluye headers informativos sobre el límite de tasa:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1709135400
Si excedes el límite de tasa, recibirás un error
429 Too Many Requests. Espera hasta que se reinicie el contador (ver header X-RateLimit-Reset).