Logistics API Documentation

Quick Reference

Referencia Rápida

Welcome to the Logistics API. This system allows you to manage orders, products, and geographic data using standard HTTP requests.

Bienvenido a la API de Logística. Este sistema te permite gestionar pedidos, productos y datos geográficos usando peticiones HTTP estándar.

✨ Key Concepts

✨ Conceptos Clave

Base URL: /api (relative to your installation)
Auth: JWT Bearer Token required for write operations.
Response Format: All responses are JSON wrapped in a standard envelope.
Dates: Format YYYY-MM-DD HH:MM:SS unless otherwise specified.

URL Base: /api (relativo a tu instalación)
Auth: Token Bearer JWT requerido para operaciones de escritura.
Formato Respuesta: Todas las respuestas son JSON envueltas en un sobre estándar.
Fechas: Formato YYYY-MM-DD HH:MM:SS a menos que se especifique lo contrario.

Standard Response Envelope

Sobre de Respuesta Estándar

Every API response follows this consistent JSON structure:

Toda respuesta de la API sigue esta estructura JSON consistente:

{
    "success": true,           // boolean: did the request succeed?
    "message": "Operation...", // string: human-readable message
    "data": { ... }            // object/array: the requested payload
}

Error Response Example

Ejemplo de Respuesta de Error

{
    "success": false,
    "message": "Invalid credentials",
    "error_code": 401          // optional: numeric error code
}

Pagination

Paginación

Endpoints that return lists (Orders, Products) support pagination via query parameters.

Los endpoints que retornan listas (Pedidos, Productos) soportan paginación vía parámetros GET.

Parameter	Type	Default	Description
`page`	integer	1	Current page number
`limit`	integer	20	Items per page

Parámetro	Tipo	Defecto	Descripción
`page`	entero	1	Número de página actual
`limit`	entero	20	Elementos por página

Paginated Response

Respuesta Paginada

{
    "success": true,
    "data": [ ... ],
    "pagination": {
        "total": 150,
        "page": 1,
        "limit": 20,
        "total_pages": 8
    }
}

Get Order States

Obtener Estados de Pedidos

Retrieve all available order states programmatically.

Obtener todos los estados de pedidos disponibles de forma programática.

                        GET /api/pedidos/estados
                        🌐 PublicPúblico
                    

Example Request

Ejemplo de Petición

GET /api/pedidos/estados

Response 200 OK

Respuesta 200 OK

{
    "success": true,
    "data": [
        {"id": 1, "nombre_estado": "En bodega"},
        {"id": 2, "nombre_estado": "En ruta o proceso"},
        {"id": 3, "nombre_estado": "Entregado"},
        {"id": 4, "nombre_estado": "Reprogramado"},
        {"id": 5, "nombre_estado": "Domicilio cerrado"},
        {"id": 6, "nombre_estado": "No hay quien reciba en domicilio"},
        {"id": 7, "nombre_estado": "Devuelto"},
        {"id": 8, "nombre_estado": "Domicilio no encontrado"},
        {"id": 9, "nombre_estado": "Rechazado"},
        {"id": 10, "nombre_estado": "No puede pagar recaudo"},
        {"id": 11, "nombre_estado": "Pendiente recolección"},
        {"id": 12, "nombre_estado": "Recolectado por mensajería"},
        {"id": 13, "nombre_estado": "Traslado a punto de distribución"},
        {"id": 14, "nombre_estado": "Entregado-liquidado"},
        {"id": 15, "nombre_estado": "Devuelto a bodega"},
        {"id": 16, "nombre_estado": "Incidencia"},
        {"id": 17, "nombre_estado": "Cancelado"},
        {"id": 18, "nombre_estado": "Correo"},
        {"id": 19, "nombre_estado": "Disponible para retirar en Agencia"}
    ]
}

💡 Use Cases 💡 Casos de Uso

Populate status dropdown filters
Build dynamic order management UIs
Validate status IDs before updates

Poblar filtros dropdown de estados
Construir UIs dinámicas de gestión de pedidos
Validar IDs de estado antes de actualizar

Order Status Reference

Referencia de Estados

Use these IDs when filtering or updating order statuses.

Usa estos IDs al filtrar o actualizar estados de pedidos.

ID	Status NameNombre Estado	DescriptionDescripción
`1`	En bodega	Initial status, order received at warehouse.Estado inicial, pedido recibido en bodega.
`2`	En ruta o proceso	Order is being delivered.El pedido está en camino.
`3`	Entregado	Order successfully delivered.Pedido entregado exitosamente.
`4`	Reprogramado	Delivery rescheduled for another day/time.Entrega reprogramada para otro día/hora.
`5`	Domicilio cerrado	Delivery failed: location closed.Falló entrega: lugar cerrado.
`6`	No hay quien reciba	Delivery failed: no recipient available.Falló entrega: nadie para recibir.
`7`	Devuelto	Order returned to warehouse.Pedido devuelto a bodega.
`8`	Domicilio no encontrado	Address could not be located.No se encontró la dirección.
`9`	Rechazado	Customer rejected the order.Cliente rechazó el pedido.
`10`	No puede pagar recaudo	Customer unable to pay on delivery.Cliente no pudo pagar al recibir.
`11`	Pendiente recolección	Waiting for messenger pick up.Esperando recolección por mensajería.
`12`	Recolectado	Picked up by the messenger service.Recolectado por el servicio de mensajería.
`13`	Traslado	Being moved to distribution point.En traslado hacia punto de distribución.
`14`	Entregado-liquidado	Order delivered and payment settled.Pedido entregado y pago liquidado.
`15`	Devuelto a bodega	Delivered back to main warehouse.Entregado de vuelta en bodega.
`16`	Incidencia	General delivery issue.Incidencia general en la entrega.
`17`	Cancelado	Order cancelled.Pedido cancelado.
`18`	Correo	Order dispatched via postal mail, delivery pending confirmation.Pedido despachado por correo postal, entrega pendiente de confirmación.
`19`	Disponible para retirar en Agencia	Package available for pickup at the agency branch.Paquete disponible para retiro en agencia.

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.

Role Access & Capabilities: Accesos y Capacidades por Rol:

Role: Client
Use this role for Order Management: Create new orders, manage massive shipments, and control inventory.

Usa este rol para Gestión de Pedidos: Crear nuevos pedidos, administrar envíos masivos y controlar inventario.
Role: Provider
Use this role for Tracking & Visualization: View order history and real-time delivery status.

Usa este rol para Seguimiento y Visualización: Ver historial de pedidos y estado de entrega en tiempo real.

1. Get Token

1. Obtener Token

                        POST /api/auth/login
                        🔓 PublicPúblico
                    

Request Body

Cuerpo de la Petición

Field	Type	Required	Description
`email`	string	✅ Yes	Registered user email
`password`	string	✅ Yes	User password

Campo	Tipo	Req.	Descripción
`email`	string	✅ Sí	Email del usuario registrado
`password`	string	✅ Sí	Contraseña del usuario

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.

Authorization: Bearer <YOUR_TOKEN>

List & View

Listar y Ver

List Orders

Listar Pedidos

                            GET /api/pedidos/listar
                            🔐 AuthenticatedAutenticado
                        

Retrieve a list of orders with advanced filtering and pagination. Use these parameters to refine your results.

Obtén una lista de pedidos con filtrado avanzado y paginación. Usa estos parámetros para refinar tus resultados.

Query Parameters (Filters)

Parámetros de Consulta (Filtros)

ParameterParámetro	TypeTipo	DescriptionDescripción	ExampleEjemplo
`page`	int	Page number (default: 1)Número de página (defecto: 1)	`1`
`limit`	int	Results per page (max: 100)Resultados por página (máx: 100)	`20`
`numero_orden`	string	Order numberNúmero de orden externo	`88002`
`numero_cliente`	int	Client IDID del cliente	`10`

Sample Request

Ejemplo de Uso

GET /api/pedidos/listar?numero_orden=88002&numero_cliente=10

Get Single Order

Ver Pedido

                            GET /api/pedidos/ver?id=100
                            🔐 AuthenticatedAutenticado
                        

Returns full details of a specific order by Internal ID.

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.

⚠️ Strict Required Fields: ⚠️ Campos estrictos (obligatorios):

These fields are REQUIRED/STRICT. If any is missing, empty, or incorrect, the order WILL NOT be created and an HTTP 400 error will be returned with field-specific details.

Estos campos son REQUIRED/STRICT. Si falta alguno o viene vacío/incorrecto, el pedido NO se crea y se retorna HTTP 400 con detalle por campo.

📮 Auto-fill from Postal Code: 📮 Autocompletado desde Código Postal:

If you send codigo_postal, the system will automatically resolve and fill id_pais, id_departamento, id_municipio and id_barrio from the postal code database — these fields become optional when the CP is recognized.

Si envías codigo_postal, el sistema resolverá y completará automáticamente id_pais, id_departamento, id_municipio e id_barrio desde la base de códigos postales. Estos campos se vuelven opcionales cuando el CP es reconocido.

                        POST /api/pedidos/crear
                        🔐 AuthenticatedAutenticado
                        👤 Role: ClientRol: Cliente
                    

🔑 Required Fields (Strict)

🔑 Campos Obligatorios (Estrictos)

Field	Type	Validation	Description
`numero_orden`	integer/string	STRICT	External order ID
`destinatario`	string	STRICT	Recipient's full name
`producto_id`	array	STRICT if `requiere_productos` is 1 or omitted	Array of product objects/IDs. Optional when `"requiere_productos": 0` is sent in the body.
`id_cliente`	integer	STRICT, exists	Client ID owner
`id_proveedor`	integer	STRICT, exists	Messenger/Provider ID assigned
`telefono`	string	STRICT	Contact phone
`direccion`	string	STRICT	Full delivery address
`comentario`	string	STRICT	Delivery notes
`precio_total_local`	decimal	STRICT, > 0	Total local price
`es_combo`	integer	STRICT (0 or 1)	1 for combo, 0 for standard
`fecha_entrega`	string	STRICT, format YYYY-MM-DD	Estimated delivery date (e.g. "2026-03-15")

