# Pedidos

La API Orders administra las compras de clientes, el ciclo de vida del pedido, el enrutamiento a tiendas vendedoras y las actualizaciones de envíos.

## ¿Qué es un pedido?

Un pedido representa una compra en curso o completada en una o varias tiendas. Al finalizar la compra, Tradly crea un pedido principal con pago, cliente, dirección y totales (`list_total`, `offer_total`, `shipping_total`, `tax_total`, `grand_total`). Incluye `Order Details` (líneas de artículos/variantes). En el cumplimiento de varios vendedores, los artículos se vinculan a sus cuentas (`account_id`) y los envíos siguen el progreso de cada vendedor.

## Estados del pedido

| ID | Estado | Descripción |
|---:|---|---|
| `0` | `Draft` | Borrador antes del checkout del carrito. |
| `1` | `Incomplete` | Creación en curso; aún sin pagar. |
| `2` | `Order Placed` | Pedido realizado y pago confirmado; espera al vendedor. |
| `3` | `In Process` | El vendedor aceptó y prepara el pedido. |
| `4` | `Shipped` | Artículos enviados con seguimiento. |
| `5` | `Delivered` | Pedido entregado en destino. |
| `6` | `Cancelled by Customer` | El cliente lo canceló antes del cumplimiento. |
| `7` | `Cancelled by Admin` | Lo canceló un administrador del tenant o vendedor. |
| `8` | `Completed` | Transacción finalizada. |

## Estados del envío

| ID | Estado | Descripción |
|---:|---|---|
| `1` | `Created` | Registro de envío creado para las líneas. |
| `2` | `In Progress` | El vendedor prepara el paquete. |
| `3` | `Shipped` | Paquete entregado al transportista. |
| `4` | `Ready for Pickup` | Paquete listo para recoger en la tienda o por el transportista. |
| `5` | `Out for Delivery` | El transportista está entregando el paquete. |
| `6` | `Undelivered / Returned` | Falló la entrega; el paquete vuelve al remitente. |
| `7` | `Delivered` | El transportista marcó el paquete como entregado. |
| `8` | `Delivered & Confirmed` | Cliente/administrador verificó la recepción. |
| `9` | `Customer Return Initiated` | El comprador pidió una devolución o cambio. |
| `10` | `Customer Return Picked` | El transportista recogió el paquete devuelto. |
| `11` | `Customer Return Confirmed` | El vendedor recibió y verificó los artículos devueltos. |
| `12` | `Cancelled by Account` | La cuenta del vendedor canceló el envío. |
| `13` | `Cancelled by Customer` | El cliente canceló el envío. |
| `14` | `Arrived at Location` | El paquete llegó a un centro de tránsito o casillero. |
| `15` | `Cancelled by Admin` | El administrador del tenant canceló el envío. |

## Estados del pago

| ID | Estado | Descripción |
|---:|---|---|
| `1` | `Unpaid / Pending` | Pago aún no capturado. |
| `2` | `Paid` | Pago capturado correctamente. |
| `3` | `Failed` | Falló el intento de pago. |
| `4` | `Refunded` | Pago reembolsado al cliente. |

## Objeto de pedido

El objeto incluye totales, perfil de cliente, pago y envío, artículos, ganancias de vendedores y seguimiento de envíos.

- Campos principales: `id`, `reference_number`, `tenant_id`, `user_id`, `user` (perfil), `account_ids`, `order_status`, `order_status_description`, `payment_status`, `payment_status_description`, `completed`, `currency` (código ISO de 3 letras), `created_at` y `updated_at` (marcas Unix).
- Los importes son objetos `{ amount, formatted }`. `list_total` es el subtotal original; `offer_total` aplica descuentos; `tax_total` y `shipping_total` son impuestos y envío; `grand_total` es `offer_total + shipping_total + tax_total`.
- `customer_pricing` detalla el precio mostrado al cliente (`grand_total`, `customer_sub_total`, `customer_shipping_charge`, `customer_tax`, `customer_coupon`). `account_pricing` detalla ganancias, comisión, envío e impuestos del vendedor al filtrar por `account_id`.
- `payment_method` incluye `id`, `name`, `type`, `gateway_name`; `shipping_method`, `id`, `name`, `type`, `shipping_charge`; `shipping_address`, los datos de entrega; `shipment`, seguimiento activo (`shipment_status`, `tracking_number`, `courier_name`, `shipped_at`, `delivered_at`).

### Líneas (`order_details`)

Cada línea representa un artículo comprado e incluye `id`, `listing_id`, `quantity`, importes `list_price`, `offer_price`, `special_price`, `tax_charges`, `shipping_charges`, fechas de reserva `schedule_start_at`/`schedule_end_at`, objeto `listing`, variante `variant`, atributos seleccionados `order_detail_attributes` y entradas por unidad `order_detail_item_attributes`.