Authentication

Autenticación

To perform write operations (create orders, products, etc.), you must obtain a JWT token.

Para realizar operaciones de escritura (crear pedidos, productos, etc.), debes obtener un token JWT.

1. Get Token

1. Obtener Token

Request Body

Cuerpo de la Petición

Example Request

Ejemplo de Petición

curl -X POST "http://localhost/paqueteriacz/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com", "password":"secure_password"}'

Response 200 OK

Respuesta 200 OK

{
    "success": true,
    "message": "Login exitoso",
    "data": {
        "token": "eyJ0e... (your_token_here) ... "
    }
}

2. Use Token

2. Usar el Token

Include the token in the Authorization header for subsequent requests.

Incluye el token en el encabezado Authorization para las siguientes peticiones.

List & View

Listar y Ver

Create Order

Crear Pedido

Create a new delivery order. The system automatically validates stock, calculates pricing, and enforces security rules based on user role.

Crea un nuevo pedido de entrega. El sistema valida automáticamente el stock, calcula precios y aplica reglas de seguridad según el rol del usuario.

🔑 Required Fields

🔑 Campos Obligatorios

📋 Optional Fields - Contact & Delivery

📋 Campos Opcionales - Contacto y Entrega

🌍 Optional Fields - Geographic

🌍 Campos Opcionales - Geográficos

👥 Optional Fields - Assignments

👥 Campos Opcionales - Asignaciones

💰 Optional Fields - Pricing

💰 Campos Opcionales - Precios

✅ Automatic Validations

✅ Validaciones Automáticas

• Stock validation: Ensures sufficient inventory before creating order
• Unique order number: Prevents duplicate numero_orden
• Coordinate format: Validates "lat,long" format
• Valid products: Verifies product IDs exist in database
• Positive quantities: All quantities must be > 0
• Foreign key validation: Checks vendor, provider, client, currency exist

• Validación de stock: Asegura inventario suficiente antes de crear
• Número único: Previene numero_orden duplicados
• Formato coordenadas: Valida formato "lat,long"
• Productos válidos: Verifica que IDs de productos existan en BD
• Cantidades positivas: Todas las cantidades deben ser > 0
• Validación FK: Verifica que vendedor, proveedor, cliente, moneda existan

🔐 Security Rules

🔐 Reglas de Seguridad

Provider Role: If authenticated user is a Provider (role 4), the system automatically sets id_proveedor to their user ID, ignoring any value sent in the request.

Rol Proveedor: Si el usuario autenticado es Proveedor (rol 4), el sistema automáticamente asigna id_proveedor a su ID de usuario, ignorando cualquier valor enviado en la petición.

📝 Example: Minimal Order

📝 Ejemplo: Pedido Mínimo

{
    "numero_orden": 12345,
    "destinatario": "Juan Pérez",
    "producto_id": 10,
    "cantidad": 2
}

📝 Example: Complete Order with Combo Pricing

📝 Ejemplo: Pedido Completo con Precio Combo

{
    "numero_orden": 12346,
    "destinatario": "María García",
    "telefono": "50212345678",
    "direccion": "Calle Principal #123",
    "coordenadas": "14.6349,-90.5069",
    "comentario": "Entregar en horario de oficina",
    "id_pais": 1,
    "id_departamento": 5,
    "id_municipio": 25,
    "id_proveedor": 8,
    "id_cliente": 15,
    "id_moneda": 2,
    "es_combo": 1,
    "precio_total_local": 150.00,
    "productos": [
        { "producto_id": 10, "cantidad": 2 },
        { "producto_id": 15, "cantidad": 1 }
    ]
}

📝 Example: Multi-Product Standard Order

📝 Ejemplo: Pedido Estándar Multi-Producto

{
    "numero_orden": 10050,
    "destinatario": "Maria Gonzalez",
    "telefono": "8888-8888",
    "direccion": "Bello Horizonte C-4",
    "es_combo": 0,
    "coordenadas": "12.1345,-86.2456",
    "productos": [
        { "producto_id": 1, "cantidad": 2 },
        { "producto_id": 5, "cantidad": 1 }
    ]
}