Campo	Tipo	Validación	Descripción
`numero_orden`	integer/string	ESTRICTO	ID externo del pedido
`destinatario`	string	ESTRICTO	Nombre del destinatario
`producto_id`	array	ESTRICTO si `requiere_productos` es 1 u omitido	Array de productos (objetos o IDs). Opcional cuando se envía `"requiere_productos": 0` en el body.
`id_cliente`	entero	ESTRICTO, existe	ID del cliente dueño
`id_proveedor`	entero	ESTRICTO, existe	ID del proveedor de mensajería asignado
`telefono`	string	ESTRICTO	Teléfono de contacto
`direccion`	string	ESTRICTO	Dirección completa
`comentario`	string	ESTRICTO	Notas de entrega
`precio_total_local`	decimal	ESTRICTO, > 0	Precio total local
`es_combo`	entero	ESTRICTO (0 o 1)	1 si es combo, 0 si estándar
`fecha_entrega`	string	ESTRICTO, formato YYYY-MM-DD	Fecha estimada de entrega (ej. "2026-03-15")

🚩 Body Flag: requiere_productos

Works exactly like es_combo — it’s a field you send in the JSON body:

Omitted or 1 → Products are required. Omitting productos/producto_id returns HTTP 422.
0 → Products are optional. The order is created without product items.
Any other value returns a validation error.

{ "requiere_productos": 0 }

🚩 Bandera en el Body: requiere_productos

Funciona igual que es_combo — es un campo que envías en el body JSON:

Omitido o 1 → Productos obligatorios. Omitir productos/producto_id retorna HTTP 422.
0 → Productos opcionales. El pedido se crea sin items de productos.
Cualquier otro valor retorna error de validación.

{ "requiere_productos": 0 }

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.

                        POST /api/pedidos/multiple?auto_enqueue=true
                        🔐 AuthenticatedAutenticado
                        👤 Role: ClientRol: Cliente
                    

📋 Optional Details (Automatic)

📋 Detalles Opcionales (Automáticos)

Field	Type	Default	Description
`coordenadas`	string	null	GPS format: "lat,long" (e.g. "14.6349,-90.5069")
`latitud`	float	null	Latitude (alternative to coordenadas)
`longitud`	float	null	Longitude (alternative to coordenadas)
`id_barrio`	integer	null	Neighborhood/District ID (if known)

Campo	Tipo	Defecto	Descripción
`coordenadas`	string	null	Formato GPS: "lat,long" (ej. "14.6349,-90.5069")
`latitud`	float	null	Latitud (alternativa a coordenadas)
`longitud`	float	null	Longitud (alternativa a coordenadas)
`id_barrio`	entero	null	ID del barrio/distrito (si se conoce)

🌍 Optional Fields - Geographic Auto-fill from CP

🌍 Campos Opcionales - Geográficos Auto desde CP

Field	Type	Description
`codigo_postal`	string	Postal code. When provided, auto-fills country, dept, municipality and neighborhood.
`id_pais` or `pais`	integer	Country ID. Optional if `codigo_postal` is recognized.
`id_departamento` or `departamento`	integer	State/Department ID. Optional if `codigo_postal` is recognized.
`id_municipio` or `municipio`	integer	City/Municipality ID. Optional if `codigo_postal` is recognized.
`id_barrio` or `barrio`	integer	Neighborhood/District ID. Optional, auto-filled from CP if available.
`zona`	string	Zone name. Optional.
`code_city` HLExpress	string	City code sent as `city_dane_code` to HLExpress. Takes priority over `codigo_postal` when dispatching to HLExpress. Example: `100075918`

Campo	Tipo	Descripción
`codigo_postal`	string	Código postal. Al enviarlo, el sistema auto-rellena país, depto, municipio y barrio.
`id_pais` o `pais`	entero	ID del país. Opcional si el `codigo_postal` es reconocido.
`id_departamento` o `departamento`	entero	ID del departamento. Opcional si el `codigo_postal` es reconocido.
`id_municipio` o `municipio`	entero	ID del municipio. Opcional si el `codigo_postal` es reconocido.
`id_barrio` o `barrio`	entero	ID del barrio. Opcional, se auto-rellena desde CP si está disponible.
`zona`	string	Nombre de la zona. Opcional.
`code_city` HLExpress	string	Código de ciudad enviado como `city_dane_code` a HLExpress. Tiene prioridad sobre `codigo_postal` al despachar a HLExpress. Ej: `100075918`

📍 Optional Fields - Special Address For orders without postal code

📍 Campos Opcionales - Dirección Especial Para pedidos sin código postal

When to use: Use these fields when the order destination does not have a registered postal code in the system. These are text-based fields for special orders (e.g. international clients like Panama). If codigo_postal is provided, these fields are stored but not displayed in views.

Cuándo usarlos: Usa estos campos cuando el destino del pedido no tiene un código postal registrado en el sistema. Son campos de texto libre para pedidos especiales (ej. clientes internacionales como Panamá). Si se envía codigo_postal, estos campos se guardan pero no se muestran en las vistas.

Field	Type	Max Length	Description
`departmentName`	string	150	Department/Province name (text)
`municipalitiesName`	string	150	Municipality/City name (text)
`postalCode`	string	20	Postal code (text, not homologated)
`Location`	string	255	Location reference (landmarks, plaza, etc.)
`betweenStreets`	string	255	Cross streets reference

Campo	Tipo	Largo Máx.	Descripción
`departmentName`	string	150	Nombre del departamento/provincia (texto)
`municipalitiesName`	string	150	Nombre del municipio/ciudad (texto)
`postalCode`	string	20	Código postal (texto, no homologado)
`Location`	string	255	Referencia de ubicación (punto de referencia, plaza, etc.)
`betweenStreets`	string	255	Referencia de entre calles

👥 Optional Fields - Assignments

👥 Campos Opcionales - Asignaciones

