Saltar a contenido

Ó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

  • pendingin-progress
  • pendingcancelled
  • in-progresscompleted
  • in-progresscancelled
  • 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