API EnviBox v1.0.0

API RESTful para gestión completa de envíos en Colombia. Integra creación, consulta, actualización y seguimiento de envíos directamente en tu aplicación.

Comenzar ahora Ver endpoints
Crear un envío (POST /api/v1/envios)
cURL

curl -X POST "https://api.envibox.com.co/api/v1/envios" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "tu_api_key_aqui",
    "api_pw": "tu_api_password_aqui",
    "tipo_paquete": "Documento",
    "precio_envio": 7500,
    "metodo_pago": "Efectivo",
    "nombre_remitente": "Mi Empresa SAS",
    "direccion_remitente": "Calle 123 #45-67, Bogotá",
    "telefono_remitente": "573012345678",
    "nombre_destinatario": "Juan Pérez",
    "direccion_destinatario": "Carrera 89 #12-34, Medellín",
    "telefono_destinatario": "573098765432",
    "observaciones_remitente": "Fragil",
    "distancia_km": 25
  }'

Características de la API

Funcionalidades diseñadas para desarrolladores

Autenticación Simple

API Key + Password en cada request. No requiere tokens JWT complejos.

Gestión Completa

CRUD completo de envíos: crear, leer, actualizar, eliminar y cambiar estados.

Búsquedas Avanzadas

Busca envíos por ID, guía, estado, usuario, fechas y más.

Estadísticas

Endpoints especializados para obtener métricas y reportes de tus envíos.

Autenticación

Todas las operaciones de gestión de envíos requieren autenticación mediante api_key y api_pw. Estos parámetros deben incluirse en cada request, ya sea en el body (POST/PUT/PATCH) o como query parameters (GET/DELETE).

Ejemplo de autenticación en GET:
Listar envíos con autenticación

# Via query parameters
curl "https://api.envibox.com.co/api/v1/envios?api_key=TU_API_KEY&api_pw=TU_API_PW&limit=10&page=1"

# O incluyendo en el body para otros métodos
curl -X POST "https://api.envibox.com.co/api/v1/envios" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "TU_API_KEY",
    "api_pw": "TU_API_PW",
    "tipo_paquete": "Documento",
    ...
  }'