Field	Type	Default	Description
`id_estado`	integer	1	Order status (see Status Reference)
`id_vendedor`	integer	null	Assigned delivery person
`id_proveedor`	integer	✅ Yes	Messenger/Provider ID assigned to the order
`id_cliente`	integer	null	Client ID
`id_moneda`	integer	null	Currency ID (auto-detected from provider's country if not provided)
`requiere_productos`	integer	1	Product requirement flag: `1` = required (default), `0` = optional (order created without product items).

Campo	Tipo	Defecto	Descripción
`id_estado`	entero	1	Estado del pedido (ver Referencia de Estados)
`id_vendedor`	entero	null	Repartidor asignado
`id_proveedor`	entero	✅ Sí	ID del usuario de mensajería (Proveedor) asignado
`id_cliente`	entero	null	ID del cliente
`id_moneda`	entero	null	ID de la moneda (auto-detectada del país del proveedor si no se envía)
`requiere_productos`	entero	1	Bandera de productos: `1` = requeridos (defecto), `0` = opcionales (pedido se crea sin ítems de producto).

💰 Optional Fields - Pricing

💰 Campos Opcionales - Precios

Field	Type	Auto-calculated	Description
`precio_total_local`	decimal	No	Total price in local currency
`precio_total_usd`	decimal	Yes*	Total price in USD (auto-calc if local + currency provided)
`tasa_conversion_usd`	decimal	Yes*	Exchange rate used (auto-fetched from currency)
`es_combo`	boolean	Yes*	Whether it's a combo (auto-detected from product)

Campo	Tipo	Auto-calculado	Descripción
`precio_total_local`	decimal	No	Precio total en moneda local
`precio_total_usd`	decimal	Sí*	Precio total en USD (auto-calc si local + moneda)
`tasa_conversion_usd`	decimal	Sí*	Tasa de cambio usada (auto desde moneda)
`es_combo`	boolean	Sí*	Si es combo (auto-detectado desde producto)

❌ Error Response (Validation Error)

❌ Respuesta de Error (Falla de Validación)

When strict rules are not met, a 400 Bad Request is returned with a VALIDATION_ERROR message and a fields object mapping each field to its specific error.

Cuando no se cumplen las reglas estrictas, se devuelve 400 Bad Request con el mensaje VALIDATION_ERROR y un objeto fields que detalla el error por cada campo.

{
    "success": false,
    "message": "VALIDATION_ERROR",
    "fields": {
        "numero_orden": "El número de orden ya existe para este cliente.",
        "id_departamento": "El departamento no pertenece al país seleccionado.",
        "telefono": "El campo 'telefono' debe tener al menos 7 caracteres."
    }
}

✅ Automatic Validations

✅ Validaciones Automáticas

Geography Hierarchy: Rejects if Department doesn't match Country, or Municipality doesn't match Department.
CP Normalization: Postal codes are converted to uppercase and stripped of spaces/dashes before saving.
Order Uniqueness: Scoped by id_cliente to prevent collision between different clients' numbering.
Stock validation: Ensures sufficient inventory before creating order.
Foreign key validation: Verifies that all IDs (vendor, provider, client, currency) exist in database.

Jerarquía Geográfica: Rechaza si el Depto no coincide con el País, o el Muni no coincide con el Depto.
Normalización de CP: Los códigos postales se convierten a mayúsculas y se limpian de espacios/guiones.
Unicidad de Orden: Validada por id_cliente para evitar colisiones entre numeración de distintos clientes.
Validación de stock: Asegura inventario suficiente antes de crear.
Validación FK: Verifica que todos los IDs (vendedor, proveedor, cliente, moneda) existan en BD.

🔐 Security Rules

🔐 Reglas de Seguridad

Provider Assignment: This field is strict. You must explicitly provide the ID of the user (role Provider) who will handle the delivery.

Asignación de Proveedor: Este campo es estricto. Debes proporcionar explícitamente el ID del usuario (rol Proveedor) que gestionará la entrega.

📝 Example: Minimal Order (auto-fill from postal code)

📝 Ejemplo: Pedido Mínimo (auto-relleno desde código postal)

{
    "numero_orden": 697896,
    "destinatario": "Carlos Mendoza",
    "id_cliente": 9,
    "telefono": "(502) 5555-1234",
    "direccion": "6 Avenida 12-34 Zona 3",
    "comentario": "Dejar con el guardia si no hay nadie.",
    "id_proveedor": 12,
    "zona": "Zona 3 Centro",
    "codigo_postal": "46400",
    "fecha_entrega": "2026-03-15",
    "precio_total_local": 250.75,
    "es_combo": 1,
    "productos": [
        { "producto_id": 49, "cantidad": 10 }
    ]
    // id_pais, id_departamento, id_municipio se auto-rellenan desde el CP
}

🚚 Example: Order with HLExpress city code

🚚 Ejemplo: Pedido con código de ciudad HLExpress

HLExpress: When this order is dispatched to HLExpress, the code_city value is sent as city_dane_code. It takes priority over codigo_postal for this field.

HLExpress: Al despachar este pedido a HLExpress, el valor de code_city se envía como city_dane_code. Tiene prioridad sobre codigo_postal para ese campo.

{
    "numero_orden": 697896,
    "destinatario": "Carlos Mendoza",
    "id_cliente": 9,
    "telefono": "(502) 5555-1234",
    "direccion": "6 Avenida 12-34 Zona 3",
    "comentario": "Dejar con el guardia si no hay nadie.",
    "id_proveedor": 12,
    "codigo_postal": "46400",
    "code_city": "100075918",
    "fecha_entrega": "2026-03-15",
    "precio_total_local": 250.75,
    "es_combo": 1,
    "productos": [
        { "producto_id": 49, "cantidad": 10 }
    ]
}

📝 Example: Special Order (no postal code, custom address fields)

📝 Ejemplo: Pedido Especial (sin código postal, campos de dirección personalizados)

{
    "numero_orden": 697897,
    "destinatario": "Ana Sofia Ramos",
    "id_cliente": 9,
    "telefono": "50761234567",
    "direccion": "Calle 50, Edificio Global Bank, Piso 3",
    "comentario": "Entregar en recepción.",
    "id_proveedor": 12,
    "fecha_entrega": "2026-03-20",
    "precio_total_local": 320.00,
    "es_combo": 0,
    "departmentName": "Panamá",
    "municipalitiesName": "San Miguelito",
    "postalCode": "0801",
    "Location": "Plaza Central, frente al supermercado",
    "betweenStreets": "Entre Calle 5ta y Avenida Balboa",
    "productos": [
        { "producto_id": 49, "cantidad": 5 }
    ]
}

📝 Example: Manual location fields (IDs)

📝 Ejemplo: Campos de ubicación manuales (IDs)

{
    "numero_orden": 697898,
    "destinatario": "Roberto Fuentes",
    "id_cliente": 9,
    "telefono": "(502) 4444-9876",
    "direccion": "18 Calle 2-10 Zona 15",
    "comentario": "Llamar antes de entregar.",
    "id_proveedor": 12,
    "id_pais": 1,
    "id_departamento": 1,
    "id_municipio": 1,
    "zona": "Vista Hermosa",
    "fecha_entrega": "2026-03-20",
    "precio_total_local": 320.00,
    "es_combo": 1,
    "productos": [
        { "producto_id": 49, "cantidad": 5 }
    ]
}

📝 Example: Complete Multi-Product Combo

📝 Ejemplo: Pedido Completo con Múltiples Productos y Combo

{
    "numero_orden": 697898,
    "destinatario": "Roberto Fuentes",
    "id_cliente": 9,
    "telefono": "(502) 3333-5678",
    "direccion": "Diagonal 12 8-55 Zona 10",
    "comentario": "Entregar en horario de oficina.",
    "id_proveedor": 12,
    "zona": "Pradera",
    "codigo_postal": "01010",
    "id_moneda": 2,
    "fecha_entrega": "2026-03-25",
    "es_combo": 1,
    "precio_total_local": 780.50,
    "productos": [
        { "producto_id": 49, "cantidad": 3 },
        { "producto_id": 50, "cantidad": 2 }
    ]
}

📦 Example: Order Without Products (`requiere_productos: 0`)

📦 Ejemplo: Pedido Sin Productos (`requiere_productos: 0`)

⚠️ Note: When sending "requiere_productos": 0, omit the productos array entirely. The order is registered without product items.

⚠️ Nota: Al enviar "requiere_productos": 0, omite completamente el array productos. El pedido se registra sin ítems de producto.

{
    "numero_orden": 697900,
    "destinatario": "Maria López",
    "id_cliente": 9,
    "telefono": "50588887777",
    "direccion": "De la Catedral 2 cuadras al lago, Managua",
    "comentario": "Entregar en recepción.",
    "id_proveedor": 12,
    "codigo_postal": "11001",
    "fecha_entrega": "2026-03-20",
    "precio_total_local": 450.00,
    "es_combo": 0,
    "requiere_productos": 0
    // No se incluye el campo "productos" — el pedido se crea sin ítems
}

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.

                        POST /api/pedidos/multiple?auto_enqueue=true
                        🔐 AuthenticatedAutenticado
                    

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": [
        {
            "numero_orden": 697901,
            "destinatario": "Luis Herrera",
            "id_cliente": 9,
            "telefono": "(502) 1111-2222",
            "direccion": "Ruta Nacional 9 Km 45",
            "comentario": "Entregar en recepción.",
            "id_proveedor": 12,
            "codigo_postal": "46400",
            "fecha_entrega": "2026-03-15",
            "precio_total_local": 250.75,
            "es_combo": 1,
            "productos": [
                { "producto_id": 49, "cantidad": 5 },
                { "producto_id": 50, "cantidad": 3 }
            ]
        },
        {
            "numero_orden": 697902,
            "destinatario": "Marta Lopez",
            "id_cliente": 9,
            "telefono": "(502) 3333-4444",
            "direccion": "Colonia El Naranjo Mz. 4",
            "comentario": "Tocar timbre dos veces.",
            "id_proveedor": 12,
            "codigo_postal": "46400",
            "fecha_entrega": "2026-03-22",
            "precio_total_local": 480.00,
            "es_combo": 1,
            "productos": [
                { "producto_id": 49, "cantidad": 2 },
                { "producto_id": 51, "cantidad": 1 }
            ]
        }
    ]
}

Currency Management (Monedas)

Gestión de Monedas

Administrative endpoints to list, create, update and delete currencies.

Endpoints administrativos para listar, crear, actualizar y eliminar monedas.

GET /api/monedas/listar

GET /api/monedas/ver?id=1

POST /api/monedas/crear

POST/PUT /api/monedas/actualizar?id=1

DELETE /api/monedas/eliminar?id=1

Auth: Auth: Requires Bearer token with permissions for currency administration. Requiere Bearer token con permisos de administración de monedas.

Product Management

Gestión de Productos

                            GET /api/productos/listar
                            🔓 PublicPúblico
                        

List all available products with current stock.

Listar todos los productos disponibles con stock actual.

Query Parameters

Parámetros de Consulta

Parameter	Type	Description
`page`	integer	Page number (default 1)
`limit`	integer	Items per page (default 50)
`id_cliente`	integer	Filter by Creator/Client ID
`categoria_id`	integer	Filter by Category ID
`marca`	string	Filter by Brand name (exact match)
`sku`	string	Filter by exact SKU
`activo`	boolean	Filter by active status (1/0 or true/false)

Parámetro	Tipo	Descripción
`page`	entero	Número de página (defecto 1)
`limit`	entero	Items por página (defecto 50)
`id_cliente`	entero	Filtrar por ID de Cliente/Creador
`categoria_id`	entero	Filtrar por ID de Categoría
`marca`	string	Filtrar por Marca (coincidencia exacta)
`sku`	string	Filtrar por SKU exacto
`activo`	boolean	Filtrar por estado activo (1/0 o true/false)

📝 Usage Examples

📝 Ejemplos de Uso

# 1. List products created by client ID 15
GET /api/productos/listar?id_cliente=15

# 2. List only active products in category 8
GET /api/productos/listar?activo=1&categoria_id=8

# 3. Filter by brand
GET /api/productos/listar?marca=Samsung

# 4. Combined filter with pagination
GET /api/productos/listar?id_cliente=15&activo=1&page=2&limit=10

                            POST /api/productos/crear
                            🔐 AuthenticatedAutenticado
                            👤 Role: ClientRol: Cliente
                        

Create a new product.

Crear un nuevo producto.

Request Body

Cuerpo de la Petición

FieldCampo	TypeTipo	Req.Req.	DescriptionDescripción
`nombre`	string	✅	Product nameNombre del producto
`sku`	string	❌	Unique identifier (SKU)Identificador único (SKU)
`descripcion`	string	❌	Product descriptionDescripción del producto
`precio_usd`	number	❌	Price in USDPrecio en USD
`stock`	integer	❌	Initial stock levelNivel de stock inicial

Product Object Model

Modelo de Objeto Producto

{
    "id": 1,
    "nombre": "Protein Shake",
    "sku": "PROT-SHK-001",
    "precio_usd": "45.00",
    "stock_total": 150,
    "descripcion": "High quality whey protein"
}

Update & Delete

Actualizar y Eliminar

Update Product

Actualizar Producto

                            POST /api/productos/actualizar
                            🔐 AuthenticatedAutenticado
                            👤 Role: ClientRol: Cliente
                        

Note: Use POST with id param or check PHP config for PUT support.

{
    "id": 1,
    "nombre": "Protein Shake V2",
    "sku": "PROT-SHK-001-B",
    "precio_usd": 48.00,
    "descripcion": "New formula"
}

Get Single Product

Ver Producto Individual

                            GET /api/productos/ver?id=1
                            🔓 PublicPúblico
                        

🗺️ Get All Geographic Data

🗺️ Obtener Todos los Datos Geográficos

Retrieve complete hierarchical geographic data (countries, departments, municipalities, neighborhoods).

Obtener datos geográficos jerárquicos completos (países, departamentos, municipios, barrios).

                        GET /api/geoinfo/listar
                        🔓 PublicPúblico
                    

Response Structure

Estructura de Respuesta

