Documentación API EnviBox

Bienvenido a la documentación oficial de la API de EnviBox. Esta API RESTful permite integrar servicios de mensajería y consulta de tarifas en tus aplicaciones.

Características Principales

Endpoints RESTful con respuestas JSON
Consulta de tarifas en tiempo real
Gestión completa de envíos
Autenticación por API Key
Paginación y filtros avanzados
Alta disponibilidad y rendimiento
Documentación actualizada

Autenticación

Para operaciones de escritura (POST, PUT, DELETE, PATCH) se requiere autenticación mediante API Key y contraseña. Los endpoints de tarifas son públicos.

Nota: Los endpoints de tarifas son públicos, pero los de envíos requieren autenticación.

Métodos de Autenticación:

1. Parámetros de consulta (GET/DELETE):

curl -X GET "https://api.envibox.com.co/api/v1/envios?api_key=TU_API_KEY&api_pw=TU_CONTRASENA"

2. Cuerpo JSON (POST/PUT/PATCH):

{ "api_key": "TU_API_KEY", "api_pw": "TU_CONTRASENA", "tipo_paquete": "Documento", ... }

3. Headers HTTP (opcional para POST/PUT/PATCH):

curl -X POST "https://api.envibox.com.co/api/v1/envios" \ -H "Content-Type: application/json" \ -H "X-API-Key: TU_API_KEY" \ -H "X-API-Password: TU_CONTRASENA"

Formatos de Respuesta

Todas las respuestas siguen un formato consistente para facilitar el parsing.

Estructura Base:

{ "status": "success" | "error", "message": "Mensaje descriptivo", "data": { ... } | [ ... ], "total": 10 // Solo en listados, "page": 1 // Solo en listados paginados, "limit": 50 // Solo en listados paginados, "pages": 5 // Solo en listados paginados }

Ejemplo Exitosa:

{ "status": "success", "message": "Envío obtenido correctamente", "data": { "id": 1, "guia_envio": "ENV-2025-01-ABC123", "estado_envio": "Pendiente", "precio_formateado": "5.000 COP" } }

Manejo de Errores

La API utiliza códigos de estado HTTP estándar. Los errores incluyen un mensaje descriptivo.

Códigos HTTP:

200 OK 201 Created 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 500 Server Error

Ejemplo de Error:

{ "status": "error", "message": "API Key no válida o no encontrada", "errors": [ "El campo 'nombre_remitente' es obligatorio" ] }

GET

Obtener todas las tarifas

PÚBLICO

https://api.envibox.com.co/api/v1/tarifas

Retorna la lista completa de tarifas activas en el sistema. No requiere autenticación.

Ejemplo de Solicitud:

curl -X GET "https://api.envibox.com.co/api/v1/tarifas" \ -H "Accept: application/json"

Respuesta Exitosa:

{ "status": "success", "message": "Tarifas obtenidas correctamente", "data": [ { "id": 1, "tipo_paquete": "Documento", "precio_servicio": 5000.00, "precio_formateado": "5.000 COP", "medidas_paquete": "30x20x5 cm", "peso_paquete": 500 } ], "total": 1 }

200 OK 500 Error

GET

Obtener tarifa por ID

PÚBLICO

https://api.envibox.com.co/api/v1/tarifas/{id}

Obtiene los detalles de una tarifa específica mediante su ID numérico. No requiere autenticación.

Parámetros de Ruta:

Parámetro	Tipo	Descripción	Ejemplo
`id` REQUERIDO	integer	ID de la tarifa	1, 2, 3

Ejemplo de Solicitud:

curl -X GET "https://api.envibox.com.co/api/v1/tarifas/1" \ -H "Accept: application/json"

200 OK 404 No encontrado 500 Error

GET

Obtener tipos de paquetes

PÚBLICO

https://api.envibox.com.co/api/v1/tarifas/tipos

Retorna la lista de tipos de paquetes disponibles en el sistema. No requiere autenticación.

Respuesta Exitosa:

{ "status": "success", "message": "Tipos de paquetes obtenidos correctamente", "data": [ "Documento", "Pequeno", "Mediano" ], "total": 3 }

200 OK 500 Error

GET

Buscar tarifas por tipo

PÚBLICO

https://api.envibox.com.co/api/v1/tarifas/buscar?tipo={tipo}

Busca tarifas que coincidan con el tipo de paquete especificado (búsqueda parcial). No requiere autenticación.

Parámetros de Consulta:

Parámetro	Requerido	Descripción	Ejemplo
`tipo` REQUERIDO	Sí	Texto a buscar en tipo de paquete	"documento", "paquete"

Ejemplo de Solicitud:

curl -X GET "https://api.envibox.com.co/api/v1/tarifas/buscar?tipo=documento" \ -H "Accept: application/json"

200 OK 400 Parámetro faltante

GET

Calcular precio

PÚBLICO

https://api.envibox.com.co/api/v1/tarifas/calcular?tipo={tipo}&peso={peso}

Calcula el precio de un envío basado en el tipo de paquete y el peso. No requiere autenticación.

Parámetros de Consulta:

Parámetro	Requerido	Descripción	Ejemplo
`tipo` REQUERIDO	Sí	Tipo exacto del paquete	"Documento", "Pequeno", "Mediano"
`peso` OPCIONAL	No	Peso en gramos	300, 500, 1000

Ejemplo de Solicitud:

curl -X GET "https://api.envibox.com.co/api/v1/tarifas/calcular?tipo=Documento&peso=300" \ -H "Accept: application/json"

Respuesta Exitosa:

{ "status": "success", "message": "Cálculo realizado correctamente", "data": { "tarifa": { "id": 1, "tipo_paquete": "Documento", "precio_servicio": 5000.00", "peso_paquete": 500 }, "calculo": { "peso_solicitado": 300, "excede_peso": false, "aplicable": true, "mensaje_peso": "Peso dentro del rango permitido" }, "precio_final": 5000.00, "precio_formateado": "5.000 COP", "moneda": "COP" } }

200 OK 400 Parámetro faltante 404 No encontrado

GET

Listar todos los envíos

REQUIERE AUTH

https://api.envibox.com.co/api/v1/envios

Retorna la lista de envíos del usuario autenticado con paginación y filtros.

Requiere autenticación: api_key y api_pw como parámetros de consulta

Parámetros de consulta:

Parámetro	Tipo	Requerido	Descripción	Ejemplo
`api_key` REQUERIDO	string	Sí	API Key del usuario	"AK_TEST_7e3b9f2a4c6d8e1f"
`api_pw` REQUERIDO	string	Sí	Contraseña API	"admin123"
`limit` OPCIONAL	integer	No	Límite de resultados (default: 50)	10, 25, 50
`page` OPCIONAL	integer	No	Número de página (default: 1)	1, 2, 3
`estado` OPCIONAL	string	No	Filtrar por estado	"Pendiente", "Recogido", "Entregado"
`usuario_id` OPCIONAL	integer	No	Filtrar por ID de usuario (solo admin)	1, 2, 3
`fecha_desde` OPCIONAL	date	No	Filtrar desde fecha (YYYY-MM-DD)	"2025-01-01"
`fecha_hasta` OPCIONAL	date	No	Filtrar hasta fecha (YYYY-MM-DD)	"2025-01-31"

Ejemplo de Solicitud:

curl -X GET "https://api.envibox.com.co/api/v1/envios?api_key=TU_API_KEY&api_pw=TU_CONTRASENA&limit=10&page=1&estado=Pendiente" \ -H "Accept: application/json"

Respuesta Exitosa:

{ "status": "success", "message": "Envíos obtenidos correctamente", "data": [ { "id": 1, "guia_envio": "ENV-2025-01-ABC123", "tipo_paquete": "Documento", "estado_envio": "Pendiente", "precio_formateado": "5.000 COP", "fecha_creacion": "2025-01-29 10:00:00" } ], "total": 15, "page": 1, "limit": 10, "pages": 2 }

200 OK 401 No autorizado 500 Error

GET

Obtener envío por ID

PÚBLICO

https://api.envibox.com.co/api/v1/envios/{id}

Obtiene los detalles completos de un envío específico mediante su ID. No requiere autenticación.

Parámetros de Ruta:

Parámetro	Tipo	Descripción	Ejemplo
`id` REQUERIDO	integer	ID del envío	1, 2, 3

Ejemplo de Solicitud:

curl -X GET "https://api.envibox.com.co/api/v1/envios/1" \ -H "Accept: application/json"

Respuesta Exitosa:

{ "status": "success", "message": "Envío obtenido correctamente", "data": { "id": 1, "usuario_id": 1, "guia_envio": "ENV-2025-01-ABC123", "tipo_paquete": "Documento", "estado_envio": "Pendiente", "precio_envio": 5000.00, "precio_formateado": "5.000 COP", "metodo_pago": "Efectivo", "remitente": { "nombre": "Juan Pérez", "direccion": "Calle 123 #45-67", "telefono": "573001234567" }, "destinatario": { "nombre": "María García", "direccion": "Carrera 89 #12-34", "telefono": "573009876543" }, "distancia_km": 5, "fecha_creacion": "2025-01-29 10:00:00", "fecha_entrega": null, "tracking_url": "https://api.envibox.com.co/rastrear/ENV-2025-01-ABC123" } }

200 OK 404 No encontrado 500 Error

POST

Crear nuevo envío

REQUIERE AUTH

https://api.envibox.com.co/api/v1/envios

Crea un nuevo envío en el sistema. Se genera automáticamente un número de guía único.

Requiere autenticación: api_key y api_pw en el cuerpo JSON

Parámetros del cuerpo (JSON):

Parámetro	Tipo	Requerido	Descripción	Ejemplo
`api_key` REQUERIDO	string	Sí	API Key del usuario	"AK_TEST_7e3b9f2a4c6d8e1f"
`api_pw` REQUERIDO	string	Sí	Contraseña API	"admin123"
`tipo_paquete` REQUERIDO	string	Sí	Tipo: Documento, Pequeno, Mediano	"Documento"
`precio_envio` REQUERIDO	decimal	Sí	Precio en COP	5000.00
`metodo_pago` REQUERIDO	string	Sí	Efectivo, Transferencia, Contraentrega	"Efectivo"
`nombre_remitente` REQUERIDO	string	Sí	Nombre completo remitente	"Juan Pérez"
`direccion_remitente` REQUERIDO	string	Sí	Dirección completa remitente	"Calle 123 #45-67"
`telefono_remitente` REQUERIDO	string	Sí	Teléfono remitente	"573001234567"
`nombre_destinatario` REQUERIDO	string	Sí	Nombre completo destinatario	"María García"
`direccion_destinatario` REQUERIDO	string	Sí	Dirección completa destinatario	"Carrera 89 #12-34"
`telefono_destinatario` REQUERIDO	string	Sí	Teléfono destinatario	"573009876543"
`distancia_km` OPCIONAL	integer	No	Distancia en kilómetros	5
`latitud_remitente` OPCIONAL	decimal	No	Latitud del remitente	4.6097100
`longitud_remitente` OPCIONAL	decimal	No	Longitud del remitente	-74.0817500
`observaciones_remitente` OPCIONAL	string	No	Observaciones del remitente	"Entregar después de las 3pm"
`latitud_destinatario` OPCIONAL	decimal	No	Latitud del destinatario	4.6097100
`longitud_destinatario` OPCIONAL	decimal	No	Longitud del destinatario	-74.0817500
`observaciones_destinatario` OPCIONAL	string	No	Observaciones del destinatario	"Llamar antes de llegar"

Ejemplo de Solicitud:

curl -X POST "https://api.envibox.com.co/api/v1/envios" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "api_key": "TU_API_KEY", "api_pw": "TU_CONTRASENA", "tipo_paquete": "Documento", "precio_envio": 5000.00, "metodo_pago": "Efectivo", "nombre_remitente": "Juan Pérez", "direccion_remitente": "Calle 123 #45-67", "telefono_remitente": "573001234567", "nombre_destinatario": "María García", "direccion_destinatario": "Carrera 89 #12-34", "telefono_destinatario": "573009876543", "distancia_km": 5 }'

Respuesta Exitosa:

{ "status": "success", "message": "Envío creado correctamente", "data": { "id": 1, "guia_envio": "ENV-20250129-ABC123DEF", "estado_envio": "Pendiente", "fecha_creacion": "2025-01-29 14:30:00" }, "guia_envio": "ENV-20250129-ABC123DEF" }

201 Created 400 Validación 401 No autorizado 500 Error

PUT

Actualizar envío

REQUIERE AUTH

https://api.envibox.com.co/api/v1/envios/{id}

Actualiza la información de un envío existente. Solo se pueden actualizar envíos con estado "Pendiente".

Requiere autenticación: Solo el dueño del envío puede actualizarlo

Parámetros de Ruta:

Parámetro	Tipo	Requerido	Descripción	Ejemplo
`id` REQUERIDO	integer	Sí	ID del envío a actualizar	1, 2, 3

Parámetros del cuerpo (JSON):

Parámetro	Tipo	Requerido	Descripción	Ejemplo
`api_key` REQUERIDO	string	Sí	API Key del usuario	"AK_TEST_7e3b9f2a4c6d8e1f"
`api_pw` REQUERIDO	string	Sí	Contraseña API	"admin123"
`tipo_paquete` OPCIONAL	string	No	Tipo: Documento, Pequeno, Mediano	"Documento"
`precio_envio` OPCIONAL	decimal	No	Precio en COP	5000.00
`metodo_pago` OPCIONAL	string	No	Efectivo, Transferencia, Contraentrega	"Efectivo"

Ejemplo de Solicitud:

curl -X PUT "https://api.envibox.com.co/api/v1/envios/1" \ -H "Content-Type: application/json" \ -d '{ "api_key": "TU_API_KEY", "api_pw": "TU_CONTRASENA", "tipo_paquete": "Pequeno", "precio_envio": 7500.00, "nombre_destinatario": "Carlos Rodríguez" }'

Restricciones:

Solo se pueden actualizar envíos con estado "Pendiente"
Solo el dueño del envío puede actualizarlo
No se puede cambiar el número de guía

200 OK 400 No editable 401 No autorizado 403 Prohibido 404 No encontrado

DELETE

Eliminar envío

REQUIERE AUTH

https://api.envibox.com.co/api/v1/envios/{id}

Elimina un envío del sistema (soft delete). Solo se pueden eliminar envíos con estado "Pendiente".

Requiere autenticación: Solo el dueño del envío puede eliminarlo

Parámetros:

Parámetro	Tipo	Requerido	Descripción	Ejemplo
`id` REQUERIDO	integer	Sí	ID del envío a eliminar	1, 2, 3
`api_key` REQUERIDO	string	Sí	API Key del usuario	"AK_TEST_7e3b9f2a4c6d8e1f"
`api_pw` REQUERIDO	string	Sí	Contraseña API	"admin123"

Ejemplo de Solicitud:

curl -X DELETE "https://api.envibox.com.co/api/v1/envios/1?api_key=TU_API_KEY&api_pw=TU_CONTRASENA" \ -H "Accept: application/json"

Restricciones:

Solo se pueden eliminar envíos con estado "Pendiente"
Solo el dueño del envío puede eliminarlo
Eliminación lógica (soft delete)

200 OK 400 No eliminable 401 No autorizado 403 Prohibido 404 No encontrado

PATCH

Cambiar estado del envío

REQUIERE AUTH

https://api.envibox.com.co/api/v1/envios/{id}/estado

Actualiza el estado de un envío. Las transiciones de estado están controladas: Pendiente → Recogido → Entregado

Requiere autenticación: Solo usuarios autorizados

Parámetros del cuerpo (JSON):

Parámetro	Tipo	Requerido	Descripción	Ejemplo
`api_key` REQUERIDO	string	Sí	API Key del usuario	"AK_TEST_7e3b9f2a4c6d8e1f"
`api_pw` REQUERIDO	string	Sí	Contraseña API	"admin123"
`estado` REQUERIDO	string	Sí	Nuevo estado: Pendiente, Recogido, Entregado	"Recogido"

Transiciones permitidas:

Pendiente → Recogido → Entregado
Recogido → Entregado
Entregado → No se puede cambiar

Ejemplo de Solicitud:

curl -X PATCH "https://api.envibox.com.co/api/v1/envios/1/estado" \ -H "Content-Type: application/json" \ -d '{ "api_key": "TU_API_KEY", "api_pw": "TU_CONTRASENA", "estado": "Recogido" }'

Respuesta Exitosa:

{ "status": "success", "message": "Estado del envío actualizado correctamente", "data": { "id": 1, "guia_envio": "ENV-2025-01-ABC123", "estado_anterior": "Pendiente", "estado_nuevo": "Recogido", "fecha_cambio": "2025-01-29 15:30:00" } }

200 OK 400 Transición inválida 401 No autorizado 404 No encontrado

GET

Buscar envío por número de guía

PÚBLICO

https://api.envibox.com.co/api/v1/envios/guia/{guia}

Busca envíos por número de guía (búsqueda parcial). No requiere autenticación.

Parámetros de Ruta:

Parámetro	Tipo	Descripción	Ejemplo
`guia` REQUERIDO	string	Número de guía o parte de él	"ENV-2025", "ABC123"

Ejemplo de Solicitud:

curl -X GET "https://api.envibox.com.co/api/v1/envios/guia/ENV-2025" \ -H "Accept: application/json"

200 OK 404 No encontrado

GET

Filtrar envíos por estado

REQUIERE AUTH

https://api.envibox.com.co/api/v1/envios/estado/{estado}

Obtiene todos los envíos del usuario autenticado con un estado específico.

Requiere autenticación: api_key y api_pw como parámetros de consulta

Parámetros de Ruta:

Parámetro	Tipo	Requerido	Descripción	Ejemplo
`estado` REQUERIDO	string	Sí	Estado a filtrar: Pendiente, Recogido, Entregado	"Pendiente", "Recogido", "Entregado"

Parámetros de Consulta:

Parámetro	Tipo	Requerido	Descripción	Ejemplo
`api_key` REQUERIDO	string	Sí	API Key del usuario	"AK_TEST_7e3b9f2a4c6d8e1f"
`api_pw` REQUERIDO	string	Sí	Contraseña API	"admin123"
`limit` OPCIONAL	integer	No	Límite de resultados (default: 50)	10, 25, 50
`page` OPCIONAL	integer	No	Número de página (default: 1)	1, 2, 3

Ejemplo de Solicitud:

curl -X GET "https://api.envibox.com.co/api/v1/envios/estado/Pendiente?api_key=TU_API_KEY&api_pw=TU_CONTRASENA&limit=10" \ -H "Accept: application/json"

200 OK 400 Estado inválido 401 No autorizado

GET

Envios por usuario

REQUIERE AUTH

https://api.envibox.com.co/api/v1/envios/usuario/{usuario_id}

Obtiene todos los envíos asociados a un usuario específico. Requiere permisos de administrador o ser el mismo usuario.

Requiere autenticación: Solo administradores o el mismo usuario

Parámetros de Ruta:

Parámetro	Tipo	Requerido	Descripción	Ejemplo
`usuario_id` REQUERIDO	integer	Sí	ID del usuario	1, 2, 3

Parámetros de Consulta:

Parámetro	Tipo	Requerido	Descripción	Ejemplo
`api_key` REQUERIDO	string	Sí	API Key del usuario	"AK_TEST_7e3b9f2a4c6d8e1f"
`api_pw` REQUERIDO	string	Sí	Contraseña API	"admin123"
`limit` OPCIONAL	integer	No	Límite de resultados (default: 50)	10, 25, 50
`page` OPCIONAL	integer	No	Número de página (default: 1)	1, 2, 3

Ejemplo de Solicitud:

curl -X GET "https://api.envibox.com.co/api/v1/envios/usuario/1?api_key=TU_API_KEY&api_pw=TU_CONTRASENA&limit=10" \ -H "Accept: application/json"

200 OK 401 No autorizado 403 Prohibido

GET

Estadísticas de envíos

REQUIERE AUTH

https://api.envibox.com.co/api/v1/envios/estadisticas

Obtiene estadísticas generales sobre los envíos del usuario autenticado.

Requiere autenticación: api_key y api_pw como parámetros de consulta

Parámetros de Consulta:

Parámetro	Tipo	Requerido	Descripción	Ejemplo
`api_key` REQUERIDO	string	Sí	API Key del usuario	"AK_TEST_7e3b9f2a4c6d8e1f"
`api_pw` REQUERIDO	string	Sí	Contraseña API	"admin123"

Ejemplo de Solicitud:

curl -X GET "https://api.envibox.com.co/api/v1/envios/estadisticas?api_key=TU_API_KEY&api_pw=TU_CONTRASENA" \ -H "Accept: application/json"

Respuesta Exitosa:

{ "status": "success", "message": "Estadísticas obtenidas correctamente", "data": { "total_envios": 150, "por_estado": { "pendientes": 45, "recogidos": 30, "entregados": 75 }, "porcentajes": { "pendientes": 30.00, "recogidos": 20.00, "entregados": 50.00 }, "ingresos": { "total": 1125000.00, "formateado": "1.125.000 COP" }, "tipo_paquetes": { "Documento": 80, "Pequeno": 45, "Mediano": 25 }, "actualizado": "2025-01-29 14:30:00" } }

200 OK 401 No autorizado