Órdenes

El endpoint de órdenes permite crear una orden de compra para la tienda autenticada. El servicio resuelve automáticamente el canal de venta, la ubicación de origen, el cliente y los precios de cada variante.

Crear orden

POST /api/v1/orders

Cuerpo de la petición

{
  "customer": {
    "email": "cliente@ejemplo.com",
    "name": "Juan",
    "lastName": "Pérez",
    "identifier": "12345678-9",
    "phone": "+56912345678"
  },
  "items": [
    {
      "variantId": "uuid-de-variante",
      "quantity": 2,
      "configuration": [ /* opciones de configuración del producto */ ]
    }
  ],
  "notes": "Por favor envolver para regalo"
}

Campos del objeto customer

Campos de cada item

Opciones de configuración (configuration)

Cuando un producto tiene configOptions, el cliente debe enviar respuestas para las opciones required. El tipo de cada entrada del array depende del campo type de la opción.

Tipo SELECT

El cliente elige un valor del listado de la opción.

{
  "optionId": "uuid-de-la-opcion",
  "type": "SELECT",
  "valueId": "uuid-del-valor-elegido"
}

Tipo MULTI_SELECT

El cliente elige uno o más valores. Respetar los límites minSelections y maxSelections del producto.

{
  "optionId": "uuid-de-la-opcion",
  "type": "MULTI_SELECT",
  "valueIds": ["uuid-valor-1", "uuid-valor-2"]
}

Tipo TEXT

El cliente ingresa un texto libre (máximo 1000 caracteres).

{
  "optionId": "uuid-de-la-opcion",
  "type": "TEXT",
  "value": "Juan Pérez"
}

Tipo FILE

El cliente adjunta un archivo subido previamente. Primero debe obtener un uploadId mediante el endpoint POST /uploads/presign, subir el archivo al URL firmado y luego referenciar el uploadId aquí.

{
  "optionId": "uuid-de-la-opcion",
  "type": "FILE",
  "uploadId": "uuid-del-upload"
}

Ajuste de precio por configuración

El precio final de cada variante es:

unitPrice = precio_base_del_canal + suma_de_priceAdjustment_de_valores_seleccionados

Los ajustes de precio provienen del campo priceAdjustment de cada ProductConfigOptionValue. Para opciones de tipo TEXT y FILE el ajuste siempre es 0.

Procesamiento interno

1. Valida que cada variante exista y pertenezca a la tienda.
2. Verifica que todas las opciones requeridas estén presentes.
3. Calcula el ajuste de precio total por item.
4. Resuelve el canal de venta por defecto (isBilling = true, o el primero creado).
5. Resuelve o crea el cliente según email o identifier.
6. Obtiene el precio base de cada variante en el canal de venta.
7. Crea la orden en el microservicio grpc-orders.
8. Persiste la configuración validada en cada OrderItem.
9. Marca los uploads de archivos como adjuntos a la orden.

Respuesta 201 Created

{
  "id": "uuid",
  "orderNumber": 1042,
  "status": "PENDING",
  "paymentStatus": "UNPAID",
  "subtotal": "19980.00",
  "shipping": "0.00",
  "discount": "0.00",
  "tax": "0.00",
  "total": "19980.00",
  "notes": "Por favor envolver para regalo",
  "paymentMethod": null,
  "trackingNumber": null,
  "transactionId": null,
  "createdAt": "2025-06-01T12:00:00.000Z",
  "items": [
    {
      "id": "uuid",
      "variantId": "uuid",
      "quantity": 2,
      "unitPrice": "9990.00",
      "subtotal": "19980.00",
      "configuration": [
        {
          "optionId": "uuid",
          "optionName": "Color de hilo",
          "type": "SELECT",
          "valueId": "uuid",
          "value": "Dorado",
          "priceAdjustment": 1500
        }
      ]
    }
  ]
}

Estados de la orden (status)

PENDING · CONFIRMED · PROCESSING · DISPATCHED · DELIVERED · CANCELLED · RETURNED

Estados de pago (paymentStatus)

UNPAID · PARTIALLY_PAID · PAID · AUTHORIZED · REFUNDED · VOIDED · FAILED

Errores frecuentes