{
    "success": true,
    "data": {
        "paises": [
            { "id": 1, "nombre": "Nicaragua", "codigo_iso": "NI" }
        ],
        "departamentos": [
            { "id": 1, "nombre": "Managua", "id_pais": 1 }
        ],
        "municipios": [
            { "id": 1, "nombre": "Managua", "id_departamento": 1, "codigo_postal": "10000" }
        ],
        "barrios": [
            { "id": 1, "nombre": "Altamira", "id_municipio": 1, "codigo_postal": "10100" }
        ]
    }
}

🌎 Countries (Países)

🌎 Países

List All Countries

Listar Todos los Países

                            GET /api/geoinfo/paises
                            🔓 PublicPúblico
                        

// Response
[
    {
        "id": 1,
        "nombre": "Nicaragua",
        "codigo_iso": "NI",
        "id_moneda_local": 1
    },
    {
        "id": 2,
        "nombre": "Honduras",
        "codigo_iso": "HN",
        "id_moneda_local": 2
    }
]

Get Single Country

Obtener País Individual

                            GET /api/geoinfo/paises?id=1
                            🔓 PublicPúblico
                        

🏛️ Departments (Departamentos)

🏛️ Departamentos

List All Departments

Listar Todos los Departamentos

                            GET /api/geoinfo/departamentos
                            🔓 PublicPúblico
                        

Filter by Country

Filtrar por País

                            GET /api/geoinfo/departamentos?id_pais=1
                            🔓 PublicPúblico
                        

Parameter	Type	Description
`id_pais`	integer	Filter departments by country ID

Parámetro	Tipo	Descripción
`id_pais`	entero	Filtrar departamentos por ID de país

// Response
[
    {
        "id": 1,
        "nombre": "Managua",
        "id_pais": 1
    },
    {
        "id": 2,
        "nombre": "Granada",
        "id_pais": 1
    }
]

🏘️ Municipalities (Municipios)

🏘️ Municipios

List All Municipalities

Listar Todos los Municipios

                            GET /api/geoinfo/municipios
                            🔓 PublicPúblico
                        

Filter by Department

Filtrar por Departamento

                            GET /api/geoinfo/municipios?id_departamento=1
                            🔓 PublicPúblico
                        

Parameter	Type	Description
`id_departamento`	integer	Filter municipalities by department ID

Parámetro	Tipo	Descripción
`id_departamento`	entero	Filtrar municipios por ID de departamento

// Response
[
    {
        "id": 1,
        "nombre": "Managua",
        "id_departamento": 1,
        "codigo_postal": "10000"
    },
    {
        "id": 2,
        "nombre": "Tipitapa",
        "id_departamento": 1,
        "codigo_postal": "11000"
    }
]

🏠 Neighborhoods (Barrios)

🏠 Barrios

List All Neighborhoods

Listar Todos los Barrios

                            GET /api/geoinfo/barrios
                            🔓 PublicPúblico
                        

Filter by Municipality

Filtrar por Municipio

                            GET /api/geoinfo/barrios?id_municipio=1
                            🔓 PublicPúblico
                        

Parameter	Type	Description
`id_municipio`	integer	Filter neighborhoods by municipality ID

Parámetro	Tipo	Descripción
`id_municipio`	entero	Filtrar barrios por ID de municipio

// Response
[
    {
        "id": 1,
        "nombre": "Altamira",
        "id_municipio": 1,
        "codigo_postal": "10100"
    },
    {
        "id": 2,
        "nombre": "Bolonia",
    }\n]\

📮 Postal Codes (Códigos Postales)

📮 Códigos Postales

Resolve postal codes to geographic locations or find postal codes by zone.

Resolver códigos postales a ubicaciones geográficas o buscar códigos postales por zona.

Resolve Postal Code

Resolver Código Postal

                            GET /api/geoinfo/codigos_postales?action=resolve&cp=<cp>[&id_pais=<id>]
                            🔓 PublicPúblico
                        

ParameterParámetro	TypeTipo	Req.Req.	DescriptionDescripción
`cp`	string	✅	Postal code to searchCódigo postal a buscar
`id_pais`	integer	❌	Filter by specific country IDFiltrar por ID de país específico

// Response Example (Single Match/Specific)
{
    "ok": true,
    "data": {
        "normalized_cp": "08001",
        "matches": [
            {
                "id_codigo_postal": 542,
                "id_pais": 1,
                "pais": "España",
                "codigo_postal": "08001",
                "id_departamento": 8,
                "departamento": "Barcelona",
                "id_municipio": 12,
                "municipio": "Barcelona",
                "id_barrio": null,
                "barrio": null,
                "partial": false
            }
        ]
    }
}

Find by Zone

Buscar por Zona

Get the postal code for a specific neighborhood.

Obtener el código postal para un barrio específico.

                            GET /api/geoinfo/codigos_postales?action=find_by_zone&id_pais=<id>&id_barrio=<id>
                            🔓 PublicPúblico
                        

🔍 Unified Search

🔍 Búsqueda Unificada

Search across all geographic entities (países, departamentos, municipios, barrios) with autocomplete/typeahead functionality.

Buscar en todas las entidades geográficas (países, departamentos, municipios, barrios) con funcionalidad de autocomplete/typeahead.

                        GET /api/geoinfo/buscar?q=<query>
                        🔓 PublicPúblico
                    

Query Parameters

Parámetros de Consulta

Parameter	Type	Required	Description
`q`	string	✅ Yes	Search query (min 2 chars)
`tipo`	string	❌ No	Filter by type: `pais`, `departamento`, `municipio`, `barrio`
`pais_id`	integer	❌ No	Filter results within country
`departamento_id`	integer	❌ No	Filter results within department
`municipio_id`	integer	❌ No	Filter results within municipality

Parámetro	Tipo	Requerido	Descripción
`q`	string	✅ Sí	Consulta de búsqueda (mín 2 caracteres)
`tipo`	string	❌ No	Filtrar por tipo: `pais`, `departamento`, `municipio`, `barrio`
`pais_id`	entero	❌ No	Filtrar resultados dentro de país
`departamento_id`	entero	❌ No	Filtrar resultados dentro de departamento
`municipio_id`	entero	❌ No	Filtrar resultados dentro de municipio

Example Requests

Ejemplos de Peticiones

# 1. Basic search (all types)
GET /api/geoinfo/buscar?q=Guatemala

# 2. Search only countries
GET /api/geoinfo/buscar?q=Guat&tipo=pais

# 3. Search municipalities containing "San"
GET /api/geoinfo/buscar?q=San&tipo=municipio

# 4. Search within specific country (Nicaragua = 1)
GET /api/geoinfo/buscar?q=San&tipo=municipio&pais_id=1

# 5. Search neighborhoods in specific municipality
GET /api/geoinfo/buscar?q=Alta&tipo=barrio&municipio_id=1

# 6. Autocomplete for cascading dropdown
GET /api/geoinfo/buscar?q=Mana&tipo=departamento&pais_id=1

Practical Use Cases

Casos de Uso Prácticos

🎯 Use Case 1: Country Autocomplete 🎯 Caso de Uso 1: Autocomplete de País

// User types "Gua"
fetch('/api/geoinfo/buscar?q=Gua&tipo=pais')
  .then(r => r.json())
  .then(data => {
    // Shows: Guatemala, Guinea, etc.
    populateCountryDropdown(data.data);
  });

🎯 Use Case 2: Cascading Location Selector 🎯 Caso de Uso 2: Selector de Ubicación en Cascada

// Step 1: User selects country
const selectedCountryId = 6; // Guatemala

// Step 2: Search departments in that country
fetch(`/api/geoinfo/buscar?q=${userInput}&tipo=departamento&pais_id=${selectedCountryId}`)
  .then(r => r.json())
  .then(data => populateDepartmentDropdown(data.data));

// Step 3: Search municipalities in selected department
const selectedDepartmentId = 80;
fetch(`/api/geoinfo/buscar?q=${userInput}&tipo=municipio&departamento_id=${selectedDepartmentId}`)
  .then(r => r.json())
  .then(data => populateMunicipalityDropdown(data.data));

🎯 Use Case 3: Quick Global Search 🎯 Caso de Uso 3: Búsqueda Global Rápida

// Search everywhere, get prioritized results
fetch('/api/geoinfo/buscar?q=Managua')
  .then(r => r.json())
  .then(data => {
    // Returns:
    // 1. Departamento "Managua" (priority 3)
    // 2. Municipio "Managua" (priority 5)
    displayResults(data.data);
  });

Example Response

Ejemplo de Respuesta

{
    "success": true,
    "data": [
        {
            "id": 6,
            "tipo": "pais",
            "nombre": "Guatemala",
            "codigo_iso": "GUAT",
            "codigo_postal": null,
            "id_pais": null,
            "pais": null,
            "id_departamento": null,
            "departamento": null,
            "id_municipio": null,
            "municipio": null
        },
        {
            "id": 80,
            "tipo": "departamento",
            "nombre": "Guatemala",
            "codigo_iso": null,
            "codigo_postal": null,
            "id_pais": 6,
            "pais": "Guatemala",
            "id_departamento": null,
            "departamento": null,
            "id_municipio": null,
            "municipio": null
        },
        {
            "id": 1278,
            "tipo": "municipio",
            "nombre": "Antigua Guatemala",
            "codigo_iso": null,
            "codigo_postal": "3001",
            "id_pais": 6,
            "pais": "Guatemala",
            "id_departamento": 89,
            "departamento": "Sacatepequez",
            "id_municipio": null,
            "municipio": null
        },
        {
            "id": 7747,
            "tipo": "barrio",
            "nombre": "Antigua Guatemala",
            "codigo_iso": null,
            "codigo_postal": "3001",
            "id_pais": 6,
            "pais": "Guatemala",
            "id_departamento": 89,
            "departamento": "Sacatepequez",
            "id_municipio": 1278,
            "municipio": "Antigua Guatemala"
        }
    ],
    "query": "Guatemala",
    "filters": []
}

💡 Key Features 💡 Características Clave

