Órdenes

Este módulo maneja la gestión de órdenes de compra en el sistema AgroMarket.

Endpoints

GET /api/v1/orders

Obtiene todas las órdenes donde el usuario es comprador o vendedor.

URL: /api/v1/orders

Método: GET

Headers:

Authorization: Bearer <token>

Respuesta exitosa (200):

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "buyer": "507f1f77bcf86cd799439012",
    "seller": "507f1f77bcf86cd799439013",
    "items": [
      {
        "productId": "507f1f77bcf86cd799439014",
        "quantity": 2,
        "price": 2.50,
        "product": {
          "_id": "507f1f77bcf86cd799439014",
          "name": "Manzanas Rojas",
          "image": "https://ejemplo.com/manzanas.jpg"
        }
      }
    ],
    "total": 5.00,
    "status": "pending",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
]

---

GET /api/v1/orders/{id}

Obtiene una orden específica por su ID.

URL: /api/v1/orders/{id}

Método: GET

Headers:

Authorization: Bearer <token>

Parámetros de ruta: - id: ID de la orden

Ejemplo:

GET /api/v1/orders/507f1f77bcf86cd799439011

Respuesta exitosa (200):

{
  "_id": "507f1f77bcf86cd799439011",
  "buyer": "507f1f77bcf86cd799439012",
  "seller": "507f1f77bcf86cd799439013",
  "items": [
    {
      "productId": "507f1f77bcf86cd799439014",
      "quantity": 2,
      "price": 2.50,
      "product": {
        "_id": "507f1f77bcf86cd799439014",
        "name": "Manzanas Rojas",
        "image": "https://ejemplo.com/manzanas.jpg"
      }
    }
  ],
  "total": 5.00,
  "status": "pending",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Respuesta de error (404):

{
  "message": "Orden no encontrada"
}

---

POST /api/v1/orders

Crea una nueva orden basada en los productos del carrito del usuario.

URL: /api/v1/orders

Método: POST

Headers:

Authorization: Bearer <token>

Respuesta exitosa (201):

{
  "orders": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "buyer": "507f1f77bcf86cd799439012",
      "seller": "507f1f77bcf86cd799439013",
      "items": [
        {
          "productId": "507f1f77bcf86cd799439014",
          "quantity": 2,
          "price": 2.50,
          "product": {
            "_id": "507f1f77bcf86cd799439014",
            "name": "Manzanas Rojas",
            "image": "https://ejemplo.com/manzanas.jpg"
          }
        }
      ],
      "total": 5.00,
      "status": "pending",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "message": "Órdenes creadas exitosamente"
}

Respuesta de error (400):

{
  "message": "Cart is empty"
}

Respuesta de error (400):

{
  "message": "Buyer location not found"
}

Respuesta de error (400):

{
  "message": "Insufficient stock for product"
}

---

PUT /api/v1/orders/{id}

Actualiza el estado de una orden específica.

URL: /api/v1/orders/{id}

Método: PUT

Headers:

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

Parámetros de ruta: - id: ID de la orden

Body:

{
  "status": "in-progress"
}

Estados válidos: - pending: Pendiente - in-progress: En progreso - completed: Completada - cancelled: Cancelada

Respuesta exitosa (200):

{
  "_id": "507f1f77bcf86cd799439011",
  "buyer": "507f1f77bcf86cd799439012",
  "seller": "507f1f77bcf86cd799439013",
  "items": [
    {
      "productId": "507f1f77bcf86cd799439014",
      "quantity": 2,
      "price": 2.50,
      "product": {
        "_id": "507f1f77bcf86cd799439014",
        "name": "Manzanas Rojas",
        "image": "https://ejemplo.com/manzanas.jpg"
      }
    }
  ],
  "total": 5.00,
  "status": "in-progress",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T11:00:00.000Z"
}

Respuesta de error (400):

{
  "message": "Estado inválido"
}

---

DELETE /api/v1/orders/{id}

Elimina una orden específica por su ID.

URL: /api/v1/orders/{id}

Método: DELETE

Headers:

Authorization: Bearer <token>

Parámetros de ruta: - id: ID de la orden

Respuesta exitosa (200):

{
  "message": "Order deleted successfully"
}

Respuesta de error (404):

{
  "message": "Orden no encontrada"
}

---

PATCH /api/v1/orders/status/{id}

Actualiza el estado de una orden siguiendo las reglas de transición válidas.

URL: /api/v1/orders/status/{id}

Método: PATCH

Headers:

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

Parámetros de ruta: - id: ID de la orden

Body:

{
  "status": "completed"
}

Respuesta exitosa (200):

{
  "order": {
    "_id": "507f1f77bcf86cd799439011",
    "buyer": "507f1f77bcf86cd799439012",
    "seller": "507f1f77bcf86cd799439013",
    "items": [
      {
        "productId": "507f1f77bcf86cd799439014",
        "quantity": 2,
        "price": 2.50,
        "product": {
          "_id": "507f1f77bcf86cd799439014",
          "name": "Manzanas Rojas",
          "image": "https://ejemplo.com/manzanas.jpg"
        }
      }
    ],
    "total": 5.00,
    "status": "completed",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T12:00:00.000Z"
  },
  "message": "Estado actualizado exitosamente"
}

Respuesta de error (400):

{
  "message": "Invalid status change from pending to completed"
}

Estados de las Órdenes

Estado	Descripción
pending	Orden creada, pendiente de procesamiento
in-progress	Orden en proceso de preparación
completed	Orden completada y entregada
cancelled	Orden cancelada

Reglas de Transición de Estados

• pending → in-progress ✅
• pending → cancelled ✅
• in-progress → completed ✅
• in-progress → cancelled ✅
• completed → No se puede cambiar ❌
• cancelled → No se puede cambiar ❌

Códigos de Error Comunes

Código	Descripción
400	Error en los datos de entrada o transición de estado inválida
401	Token de autenticación inválido o faltante
404	Orden no encontrada
500	Error interno del servidor

Notas Importantes

• Se crean órdenes separadas por vendedor
• El carrito se vacía automáticamente al crear órdenes
• Solo se pueden actualizar órdenes que pertenezcan al usuario
• Los estados tienen reglas de transición específicas
• Las órdenes incluyen información completa de los productos
• El total se calcula automáticamente