Nota: Las rutas de tarifas (/api/v1/tarifas/**) son públicas y no requieren autenticación.

Endpoints Públicos - Tarifas

Consulta de tarifas sin necesidad de autenticación

GET /api/v1/tarifas PÚBLICO

Obtener todas las tarifas disponibles

Response:
{
  "status": "success",
  "message": "Tarifas obtenidas correctamente",
  "data": [
    {
      "id": 1,
      "tipo_paquete": "Documento",
      "peso_paquete": 500,
      "precio_servicio": "7000.00",
      "created_at": "2024-01-15 10:30:00"
    },
    {
      "id": 2,
      "tipo_paquete": "Pequeno",
      "peso_paquete": 2000,
      "precio_servicio": "12000.00",
      "created_at": "2024-01-15 10:30:00"
    }
  ],
  "total": 2
}
GET /api/v1/tarifas/calcular?tipo=Documento&peso=300 PÚBLICO

Calcular precio según tipo y peso

Response:
{
  "status": "success",
  "message": "Cálculo realizado correctamente",
  "data": {
    "tarifa": {
      "id": 1,
      "tipo_paquete": "Documento",
      "peso_paquete": 500,
      "precio_servicio": "7000.00"
    },
    "calculo": {
      "peso_solicitado": 300,
      "excede_peso": false,
      "aplicable": true,
      "mensaje_peso": "Peso dentro del rango permitido"
    },
    "precio_final": 7000,
    "precio_formateado": "7.000,00 COP",
    "moneda": "COP"
  }
}
GET /api/v1/tarifas/tipos PÚBLICO

Obtener tipos de paquetes disponibles

Response:
{
  "status": "success",
  "message": "Tipos de paquetes obtenidos correctamente",
  "data": ["Documento", "Pequeno", "Mediano"],
  "total": 3
}
GET /api/v1/tarifas/buscar?tipo=Documento PÚBLICO

Buscar tarifas por tipo

Response:
{
  "status": "success",
  "message": "Tarifas encontradas",
  "data": [{
    "id": 1,
    "tipo_paquete": "Documento",
    "peso_paquete": 500,
    "precio_servicio": "7000.00"
  }],
  "total": 1,
  "tipo_busqueda": "Documento"
}

Endpoints de Envíos

Gestión completa de envíos (requieren autenticación)

POST /api/v1/envios AUTENTICACIÓN

Crear un nuevo envío

Parámetros requeridos:
Campo Tipo Descripción
api_key string Tu API Key
api_pw string Tu API Password
tipo_paquete string "Documento", "Pequeno" o "Mediano"
precio_envio number Precio mayor a 0
metodo_pago string "Efectivo", "Transferencia" o "Contraentrega"
nombre_remitente string Nombre del remitente
direccion_remitente string Dirección del remitente
telefono_remitente string Teléfono del remitente
nombre_destinatario string Nombre del destinatario
direccion_destinatario string Dirección del destinatario
telefono_destinatario string Teléfono del destinatario
Response (201 Created):
{
  "status": "success",
  "message": "Envío creado correctamente",
  "data": {
    "id": 123,
    "usuario_id": 45,
    "guia_envio": "ENV-20250130-ABC123",
    "tipo_paquete": "Documento",
    "precio_envio": "7500.00",
    "metodo_pago": "Efectivo",
    "nombre_remitente": "Mi Empresa SAS",
    "direccion_remitente": "Calle 123 #45-67",
    "telefono_remitente": "573012345678",
    "nombre_destinatario": "Juan Pérez",
    "direccion_destinatario": "Carrera 89 #12-34",
    "telefono_destinatario": "573098765432",
    "estado_envio": "Pendiente",
    "created_at": "2025-01-30 14:30:00"
  },
  "guia_envio": "ENV-20250130-ABC123"
}
GET /api/v1/envios/(:num) AUTENTICACIÓN

Obtener envío por ID

Ejemplo:
curl "https://api.envibox.com.co/api/v1/envios/123?api_key=TU_API_KEY&api_pw=TU_API_PW"
Response:
{
  "status": "success",
  "message": "Envío obtenido correctamente",
  "data": {
    "id": 123,
    "guia_envio": "ENV-20250130-ABC123",
    "tipo_paquete": "Documento",
    "precio_envio": "7500.00",
    "metodo_pago": "Efectivo",
    "estado_envio": "Pendiente",
    "nombre_remitente": "Mi Empresa SAS",
    "direccion_remitente": "Calle 123 #45-67",
    "telefono_remitente": "573012345678",
    "nombre_destinatario": "Juan Pérez",
    "direccion_destinatario": "Carrera 89 #12-34",
    "telefono_destinatario": "573098765432",
    "created_at": "2025-01-30 14:30:00",
    "updated_at": "2025-01-30 14:30:00"
  }
}
PATCH /api/v1/envios/(:num)/estado AUTENTICACIÓN

Cambiar estado del envío

Ejemplo:
curl -X PATCH "https://api.envibox.com.co/api/v1/envios/123/estado" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "TU_API_KEY",
    "api_pw": "TU_API_PW",
    "estado": "Recogido"
  }'
Response:
{
  "status": "success",
  "message": "Estado del envío actualizado correctamente",
  "data": {
    "id": 123,
    "guia_envio": "ENV-20250130-ABC123",
    "estado_anterior": "Pendiente",
    "estado_nuevo": "Recogido",
    "fecha_cambio": "2025-01-30 15:45:00"
  }
}
Estados permitidos: Pendiente → Recogido → Entregado
GET /api/v1/envios AUTENTICACIÓN

Listar envíos con paginación

Parámetros opcionales:
  • limit - Límite por página (default: 50)
  • page - Número de página (default: 1)
  • estado - Filtrar por estado
  • fecha_desde - Filtrar desde fecha
  • fecha_hasta - Filtrar hasta fecha
Ejemplo:
curl "https://api.envibox.com.co/api/v1/envios?api_key=TU_KEY&api_pw=TU_PW&limit=10&page=1&estado=Pendiente"
Response:
{
  "status": "success",
  "message": "Envíos obtenidos correctamente",
  "data": [...],
  "total": 150,
  "page": 1,
  "limit": 10,
  "pages": 15
}
PUT /api/v1/envios/(:num) AUTENTICACIÓN

Actualizar envío (solo estado "Pendiente")

Ejemplo:
curl -X PUT "https://api.envibox.com.co/api/v1/envios/123" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "TU_API_KEY",
    "api_pw": "TU_API_PW",
    "precio_envio": 8500,
    "observaciones_remitente": "Paquete frágil"
  }'
Solo se pueden actualizar envíos con estado "Pendiente"
GET /api/v1/envios/guia/(:any) AUTENTICACIÓN

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

Ejemplo:
curl "https://api.envibox.com.co/api/v1/envios/guia/ENV-20250130-ABC123?api_key=TU_KEY&api_pw=TU_PW"
GET /api/v1/envios/estadisticas AUTENTICACIÓN

Obtener estadísticas de envíos

Ejemplo:
curl "https://api.envibox.com.co/api/v1/envios/estadisticas?api_key=TU_KEY&api_pw=TU_PW"
Response:
{
  "status": "success",
  "message": "Estadísticas obtenidas correctamente",
  "data": {
    "total_envios": 150,
    "pendientes": 45,
    "recogidos": 30,
    "entregados": 75,
    "valor_total": 1125000,
    "promedio_envio": 7500
  }
}
Ver documentación completa

Ejemplos de Implementación

Cómo consumir la API desde diferentes lenguajes

PHP - Crear envío

<?php

$api_url = 'https://api.envibox.com.co/api/v1/envios';
$api_key = 'TU_API_KEY';
$api_pw = 'TU_API_PASSWORD';

$data = [
    'api_key' => $api_key,
    'api_pw' => $api_pw,
    'tipo_paquete' => 'Documento',
    'precio_envio' => 7500,
    'metodo_pago' => 'Efectivo',
    'nombre_remitente' => 'Mi Empresa SAS',
    'direccion_remitente' => 'Calle 123 #45-67',
    'telefono_remitente' => '573012345678',
    'nombre_destinatario' => 'Juan Pérez',
    'direccion_destinatario' => 'Carrera 89 #12-34',
    'telefono_destinatario' => '573098765432'
];

$ch = curl_init($api_url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

if ($result['status'] === 'success') {
    echo "Envío creado: " . $result['data']['guia_envio'];
} else {
    echo "Error: " . $result['message'];
}
JavaScript (Fetch) - Listar envíos

async function listarEnvios() {
    const apiKey = 'TU_API_KEY';
    const apiPw = 'TU_API_PASSWORD';
    
    const url = new URL('https://api.envibox.com.co/api/v1/envios');
    url.searchParams.append('api_key', apiKey);
    url.searchParams.append('api_pw', apiPw);
    url.searchParams.append('limit', '10');
    url.searchParams.append('page', '1');
    
    try {
        const response = await fetch(url);
        const data = await response.json();
        
        if (data.status === 'success') {
            console.log('Total envíos:', data.total);
            console.log('Envíos:', data.data);
            
            // Mostrar envíos
            data.data.forEach(envio => {
                console.log(`${envio.guia_envio} - ${envio.estado_envio}`);
            });
        } else {
            console.error('Error:', data.message);
        }
    } catch (error) {
        console.error('Error de conexión:', error);
    }
}

// Llamar la función
listarEnvios();
Python - Consultar tarifas

import requests

# Endpoint público - no requiere autenticación
response = requests.get('https://api.envibox.com.co/api/v1/tarifas')

if response.status_code == 200:
    data = response.json()
    
    if data['status'] == 'success':
        print(f"Total tarifas: {data['total']}")
        
        for tarifa in data['data']:
            print(f"{tarifa['tipo_paquete']}: {tarifa['precio_servicio']} COP")
    else:
        print(f"Error: {data['message']}")
else:
    print(f"Error HTTP: {response.status_code}")
Shell Script - Monitorear estados

#!/bin/bash

API_KEY="TU_API_KEY"
API_PW="TU_API_PASSWORD"
BASE_URL="https://api.envibox.com.co/api/v1"

# Obtener envíos pendientes
curl -s "${BASE_URL}/envios/estado/Pendiente?api_key=${API_KEY}&api_pw=${API_PW}" | \
  python3 -c "
import sys, json
data = json.load(sys.stdin)
if data['status'] == 'success':
    print(f'Envíos pendientes: {data[\"total\"]}')
    for envio in data['data']:
        print(f\"  • {envio['guia_envio']} - {envio['nombre_destinatario']}\")
else:
    print(f'Error: {data[\"message\"]}')
"

¿Listo para comenzar?

Obtén tu API Key y comienza a integrar en minutos

Pasos para comenzar:
1
Crear cuenta

Regístrate en el portal de desarrolladores

2
Generar credenciales

Obtén tu API Key y Password

3
Probar endpoints

Usa las rutas públicas primero

Crear cuenta gratis Probar endpoints públicos
Consejo: Comienza probando los endpoints de tarifas que son públicos y no requieren autenticación.