Priority Ordering: Countries first, then departments, municipalities, and neighborhoods
Postal Codes: Neighborhoods inherit postal code from parent municipality if not set
Hierarchical Data: Includes parent entity names for complete context
Performance: Limited to 20 results, perfect for autocomplete/typeahead

Orden por Prioridad: Países primero, luego departamentos, municipios y barrios
Códigos Postales: Barrios heredan código postal del municipio si no tienen
Datos Jerárquicos: Incluye nombres de entidades padre para contexto completo
Rendimiento: Limitado a 20 resultados, perfecto para autocomplete/typeahead

Messenger Application API

API App de Mensajería

Specialized endpoints for the delivery provider app.

Endpoints especializados para la app de los proveedores de mensajería (logística).

Assigned Orders

Mis Asignaciones

Get list of orders assigned to the authenticated provider.

Obtener lista de pedidos asignados al proveedor autenticado.

                                GET /api/mensajeria/pedidos?page=1&limit=20
                                👤 Role: MessengerRol: Mensajería
                            

Field / Campo	Req.	Type	Description
`page`	No	integer	Page number (default: 1). Número de página (por defecto: 1).
`limit`	No	integer	Items per page (default: 20, max: 100). Items por página (por defecto: 20, máx: 100).
`estado`	No	integer	Filter by status ID. Filtrar por ID de estado.

{
    "success": true,
    "data": [
        {
            "ID_Pedido": 100,
            "Numero_Orden": "ORD-2025-001",
            "Estado": "En ruta",
            "Cliente": "Juan Pérez"
        }
    ],
    "pagination": {
        "total": 45,
        "page": 1,
        "limit": 20,
        "total_pages": 3
    }
}

Change Order Status

Cambiar Estado de Pedido

Allows providers and clients to update delivery progress states. Permission rules apply based on role.

Permite a proveedores y clientes actualizar los estados de progreso de entrega. Se aplican reglas de permiso según el rol.

🔒 Role-based restrictions: 🔒 Restricciones por rol:

Client (rol=4): Cannot set status to Entregado (3) or Devuelto (7). Also blocked if order is already in those states.
Messenger/Provider (rol=5): Full access — can use any state including 3 and 7.
Admin: No restrictions.

Cliente (rol=4): No puede usar Entregado (3) ni Devuelto (7) como destino. Tampoco puede modificar un pedido que ya esté en esos estados.
Mensajería/Proveedor (rol=5): Acceso completo — puede usar cualquier estado incluyendo 3 y 7.
Admin: Sin restricciones.

                                POST /api/mensajeria/cambiar_estado
                                👤 Role: MessengerRol: Mensajería
                            

Field / Campo	Req.	Allowed Values / Valores Permitidos	Description
`id_pedido`	Cond.	integer (ID)	Internal Order ID. Required if `numero_orden` not provided. ID interno del pedido. Requerido si no se envía `numero_orden`.
`numero_orden`	Cond.	string	External Order Number. Required if `id_pedido` not provided. Número de orden externo. Requerido si no se envía `id_pedido`.
`estado`	Yes	integer	Target Status ID (e.g., 3: Delivered, 4: Rescheduled, 7: Returned). ID del estado destino (ej: 3: Entregado, 4: Reprogramado, 7: Devuelto).
`motivo`	Cond.	string	Reason. Mandatory if status=7. Motivo. Obligatorio si estado=7.

By ID

Por ID

{
    "id_pedido": 150,
    "estado": 4,
    "motivo": "Reprogramar"
}

By Order Num

Por Núm. Orden

{
    "numero_orden": "EXT-88002",
    "estado": 4,
    "motivo": "Reprogramar"
}

Return (Mandatory Motive)

Devolución (Motivo Oblig.)

{
    "numero_orden": "EXT-88002",
    "estado": 7,
    "motivo": "Dirección incorrecta"
}

Error Response (Forbidden transition)

Respuesta de Error (Transición prohibida)

{
    "success": false,
    "message": "No se puede cambiar el estado de un pedido que ya ha sido entregado."
}

Order Status History

Historial de Cambios de Estado

This endpoint allows you to query the full audit trail of status changes for any order. Each record shows the previous state, the new state, the comment left at the time of the change, and who performed it.

Este endpoint permite consultar el historial completo de cambios de estado de los pedidos. Cada registro muestra el estado anterior, el estado nuevo, el comentario del cambio y quién lo realizó.

                        GET /api/pedidos/historial
                        🔐 AuthenticatedAutenticado
                    

💡 Tip: 💡 Tip: All filters are optional and can be combined freely. Without filters, all history is returned paginated. Todos los filtros son opcionales y combinables libremente. Sin filtros, se devuelve todo el historial paginado.

Query Parameters

Parámetros de Consulta

Parameter	Type	Default	Description	Example
`numero_orden`	string	—	Filter by order number	`100045`
`id_pedido`	integer	—	Filter by internal order ID	`45`
`id_estado_anterior`	integer	—	Filter by exact previous state ID	`1`
`id_estado_nuevo`	integer	—	Filter by exact new state ID	`3`
`id_estados`	string	—	Comma-separated state IDs — matches previous OR new state	`1,2,3`
`fecha_desde`	date	—	Start date of the change (Y-m-d)	`2026-03-01`
`fecha_hasta`	date	—	End date of the change (Y-m-d)	`2026-03-31`
`id_usuario`	integer	—	Filter by user who made the change	`7`
`page`	integer	1	Page number	`2`
`limit`	integer	20	Records per page (max 100)	`50`

Parámetro	Tipo	Defecto	Descripción	Ejemplo
`numero_orden`	string	—	Filtrar por número de orden	`100045`
`id_pedido`	entero	—	Filtrar por ID interno del pedido	`45`
`id_estado_anterior`	entero	—	Filtrar por ID exacto del estado anterior	`1`
`id_estado_nuevo`	entero	—	Filtrar por ID exacto del estado nuevo	`3`
`id_estados`	string	—	IDs de estados separados por coma — coincide con anterior O nuevo	`1,2,3`
`fecha_desde`	fecha	—	Fecha inicio del cambio (Y-m-d)	`2026-03-01`
`fecha_hasta`	fecha	—	Fecha fin del cambio (Y-m-d)	`2026-03-31`
`id_usuario`	entero	—	Filtrar por usuario que realizó el cambio	`7`
`page`	entero	1	Número de página	`2`
`limit`	entero	20	Registros por página (máx 100)	`50`

Usage Examples

Ejemplos de Uso

1. Full history (paginated)

1. Historial completo (paginado)

GET /api/pedidos/historial
Authorization: Bearer <YOUR_TOKEN>

2. History for a specific order

2. Historial de un pedido específico

GET /api/pedidos/historial?numero_orden=100045
Authorization: Bearer <YOUR_TOKEN>

3. Changes to "Delivered" state in March 2026

3. Cambios a estado "Entregado" en marzo 2026

GET /api/pedidos/historial?id_estado_nuevo=3&fecha_desde=2026-03-01&fecha_hasta=2026-03-31
Authorization: Bearer <YOUR_TOKEN>

4. Orders that passed through states 1, 2 or 7

4. Pedidos que pasaron por los estados 1, 2 o 7

GET /api/pedidos/historial?id_estados=1,2,7&page=1&limit=50
Authorization: Bearer <YOUR_TOKEN>

5. Full cURL example

5. Ejemplo completo con cURL

curl -X GET "http://localhost/paqueteriacz/api/pedidos/historial?numero_orden=100045&page=1&limit=20" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLC..." \
  -H "Content-Type: application/json"

6. JavaScript (fetch)

const params = new URLSearchParams({
  numero_orden: '100045',
  page: 1,
  limit: 20
});

const res = await fetch(`/api/pedidos/historial?${params}`, {
  headers: { 'Authorization': 'Bearer ' + token }
});
const json = await res.json();
console.log(json.data);       // array de cambios
console.log(json.pagination); // metadatos de paginación

7. PHP (cURL)

$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL            => 'http://localhost/paqueteriacz/api/pedidos/historial?numero_orden=100045',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $token]
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

foreach ($response['data'] as $cambio) {
    echo $cambio['fecha_cambio'] . ': '
       . $cambio['estado_anterior'] . ' → '
       . $cambio['estado_nuevo'] . PHP_EOL;
}

Response Structure

Estructura de Respuesta

Success 200 OK

Éxito 200 OK

{
    "success": true,
    "message": "Se encontraron 42 registros en el historial.",
    "data": [
        {
            "id": 12,
            "id_pedido": 45,
            "numero_orden": "100045",
            "id_estado_anterior": 1,
            "estado_anterior": "En bodega",
            "id_estado_nuevo": 2,
            "estado_nuevo": "En ruta o proceso",
            "comentario": "Recogido por mensajero",
            "id_usuario": 7,
            "realizado_por": "Juan Pérez",
            "fecha_cambio": "2026-03-04 09:30:00"
        },
        {
            "id": 11,
            "id_pedido": 45,
            "numero_orden": "100045",
            "id_estado_anterior": null,
            "estado_anterior": null,
            "id_estado_nuevo": 1,
            "estado_nuevo": "En bodega",
            "comentario": null,
            "id_usuario": 3,
            "realizado_por": "María García",
            "fecha_cambio": "2026-03-03 14:00:00"
        }
    ],
    "pagination": {
        "total": 42,
        "per_page": 20,
        "current_page": 1,
        "total_pages": 3,
        "has_next": true,
        "has_prev": false
    }
}

Response Fields

Campos de la Respuesta

Field	Type	Description
`id`	integer	Unique ID of the history record
`id_pedido`	integer	Internal order ID
`numero_orden`	string	Order number (client reference)
`id_estado_anterior`	integer\|null	Previous state ID (null if this was the first transition)
`estado_anterior`	string\|null	Previous state name
`id_estado_nuevo`	integer	New state ID after the change
`estado_nuevo`	string	New state name
`comentario`	string\|null	Observation or comment recorded at the time of the change
`id_usuario`	integer	ID of the user who made the change
`realizado_por`	string	Full name of the user who made the change
`fecha_cambio`	datetime	Date and time of the state change

