Archivos

Cuando un producto tiene una opción de configuración de tipo FILE, el cliente debe subir el archivo antes de crear la orden. El proceso consiste en tres pasos:

1. Obtener una URL firmada con POST /uploads/presign.
2. Subir el archivo directamente a Firebase Storage usando esa URL.
3. Usar el uploadId al crear la orden en POST /orders.

Obtener URL de subida

POST /api/v1/uploads/presign

Genera un uploadId único y una URL de subida firmada (válida por 15 minutos). Simultáneamente registra el upload en Firestore con estado pending.

Cuerpo de la petición

{
  "contentType": "image/jpeg"
}

Tipos de contenido permitidos

Respuesta 201 Created

{
  "uploadId": "550e8400-e29b-41d4-a716-446655440000",
  "uploadUrl": "https://storage.googleapis.com/bucket/stores/.../file?X-Goog-Signature=...",
  "expiresAt": "2025-06-01T13:00:00.000Z"
}

Subir el archivo

Con la uploadUrl obtenida, realiza una petición PUT directamente desde el cliente (navegador, app móvil) a Firebase Storage. No pases por la API.

PUT <uploadUrl>
Content-Type: image/jpeg

<bytes del archivo>

La URL firmada expira a los 15 minutos. Si caduca antes de completar la subida, debes solicitar una nueva URL con un nuevo uploadId.

Ciclo de vida del upload

pending  →  ready  →  attached

La Cloud Function trackOrderUpload escucha el evento onObjectFinalized en la ruta stores/{storeId}/order-uploads/{uploadId}/file y actualiza el documento de Firestore con status: "ready".

Los documentos en Firestore expiran 1 hora después de ser creados. Si no se usa el uploadId en ese plazo, el upload queda huérfano.

Usar el uploadId en una orden

Una vez que el archivo esté en estado ready, inclúyelo en la configuración del item al crear la orden:

{
  "customer": { /* ... */ },
  "items": [
    {
      "variantId": "uuid-variante",
      "quantity": 1,
      "configuration": [
        {
          "optionId": "uuid-opcion-archivo",
          "type": "FILE",
          "uploadId": "550e8400-e29b-41d4-a716-446655440000"
        }
      ]
    }
  ]
}

El servicio de órdenes validará que:

• El uploadId exista en Firestore.
• El estado sea ready (no pending ni expirado).
• El storeId del upload coincida con el de la tienda autenticada.

Si alguna validación falla, la respuesta es 422 Unprocessable Entity.

Ruta de almacenamiento

Los archivos se guardan en Firebase Storage bajo la siguiente ruta:

stores/{storeId}/order-uploads/{uploadId}/file

Una vez adjunto a una orden, el archivo queda asociado al OrderItem a través del campo configuration (JSON) y es accesible internamente para el equipo de la tienda.