Introducción
🎯 ¿Qué hace este módulo?
El módulo de Orders te permite crear, gestionar y rastrear pedidos de clientes - desde la finalización de la compra en el carrito hasta el procesamiento de pagos y la entrega de pedidos - manejando el ciclo de vida completo de los pedidos de comercio electrónico.
Piénsalo como tu sistema de gestión de pedidos - los clientes añaden artículos al carrito, realizan pedidos, hacen pagos, y tú rastreas todo desde la creación del pedido hasta la entrega, todo dentro de OneEntry.
📖 Explicación Simple
Cada aplicación de comercio electrónico necesita gestión de pedidos:
- 🛒 Carrito de Compras - Los usuarios añaden productos, proceden a la compra
- 📋 Creación de Pedidos - Convierte el carrito en un pedido con los detalles del cliente
- 💳 Procesamiento de Pagos - Acepta pagos (tarjeta de crédito, PayPal, etc.)
- 📦 Rastreo de Pedidos - Rastrear el estado (pendiente, en proceso, enviado, entregado)
- 📊 Gestión de Pedidos - Ver todos los pedidos, filtrar por estado, buscar
- 🧾 Detalles del Pedido - Ver artículos, totales, información del cliente
Problemas:
- 🔒 Sin integración de pagos - Seguimiento manual de pagos
- 📊 Pobre rastreo - Difícil encontrar pedidos, filtrar por estado
- 🔄 Sin automatización - Actualizaciones de estado manuales, sin notificaciones
- 💸 Sin cálculo de impuestos/envío - Calcular manualmente
La solución de Orders:
Beneficios:
- 🔒 Pagos integrados - Stripe, PayPal, otros gateways
- 📊 Rastreo avanzado - Filtrar, buscar, exportar pedidos
- 🔄 Flujos de trabajo automatizados - Actualizaciones de estado, notificaciones
- 💸 Cálculos automáticos - Impuestos, envío, descuentos
✨ Conceptos Clave
¿Qué es un Pedido?
Un Pedido es una transacción de compra del cliente que contiene:
- Artículos del Pedido - Productos/servicios que se están comprando (cantidad, precio)
- Información del Cliente - Nombre, correo electrónico, teléfono
- Dirección de Envío - Ubicación de entrega
- Dirección de Facturación - Información de facturación del pago
- Detalles del Pago - Método de pago, ID de transacción
- Totales del Pedido - Subtotal, impuestos, envío, total
- Estado del Pedido - Estado actual (pendiente, en proceso, completado)
- Tiempos - Fechas de creación, actualización, finalización
Estructura del Pedido
Cada pedido tiene esta estructura:
{
id: 179,
storageId: 1,
createdDate: '2025-07-03T00:43:02.908Z',
statusIdentifier: 'inProgress',
formIdentifier: 'orderForm',
formData: [
{
marker: 'order_name',
type: 'string',
value: 'Ivan'
}
],
attributeSetIdentifier: 'order_form',
totalSum: '300.00',
currency: 'USD',
paymentAccountIdentifier: 'cash',
paymentAccountLocalizeInfos: { title: 'Cash' },
products: [
{
id: 2957,
title: 'Cosmo',
sku: null,
previewImage: null,
price: 150,
quantity: 2,
},
],
isCompleted: true,
}
Ciclo de Vida del Pedido
1. Customer adds items to cart
↓
2. Proceeds to checkout
↓
3. Enters shipping/billing info
↓
4. Selects payment method
↓
5. Order created (status: pending)
↓
6. Payment processed (status: processing)
↓
7. Order confirmed (status: confirmed)
↓
8. Items prepared (status: processing)
↓
9. Order shipped (status: shipped)
↓
10. Order delivered (status: completed)
Ejemplos de Estados del Pedido
| Estado | Significado | Cuándo Usar |
|---|---|---|
| pendiente | Pedido creado, esperando pago | Acabado de realizar, pago no procesado |
| en proceso | Pago recibido, preparando artículos | Pago confirmado, empaquetando artículos |
| confirmado | Pedido confirmado, listo para enviar | Pago procesado, pedido verificado |
| enviado | Pedido despachado al cliente | Paquete enviado por el transportista |
| entregado | Pedido recibido por el cliente | Entrega confirmada |
| completado | Pedido finalizado, no se necesita acción | Transacción completa |
| cancelado | Pedido cancelado | Cancelado por el cliente/admin |
| reembolsado | Pago devuelto al cliente | Reembolso procesado |
| fallido | Pago o procesamiento fallido | Pago rechazado |
Operaciones Comunes de Pedidos
| Operación | Descripción | Caso de Uso Ejemplo |
|---|---|---|
| Crear Pedido | Convertir carrito en pedido | Botón de compra clicado |
| Obtener Pedidos | Listar todos los pedidos (paginados) | Panel de administración |
| Obtener Pedido por ID | Obtener pedido específico | Ver detalles del pedido |
| Actualizar Estado | Cambiar estado del pedido | Marcar como enviado |
| Calcular Totales | Calcular impuestos, envío, total | Resumen de compra |
| Cancelar Pedido | Cancelar pedido pendiente | Solicitud de cancelación del cliente |
| Reembolsar Pedido | Devolver pago al cliente | Devolución de producto |
¿Por qué usar el módulo de Orders?
| Beneficio | Descripción |
|---|---|
| Gestión de Pedidos Automatizada | Sin seguimiento manual, todo automatizado |
| Integración de Pagos | Stripe, PayPal, otros gateways integrados |
| Rastreo de Estado | Actualizaciones de estado de pedidos en tiempo real |
| Notificaciones al Cliente | Envío automático de confirmaciones de pedidos, actualizaciones de envío |
| Gestión de Inventario | Deducción automática de stock al realizar un pedido |
| Analíticas e Informes | Informes de ventas, seguimiento de ingresos |
| Seguridad | Procesamiento de pagos conforme a PCI |
📋 Lo Que Necesitas Saber
Los Pedidos se Crean a Partir de Datos del Carrito
Necesitas proporcionar:
- Información del cliente - Nombre, correo electrónico, teléfono
- Artículos del pedido - Productos, cantidades, precios
- Dirección de envío - Ubicación de entrega
- Método de pago - Cómo pagará el cliente
Gestión del Estado del Pedido
Rastrea el progreso del pedido a través de estados:
Flujos de estado comunes:
- Productos digitales: pendiente → en proceso → completado
- Productos físicos: pendiente → en proceso → enviado → entregado → completado
- Cancelado: cualquier estado → cancelado
- Reembolsado: completado → reembolsado
Procesamiento de Pagos
Los pedidos se integran con gateways de pago
💡 Notas Importantes
Los Pedidos se Crean en OneEntry
El módulo de Orders maneja el ciclo de vida completo del pedido:
- ✅ Crear pedidos a partir de datos del carrito
- ✅ Procesar pagos
- ✅ Actualizar estado del pedido
- ✅ Rastrear envíos
- ❌ NO maneja la interfaz del carrito de compras (tú construyes eso)
Tu responsabilidad:
- Construir la interfaz del carrito de compras
- Recoger información del cliente
- Mostrar confirmación del pedido
Procesamiento de Pagos
Los pedidos se integran con gateways de pago:
- Stripe (recomendado)
- PayPal
- Gateways personalizados
Importante:
- Nunca almacenes detalles de tarjetas de crédito directamente
- Usa tokenización (Stripe.js, PayPal SDK)
- OneEntry maneja el procesamiento seguro de pagos
Gestión de Inventario
Los pedidos automáticamente:
- ✅ Deducen inventario al crear el pedido
- ✅ Restauran inventario al cancelar
- ✅ Rastrean niveles de stock
Mejor práctica: Verifica el stock antes de crear el pedido
Seguridad
Los pedidos contienen datos sensibles:
- Información personal del cliente
- Detalles de pago
- Direcciones de envío
Siempre:
- Usa HTTPS para las páginas de pago
- Valida los datos antes de crear pedidos
- Implementa autenticación adecuada
- Sigue el cumplimiento de PCI DSS para pagos
📊 Tabla de Referencia Rápida
| Método | Descripción |
|---|---|
| createOrder() | Crear un nuevo pedido |
| getAllOrdersByMarker() | Obtener todos los pedidos (paginados) |
| getOrdersStorageByMarker() | Obtener un objeto de almacenamiento de pedidos por marcador. |
| getAllOrdersStorage() | Obtener todos los objetos de almacenamiento de pedidos. |
| getOrderByMarkerAndId() | Obtener un pedido por marcador e ID del objeto de almacenamiento de pedidos creado por el usuario. |
| updateOrderByMarkerAndId() | Actualizar un pedido por marcador e ID del objeto de almacenamiento de pedidos creado por el usuario. |
❓ Preguntas Comunes (FAQ)
¿Cómo creo un pedido con múltiples productos?
Pasa un array de objetos de producto en los datos del pedido.
Cada producto debe incluir id, cantidad y precio.
La suma total se calcula automáticamente en función de las cantidades y precios de los productos.
¿Puedo actualizar un pedido después de haber sido creado?
Sí, usa updateOrderByMarkerAndId() para modificar detalles del pedido como estado, dirección de envío o datos del pedido.
Sin embargo, una vez que se procesa el pago, ten cuidado al modificar los artículos o totales del pedido.
¿Cómo rastreo los cambios en el estado del pedido?
Usa el campo statusIdentifier para rastrear el estado actual del pedido.
También puedes configurar webhooks o usar el módulo de Events para recibir notificaciones cuando cambie el estado del pedido.
¿Cuál es la diferencia entre el almacenamiento de pedidos y los pedidos individuales?
El almacenamiento de pedidos es un contenedor que agrupa pedidos relacionados (como pedidos de un formulario específico o canal de ventas). Los pedidos individuales son las transacciones de compra reales dentro de ese almacenamiento. Usa marcadores para identificar y organizar diferentes almacenamientos de pedidos.
¿Cómo manejo las cancelaciones y reembolsos de pedidos?
Actualiza el estado del pedido a 'cancelado' usando updateOrderByMarkerAndId().
Para reembolsos, usa el módulo de Payments para procesar la transacción de reembolso, luego actualiza el estado del pedido a 'reembolsado'.
¿Puedo recuperar el historial de pedidos de un cliente?
Sí, usa getAllOrdersByMarker() con filtros apropiados para obtener todos los pedidos de un cliente específico.
Puedes filtrar por ID de usuario, rango de fechas u otros criterios.
🎓 Mejores Prácticas
- Valida el carrito antes de crear el pedido - Verifica la disponibilidad de stock
- Calcula los totales en el servidor - Nunca confíes en cálculos del lado del cliente
- Envía confirmaciones de pedidos - Envía correos electrónicos a los clientes después de realizar un pedido
- Rastrea el estado del pedido - Actualiza el estado a medida que avanza el pedido
- Maneja fallos de pago - Lógica de reintento, mensajes de error claros
- Implementa búsqueda de pedidos - Permite a los clientes encontrar sus pedidos fácilmente
- Almacena el historial de pedidos - Mantén registros para el servicio al cliente
- Usa paginación - No cargues todos los pedidos a la vez
Más información sobre la interfaz de usuario del módulo https://doc.oneentry.cloud/docs/category/orders
Definición del módulo de Orders
const { Orders } = defineOneEntry( "your-project-url", { "token": "your-app-token" });
🔗 Documentación Relacionada
- Módulo de Products - Gestionar productos disponibles para la compra
- Módulo de Users - Gestionar clientes que realizan pedidos
- Módulo de IntegrationCollections - Integraciones de gateways de pago
- Módulo de Events - Notificaciones de estado de pedidos