Campo	Tipo	Descripción
`id`	entero	ID único del registro de historial
`id_pedido`	entero	ID interno del pedido
`numero_orden`	string	Número de orden (referencia del cliente)
`id_estado_anterior`	entero\|null	ID del estado anterior (null si es la primera transición)
`estado_anterior`	string\|null	Nombre del estado anterior
`id_estado_nuevo`	entero	ID del estado nuevo después del cambio
`estado_nuevo`	string	Nombre del estado nuevo
`comentario`	string\|null	Observación o comentario registrado al momento del cambio
`id_usuario`	entero	ID del usuario que realizó el cambio
`realizado_por`	string	Nombre completo del usuario que realizó el cambio
`fecha_cambio`	datetime	Fecha y hora del cambio de estado

Error Responses

Respuestas de Error

// 401 - No token
{
    "success": false,
    "message": "Token de autorización requerido.",
    "data": null
}

// 400 - Bad date format
{
    "success": false,
    "message": "Formato de fecha_desde inválido. Use Y-m-d (ej: 2026-03-01).",
    "data": null
}

State ID Reference

Referencia de IDs de Estado

Use these IDs in id_estado_anterior, id_estado_nuevo or id_estados filter parameters.

Usa estos IDs en los parámetros de filtro id_estado_anterior, id_estado_nuevo o id_estados.

ID	State NameNombre del Estado	CategoryCategoría	DescriptionDescripción
`1`	En bodega	InitialInicial	Order received and stored at warehousePedido recibido y almacenado en bodega
`2`	En ruta o proceso	In TransitEn tránsito	Order is out for deliveryPedido en camino al destinatario
`3`	Entregado	CompletedCompletado	Order successfully delivered to recipientPedido entregado exitosamente al destinatario
`4`	Reprogramado	RescheduledReprogramado	Delivery rescheduled for another day/timeEntrega reprogramada para otra fecha/hora
`5`	Domicilio cerrado	IssueIncidencia	Delivery failed: location was closedFalló la entrega: el domicilio estaba cerrado
`6`	No hay quien reciba	IssueIncidencia	Delivery failed: no one available to receiveFalló la entrega: nadie disponible para recibir
`7`	Devuelto	ReturnedDevuelto	Order returned to warehousePedido devuelto a bodega
`8`	Domicilio no encontrado	IssueIncidencia	Address could not be locatedLa dirección no pudo ser ubicada
`9`	Rechazado	RejectedRechazado	Customer refused to receive the orderEl cliente rechazó recibir el pedido
`10`	No puede pagar recaudo	IssueIncidencia	Customer unable to pay cash on deliveryCliente no pudo pagar el recaudo al recibir
`11`	Pendiente recolección	In TransitEn tránsito	Waiting for messenger pick upEsperando recolección por mensajería
`12`	Recolectado por mensajería	In TransitEn tránsito	Picked up by the messenger serviceRecolectado por el servicio de mensajería
`13`	Traslado a punto	In TransitEn tránsito	Being moved to distribution pointEn traslado hacia punto de distribución
`14`	Entregado-liquidado	SettledLiquidado	Order delivered and payment settledPedido entregado y pago liquidado
`15`	Devuelto a bodega	ReturnedDevuelto	Final return: delivered back to main warehouseDevolución final: entregado de vuelta en bodega
`16`	Incidencia	IssueIncidencia	General delivery issueIncidencia general en la entrega
`17`	Cancelado	CancelledCancelado	Order cancelledPedido cancelado
`18`	Correo	In TransitEn tránsito	Order dispatched via postal mail, delivery pending confirmationPedido despachado por correo postal, entrega pendiente de confirmación
`19`	Disponible para retirar en Agencia	Pending PickupPendiente retiro	Package could not be delivered to address; available for pickup at agency branchEl paquete no pudo entregarse en domicilio; disponible para retiro en agencia

⚠️ Note: ⚠️ Nota: The list of states above may grow over time. Use GET /api/pedidos/estados to always retrieve the current, up-to-date list from the database. La lista de estados puede crecer con el tiempo. Usa GET /api/pedidos/estados para obtener siempre la lista actualizada desde la base de datos.

🔧 How history records are created: 🔧 Cómo se generan los registros del historial:

Each state change is recorded automatically by a database trigger (AFTER UPDATE on pedidos).
When an operator adds a comment/observation during a state change (e.g. from the Logistics dashboard), the PHP layer updates the observaciones column of the latest history record for that order.
This two-step approach prevents duplicate entries — the trigger owns the INSERT, PHP only annotates it.

Cada cambio de estado es registrado automáticamente por un trigger de base de datos (AFTER UPDATE sobre la tabla pedidos).
Cuando un operador incluye un comentario/observación durante el cambio de estado (por ejemplo desde el panel de Logística), la capa PHP actualiza la columna observaciones del último registro de historial de ese pedido.
Este enfoque en dos pasos evita entradas duplicadas: el trigger es dueño del INSERT, PHP solo lo anota.

⚙️ Logistics Job Status

⚙️ Estado de Jobs Logísticos

Returns processing jobs related to logistics automation (validation, guide generation, tracking updates) for one or many orders.

Devuelve los trabajos de procesamiento relacionados con automatización logística (validación, guía, tracking) para uno o varios pedidos.

                        GET /api/pedidos/status
                        🔐 AuthenticatedAutenticado
                    

Modes

Modos

?numero_orden=87416381 Single order
?numeros_orden=87416381,87416382 Batch (max 50)
No params: provider dashboard summary

?numero_orden=87416381 Pedido único
?numeros_orden=87416381,87416382 Lote (máx 50)
Sin parámetros: resumen de dashboard del proveedor

Single Response 200 OK

Respuesta Single 200 OK

{
  "success": true,
  "message": "Estado trabajos pedido",
  "data": {
    "numero_orden": "87416381",
    "has_jobs": true,
    "jobs": [
      {
        "job_type": "validar_direccion",
        "status": "completed",
        "attempts": 1,
        "updated_at": "2026-04-08 14:20:00",
        "error": null
      }
    ],
    "observacion_estado": "Estado cambiado automáticamente",
    "fecha_observacion_estado": "2026-04-07 16:15:00",
    "observacion_por": "Proveedor RutaEX Pulox CR"
  }
}

Batch Response 200 OK

Respuesta Batch 200 OK

{
  "success": true,
  "message": "Resultados batch",
  "data": {
    "results": [
      {
        "numero_orden": "87416381",
        "found": true,
        "jobs": [],
        "observacion_estado": null,
        "fecha_observacion_estado": null,
        "observacion_por": null
      }
    ]
  }
}

📦 Current Order Status

📦 Estado Actual de Pedidos

Returns the current state of each order directly from the pedidos table. Unlike /historial (which shows state changes), this endpoint shows every order with its present status — including orders that have never had a recorded state change.

Devuelve el estado actual de cada pedido directamente desde la tabla pedidos. A diferencia de /historial (que muestra cambios de estado), este endpoint muestra todos los pedidos con su estado vigente — incluyendo pedidos que nunca tuvieron un cambio de estado registrado.

                        GET /api/pedidos/estado_pedidos
                        🔐 AuthenticatedAutenticado
                    

💡 When to use this vs /historial: 💡 ¿Cuándo usar este vs /historial?

Use /estado_pedidos to know where an order is right now.
Use /historial to see how it got there (the full audit trail of transitions).

Usa /estado_pedidos para saber dónde está un pedido ahora mismo.
Usa /historial para ver cómo llegó ahí (trazabilidad completa de transiciones).

Query Parameters

Parámetros de Consulta

Parameter	Type	Default	Description	Example
`numero_orden`	string	—	Exact order number	`81154737`
`id_estado`	integer	—	Filter by current state ID	`1`
`id_cliente`	integer	—	Filter by client ID	`5`
`id_proveedor`	integer	—	Filter by provider/messenger ID	`3`
`fecha_desde`	date	—	Order entry date start (Y-m-d)	`2026-03-01`
`fecha_hasta`	date	—	Order entry date end (Y-m-d)	`2026-03-31`
`page`	integer	1	Page number	`2`
`limit`	integer	20	Records per page (max 100)	`50`

Parámetro	Tipo	Defecto	Descripción	Ejemplo
`numero_orden`	string	—	Número de orden exacto	`81154737`
`id_estado`	entero	—	Filtrar por ID de estado actual	`1`
`id_cliente`	entero	—	Filtrar por ID de cliente	`5`
`id_proveedor`	entero	—	Filtrar por ID de proveedor/mensajero	`3`
`fecha_desde`	fecha	—	Fecha ingreso desde (Y-m-d)	`2026-03-01`
`fecha_hasta`	fecha	—	Fecha ingreso hasta (Y-m-d)	`2026-03-31`
`page`	entero	1	Número de página	`2`
`limit`	entero	20	Registros por página (máx 100)	`50`

Usage Examples

Ejemplos de Uso

1. All orders (paginated)

1. Todos los pedidos (paginado)

GET /api/pedidos/estado_pedidos
Authorization: Bearer <YOUR_TOKEN>

2. Specific order

2. Pedido específico

GET /api/pedidos/estado_pedidos?numero_orden=81154737
Authorization: Bearer <YOUR_TOKEN>

3. All orders currently "En bodega"

3. Todos los pedidos actualmente en bodega

GET /api/pedidos/estado_pedidos?id_estado=1&page=1&limit=50
Authorization: Bearer <YOUR_TOKEN>

4. Orders by date range

4. Pedidos por rango de fecha

GET /api/pedidos/estado_pedidos?fecha_desde=2026-03-01&fecha_hasta=2026-03-20
Authorization: Bearer <YOUR_TOKEN>

Response 200 OK

Respuesta 200 OK