Standard vs. Combo Orders

Pedidos Estándar vs. Combos

{
    "numero_orden": "STD-101",
    "es_combo": 0,
    "productos": [
        { "producto_id": 1, "cantidad": 2 }
    ]
    // Total calculated by system:
    // (Price of ID 1 × 2)
}

{
    "numero_orden": "PROMO-500",
    "es_combo": 1,
    "precio_total_local": 999.00,
    "productos": [
        { "producto_id": 1, "cantidad": 1 },
        { "producto_id": 5, "cantidad": 1 }
    ]
    // System accepts 999.00
    // ignoring individual prices.
}

Bulk Import (Async)

Importación Masiva (Async)

Import multiple orders efficiently. Use auto_enqueue=true to process in background.

Importa múltiples pedidos eficientemente. Usa auto_enqueue=true para procesar en segundo plano.

Success Response (202 Accepted)

Respuesta Exitosa (202 Accepted)

{
    "success": true,
    "message": "Proceso iniciado",
    "results": [
        { "numero_orden": 10050, "success": true, "job_queued": true },
        { "numero_orden": 10051, "success": true, "job_queued": true }
    ]
}

Advanced Example: Multiple Products & Combo

Ejemplo Avanzado: Múltiples Productos y Combos

{
    "pedidos": [
        {
            // Pedido multiproducto estándar
            "numero_orden": 20001,
            "destinatario": "Juan Perez",
            "telefono": "5555-5555",
            "direccion": "Calle Principal #123",
            "coordenadas": "12.1234,-86.1234",
            "productos": [
                { "producto_id": 1, "cantidad": 2 },
                { "producto_id": 5, "cantidad": 1 }
            ]
        },
        {
            // Pedido tipo COMBO (Precio fijo total)
            "numero_orden": 20002,
            "destinatario": "Ana Lopez",
            "telefono": "7777-7777",
            "direccion": "Residencial Los Arcos, Casa 5",
            "coordenadas": "12.1255,-86.1255",
            "es_combo": 1, 
            "precio_total_local": 1500.00,  // Precio fijo total
            "precio_total_usd": 40.50,      // Opcional si se calcula, pero recomendado en combos
            "productos": [
                { "producto_id": 10, "cantidad": 1 },
                { "producto_id": 11, "cantidad": 1 },
                { "producto_id": 12, "cantidad": 1 }
            ]
        }
    ]
}

Product Management

Gestión de Productos

Product Object Model

Modelo de Objeto Producto

{
    "id": 1,
    "nombre": "Protein Shake",
    "precio_usd": "45.00",
    "stock_total": 150,
    "descripcion": "High quality whey protein"
}

Update & Delete

Actualizar y Eliminar

{
    "id": 1,
    "nombre": "Protein Shake V2",
    "precio_usd": 48.00,
    "descripcion": "New formula"
}

Geographic Data

Datos Geográficos

Retrieve reference data for dropdowns (Countries, Departments, Municipalities).

Obtener datos de referencia para listas desplegables (Países, Departamentos, Municipios).

Response Structure

Estructura de Respuesta

{
    "success": true,
    "data": {
        "paises": [ ... ],
        "departamentos": [ ... ],
        "municipios": [ ... ],
        "barrios": [ ... ]
    }
}

Geo CRUD Operations

Operaciones CRUD Geo

Endpoints to manage reference data. All accept POST for creation/update.

Endpoints para gestionar datos de referencia. Todos aceptan POST para crear/actualizar.

Client Application API

API App Cliente

Specialized endpoints for the end-customer mobile/web app.

Endpoints especializados para la app móvil/web del cliente final.

{
    "success": true,
    "data": [
        {
            "id": 100,
            "numero_orden": "ORD-2025-001",
            "estado": "En ruta",
            "productos": "Producto A (x2)"
        }
    ]
}

{
    "id_pedido": 100,
    "estado": 3,
    "motivo": "Recibido conforme"
}