{
    "success": true,
    "message": "Se encontraron 3 pedidos.",
    "data": [
        {
            "id": 45,
            "numero_orden": "81154737",
            "destinatario": "Juan Pérez",
            "id_estado": 1,
            "estado_actual": "En bodega",
            "observacion_estado": "Estado cambiado automáticamente",
            "fecha_observacion_estado": "2026-03-10 09:10:00",
            "observacion_por": "Proveedor RutaEX Pulox CR",
            "fecha_ingreso": "2026-03-10 09:00:00",
            "fecha_actualizacion": "2026-03-10 09:00:00"
        },
        {
            "id": 46,
            "numero_orden": "81154738",
            "destinatario": "María López",
            "id_estado": 3,
            "estado_actual": "Entregado",
            "observacion_estado": null,
            "fecha_observacion_estado": null,
            "observacion_por": null,
            "fecha_ingreso": "2026-03-11 10:30:00",
            "fecha_actualizacion": "2026-03-12 14:20:00"
        }
    ],
    "pagination": {
        "total": 3,
        "per_page": 20,
        "current_page": 1,
        "total_pages": 1,
        "has_next": false,
        "has_prev": false
    }
}

Response Fields

Campos de la Respuesta

Field	Type	Description
`id`	integer	Internal order ID
`numero_orden`	string	Order number (client reference)
`destinatario`	string	Recipient name
`id_estado`	integer	Current state ID
`estado_actual`	string	Current state name
`observacion_estado`	string/null	Latest observation/comment for the order status
`fecha_observacion_estado`	datetime/null	Timestamp of the latest observation
`observacion_por`	string/null	User/provider who registered the latest observation
`fecha_ingreso`	datetime	Date the order was registered
`fecha_actualizacion`	datetime	Date of last update

Campo	Tipo	Descripción
`id`	entero	ID interno del pedido
`numero_orden`	string	Número de orden (referencia del cliente)
`destinatario`	string	Nombre del destinatario
`id_estado`	entero	ID del estado actual
`estado_actual`	string	Nombre del estado actual
`observacion_estado`	string/null	Última observación/comentario del estado
`fecha_observacion_estado`	datetime/null	Fecha/hora de la última observación
`observacion_por`	string/null	Usuario/proveedor que registró la observación
`fecha_ingreso`	datetime	Fecha en que se registró el pedido
`fecha_actualizacion`	datetime	Fecha de la última actualización

🔗 Forwarding Provider Status Webhook

🔗 Webhook de Estados (Forwarding)

Endpoint designed to receive real-time order status updates from Forwarding Providers.

Endpoint diseñado para recibir actualizaciones de estado de pedidos en tiempo real desde Proveedores de Forwarding.

                        POST /api/forwarding/webhook_estados.php
                        🔒 Bearer Token RequiredRequiere Bearer Token
                    

Headers

Authorization: Bearer <webhook_secret>
Content-Type: application/json

💡 Authentication: 💡 Autenticación: The webhook_secret must match the token configured in the corresponding Provider settings within the Forwarding module. El webhook_secret debe coincidir con el token configurado en los ajustes del Proveedor correspondiente dentro del módulo de Forwarding.

Expected JSON Payload

JSON Esperado

{
  "customersId": 54,
  "auditUser": "rutaexmex.api",
  "state": "Reprogramado",
  "substate": "Nuevo Intento",
  "dateToReceive": "2026-05-04",
  "notes": "Entrega programada para mañana.",
  "ordersNumbers": [
    { "orderNumber": "123987123456" },
    { "orderNumber": "414141" }
  ]
}

Field Mapping

Mapeo de Campos

Provider Field	Description
`state` & `substate`	Mapped to internal states (e.g. Reprogramado, Cancelado).
`dateToReceive`	Updates order delivery date (Required if state is Reprogramado). Format: YYYY-MM-DD.
`notes` & `auditUser`	Appended to the order's status history log.
`ordersNumbers`	List of order numbers to apply the status update to.

Campo del Proveedor	Descripción
`state` y `substate`	Mapeado a estados internos (Ej. Reprogramado, Cancelado).
`dateToReceive`	Actualiza la fecha de entrega (Obligatorio si el estado es Reprogramado). Formato: YYYY-MM-DD.
`notes` y `auditUser`	Se añade al historial de estados del pedido.
`ordersNumbers`	Lista de números de orden a los que aplicar la actualización.

Response 200 OK

Respuesta 200 OK

{
  "success": true,
  "processed": 1,
  "failed": 1,
  "results": [
    { "orderNumber": "123987123456", "updated": true },
    { "orderNumber": "414141", "updated": false, "error": "Orden no encontrada en el sistema." }
  ]
}

📅 Reschedule an Order

📅 Reprogramar un Pedido

Changes the order status to the indicated state (ID 4 = Rescheduled by default), updates the delivery date, optionally reassigns the client, and records the reason in the status history. The operation is atomic — all changes happen inside a single transaction.

Cambia el estado del pedido al estado indicado (ID 4 = Reprogramado por defecto), actualiza la fecha de entrega, opcionalmente reasigna el cliente y registra el motivo en el historial de estados. La operación es atómica — todos los cambios ocurren dentro de una sola transacción.

                        POST /api/pedidos/reprogramar
                        🔐 AuthenticatedAutenticado
                    

Request Body (application/json)

Cuerpo de la Petición (application/json)

Field	Type	Required	Description	Example
`numero_orden`	string	✅ Yes	Order number to reschedule	`"81154737"`
`fecha_entrega`	string	⚠️ Cond.	New delivery date (ISO 8601 — YYYY-MM-DD). Required only when `id_estado = 4` (Rescheduled). Optional for other states.	`"2026-05-20"`
`id_estado`	integer	⬜ No	Target state ID. Must exist in `estados_pedidos`. Defaults to `4` (Rescheduled).	`4`
`id_cliente`	integer	⬜ No	Client ID to assign to the order. If provided, updates `id_cliente` in the same atomic transaction.	`42`
`motivo`	string	⬜ No	Reason for rescheduling	`"Cliente ausente"`

Campo	Tipo	Req.	Descripción	Ejemplo
`numero_orden`	string	✅ Sí	Número de orden a reprogramar	`"81154737"`
`fecha_entrega`	string	⚠️ Cond.	Nueva fecha de entrega (ISO 8601 — YYYY-MM-DD). Solo requerida cuando `id_estado = 4` (Reprogramado). Opcional para otros estados.	`"2026-05-20"`
`id_estado`	entero	⬜ No	ID del estado destino. Debe existir en `estados_pedidos`. Por defecto `4` (Reprogramado).	`4`
`id_cliente`	entero	⬜ No	ID del cliente a asignar al pedido. Si se provee, actualiza `id_cliente` en la misma transacción atómica.	`42`
`motivo`	string	⬜ No	Razón de la reprogramación	`"Cliente ausente"`

Example Request (curl)

Ejemplo de Petición (curl)

curl -X POST "http://localhost/paqueteriacz/api/pedidos/reprogramar" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "numero_orden": "81154737",
    "fecha_entrega": "2026-05-20",
    "id_estado": 4,
    "id_cliente": 42,
    "motivo": "Cliente ausente en primer intento"
  }'

Example Request (JavaScript)

Ejemplo de Petición (JavaScript)

const res = await fetch('/api/pedidos/reprogramar', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_TOKEN>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    numero_orden: '81154737',
    fecha_entrega: '2026-05-20',
    id_estado: 4,
    id_cliente: 42,
    motivo: 'Cliente ausente en primer intento'
  })
});
const json = await res.json();
console.log(json.data); // { numero_orden, id_estado, id_cliente, fecha_entrega, motivo, reprogramado_en }

Response 200 OK

Respuesta 200 OK

{
  "success": true,
  "message": "Pedido 81154737 reprogramado para el 2026-05-20.",
  "data": {
    "numero_orden":    "81154737",
    "id_estado":       4,
    "id_cliente":      42,
    "fecha_entrega":   "2026-05-20",
    "motivo":          "Cliente ausente en primer intento",
    "reprogramado_en": "2026-05-05 14:30:00"
  }
}

Error Responses

Respuestas de Error

HTTP	CauseCausa
400	Missing required fields, invalid date format, past date, or non-existent `id_estado`.Campos requeridos faltantes, formato de fecha inválido, fecha en el pasado o `id_estado` inexistente.
401	Missing or invalid JWT token.Token JWT ausente o inválido.
403	No permission over the order, or role not allowed to use the target state.Sin permiso sobre el pedido, o el rol no puede usar el estado destino.
404	Order not found.Pedido no encontrado.

💡 Key Behaviors 💡 Comportamientos Clave

Atomic transaction: State change + date update + optional client reassignment + history entry happen in one DB transaction.
State validation: id_estado must be in range 1–13 or 15–17. Returns 400 if outside this range or non-existent.
fecha_entrega: Only required when id_estado = 4 (Reprogramado). Optional for all other states.
Client reassignment: If id_cliente is provided, the order's client is updated in the same transaction.
Role restrictions: Clients (rol=4) cannot use Entregado (3) or Devuelto (7). Blocked if order is already in a terminal state. Messengers (rol=5) and admins have full access.
Default state: If id_estado is omitted, defaults to 4 (Reprogramado).

Transacción atómica: Cambio de estado + actualización de fecha + reasignación opcional de cliente + entrada en historial ocurren en una sola transacción DB.
Validación de estado: id_estado debe estar en el rango 1–13 o 15–17. Retorna 400 si está fuera del rango o no existe.
fecha_entrega: Solo requerida cuando id_estado = 4 (Reprogramado). Opcional para cualquier otro estado.
Reasignación de cliente: Si se provee id_cliente, el cliente del pedido se actualiza en la misma transacción.
Restricciones por rol: Clientes (rol=4) no pueden usar Entregado (3) ni Devuelto (7). Bloqueados si el pedido ya está en estado terminal. Mensajería (rol=5) y admins tienen acceso completo.
Estado por defecto: Si se omite id_estado, usa 4 (Reprogramado).

📅 Rescheduled Orders

📅 Consulta de Órdenes Reprogramadas

Standard endpoint to query all orders currently in Rescheduled status (state ID 4). Returns the new delivery date, the reason for rescheduling, who performed it, and when. The response is automatically scoped to the authenticated client — admins see all orders.

Endpoint estándar para consultar todas las órdenes actualmente en estado Reprogramado (ID 4). Devuelve la nueva fecha de entrega, el motivo del cambio, quién lo realizó y cuándo. La respuesta se limita automáticamente al cliente autenticado — los administradores ven todos los pedidos.

                        GET /api/pedidos/reprogramaciones
                        🔐 AuthenticatedAutenticado
                    

✅ Key difference vs /estado_pedidos?id_estado=4: ✅ Diferencia clave vs /estado_pedidos?id_estado=4:

Returns fecha_entrega (the new scheduled delivery date).
Returns motivo (reason recorded at the time of rescheduling).
Returns reprogramado_por (who changed the state — user or external API).
Returns fecha_reprogramacion (exact timestamp the reschedule was logged).
Date filters apply to when the reschedule occurred, not order entry date.

Devuelve fecha_entrega (la nueva fecha de entrega programada).
Devuelve motivo (razón registrada al momento de reprogramar).
Devuelve reprogramado_por (quién cambió el estado — usuario o API externa).
Devuelve fecha_reprogramacion (timestamp exacto en que se registró la reprogramación).
Los filtros de fecha aplican sobre cuándo ocurrió la reprogramación, no la fecha de ingreso del pedido.

Query Parameters

Parámetros de Consulta

All parameters are optional and combinable. Without filters, all rescheduled orders visible to the authenticated user are returned. Todos los parámetros son opcionales y combinables. Sin filtros, se devuelven todas las órdenes reprogramadas visibles para el usuario autenticado.

Parameter	Type	Default	Description	Example
`numero_orden`	string	—	Filter by exact order number	`81154737`
`fecha_desde`	date	—	Rescheduling date start (Y-m-d)	`2026-05-01`
`fecha_hasta`	date	—	Rescheduling date end (Y-m-d)	`2026-05-31`
`page`	integer	1	Page number	`2`
`limit`	integer	20	Records per page (max 100)	`50`

Parámetro	Tipo	Defecto	Descripción	Ejemplo
`numero_orden`	string	—	Filtrar por número de orden exacto	`81154737`
`fecha_desde`	fecha	—	Fecha de reprogramación desde (Y-m-d)	`2026-05-01`
`fecha_hasta`	fecha	—	Fecha de reprogramación hasta (Y-m-d)	`2026-05-31`
`page`	entero	1	Número de página	`2`
`limit`	entero	20	Registros por página (máx 100)	`50`

Usage Examples

Ejemplos de Uso

1. All rescheduled orders (paginated)

1. Todas las órdenes reprogramadas (paginado)

GET /api/pedidos/reprogramaciones
Authorization: Bearer <YOUR_TOKEN>

2. Specific rescheduled order

2. Reprogramación de un pedido específico

GET /api/pedidos/reprogramaciones?numero_orden=81154737
Authorization: Bearer <YOUR_TOKEN>

3. Rescheduled during May 2026

3. Reprogramadas durante mayo 2026

GET /api/pedidos/reprogramaciones?fecha_desde=2026-05-01&fecha_hasta=2026-05-31
Authorization: Bearer <YOUR_TOKEN>

4. Full cURL example

4. Ejemplo completo con cURL

curl -X GET "http://localhost/paqueteriacz/api/pedidos/reprogramaciones?fecha_desde=2026-05-01&page=1&limit=50" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLC..." \
  -H "Content-Type: application/json"

5. JavaScript (fetch)

const params = new URLSearchParams({
  fecha_desde: '2026-05-01',
  fecha_hasta: '2026-05-31',
  page: 1,
  limit: 50
});

const res = await fetch(`/api/pedidos/reprogramaciones?${params}`, {
  headers: { 'Authorization': 'Bearer ' + token }
});
const json = await res.json();
console.log(json.data);       // array de reprogramaciones
console.log(json.pagination); // metadatos de paginación

6. PHP (cURL)

$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL            => 'http://localhost/paqueteriacz/api/pedidos/reprogramaciones?fecha_desde=2026-05-01',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $token]
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

foreach ($response['data'] as $orden) {
    echo $orden['numero_orden'] . ' → nueva entrega: ' . $orden['fecha_entrega']
       . ' (reprogramado por: ' . $orden['reprogramado_por'] . ')' . PHP_EOL;
}

Response Structure

Estructura de Respuesta

Success 200 OK

Éxito 200 OK

{
    "success": true,
    "message": "Se encontraron 3 órdenes reprogramadas.",
    "data": [
        {
            "numero_orden":          "81154737",
            "destinatario":          "Juan Pérez",
            "direccion":             "Av. Central 123, Col. Centro",
            "estado_actual":         "Reprogramado",
            "fecha_entrega":         "2026-05-20",
            "motivo":                "Cliente ausente en primer intento",
            "reprogramado_por":      "rutaexmex.api",
            "fecha_reprogramacion":  "2026-05-05 14:30:00"
        },
        {
            "numero_orden":          "81154738",
            "destinatario":          "María López",
            "direccion":             "Calle 5 Norte #22",
            "estado_actual":         "Reprogramado",
            "fecha_entrega":         "2026-05-22",
            "motivo":                "Domicilio cerrado",
            "reprogramado_por":      "Carlos Mendoza",
            "fecha_reprogramacion":  "2026-05-05 09:15:00"
        }
    ],
    "pagination": {
        "total":        3,
        "per_page":     20,
        "current_page": 1,
        "total_pages":  1,
        "has_next":     false,
        "has_prev":     false
    }
}

Response Fields

Campos de la Respuesta

Field	Type	Description
`numero_orden`	string	Order number (client reference)
`destinatario`	string	Recipient full name
`direccion`	string	Delivery address
`estado_actual`	string	Always `"Reprogramado"`
`fecha_entrega`	date / null	New scheduled delivery date (`YYYY-MM-DD`). Null if the field was not updated.
`motivo`	string / null	Reason recorded when the order was rescheduled
`reprogramado_por`	string / null	Name of the user or external API that changed the status
`fecha_reprogramacion`	datetime / null	Timestamp of the last rescheduling event (America/Managua)

Campo	Tipo	Descripción
`numero_orden`	string	Número de orden (referencia del cliente)
`destinatario`	string	Nombre completo del destinatario
`direccion`	string	Dirección de entrega
`estado_actual`	string	Siempre `"Reprogramado"`
`fecha_entrega`	fecha / null	Nueva fecha de entrega programada (`YYYY-MM-DD`). Null si el campo no fue actualizado.
`motivo`	string / null	Razón registrada cuando se reprogramó el pedido
`reprogramado_por`	string / null	Nombre del usuario o API externa que cambió el estado
`fecha_reprogramacion`	datetime / null	Timestamp del último evento de reprogramación (America/Managua)

Error Responses

Respuestas de Error

// 401 - Sin token
{
    "success": false,
    "message": "Token de autorización requerido.",
    "data": null
}

// 400 - Formato de fecha incorrecto
{
    "success": false,
    "message": "Formato de fecha_desde inválido. Use YYYY-MM-DD.",
    "data": null
}

// 200 - Sin resultados
{
    "success": true,
    "message": "No se encontraron órdenes reprogramadas con los filtros indicados.",
    "data": []
}

Quick Reference

Referencia Rápida

✨ Key Concepts

✨ Conceptos Clave

Standard Response Envelope

Sobre de Respuesta Estándar

Error Response Example

Ejemplo de Respuesta de Error

Pagination

Paginación

Paginated Response

Respuesta Paginada

Get Order States

Obtener Estados de Pedidos

Example Request

Ejemplo de Petición

Response 200 OK

Respuesta 200 OK

Order Status Reference

Referencia de Estados

Authentication

Autenticación

1. Get Token

1. Obtener Token

Request Body

Cuerpo de la Petición

Example Request

Ejemplo de Petición

Response 200 OK

Respuesta 200 OK

2. Use Token

2. Usar el Token

List & View

Listar y Ver

List Orders

Listar Pedidos

Query Parameters (Filters)

Parámetros de Consulta (Filtros)

Sample Request

Ejemplo de Uso

Get Single Order

Ver Pedido

Create Order

Crear Pedido

🔑 Required Fields (Strict)

🔑 Campos Obligatorios (Estrictos)

Bulk Import (Async)

Importación Masiva (Async)

📋 Optional Details (Automatic)

📋 Detalles Opcionales (Automáticos)

🌍 Optional Fields - Geographic Auto-fill from CP

🌍 Campos Opcionales - Geográficos Auto desde CP

📍 Optional Fields - Special Address For orders without postal code

📍 Campos Opcionales - Dirección Especial Para pedidos sin código postal

👥 Optional Fields - Assignments

👥 Campos Opcionales - Asignaciones

💰 Optional Fields - Pricing

💰 Campos Opcionales - Precios

❌ Error Response (Validation Error)

❌ Respuesta de Error (Falla de Validación)

✅ Automatic Validations

✅ Validaciones Automáticas

🔐 Security Rules

🔐 Reglas de Seguridad

📝 Example: Minimal Order (auto-fill from postal code)

📝 Ejemplo: Pedido Mínimo (auto-relleno desde código postal)

🚚 Example: Order with HLExpress city code

🚚 Ejemplo: Pedido con código de ciudad HLExpress

📝 Example: Special Order (no postal code, custom address fields)

📝 Ejemplo: Pedido Especial (sin código postal, campos de dirección personalizados)

📝 Example: Manual location fields (IDs)

📝 Ejemplo: Campos de ubicación manuales (IDs)

📝 Example: Complete Multi-Product Combo

📝 Ejemplo: Pedido Completo con Múltiples Productos y Combo

📦 Example: Order Without Products (requiere_productos: 0)

📦 Ejemplo: Pedido Sin Productos (requiere_productos: 0)

Bulk Import (Async)

Importación Masiva (Async)

Success Response (202 Accepted)

Respuesta Exitosa (202 Accepted)

📦 Example: Order Without Products (`requiere_productos: 0`)

📦 Ejemplo: Pedido Sin Productos (`requiere_productos: 0`)