Saltar al contenido principal

Multimedia y Archivos

La API de Multimedia y Archivos gestiona el almacenamiento, procesamiento e indexación de archivos multimedia (ej. imágenes de productos, banners, documentos adjuntos) utilizando Google Cloud Storage u otros proveedores de almacenamiento.

Flujo de Subida de Archivos​

La subida de archivos sigue un flujo de dos pasos para evitar que el tráfico pesado pase por los servidores de la aplicación Go:

sequenceDiagram
    Client->>Go API: POST /api/v1/media/upload
    Go API-->>Client: 201 Created (File ID + Presigned GCS URL)
    Client->>GCS Storage: PUT (Subida binaria del archivo)
    GCS Storage-->>Client: 200 OK
    Client->>Go API: POST /api/v1/media/:id/confirm
    Go API-->>Client: 200 OK (File Status: uploaded)

Endpoints​

1. Iniciar subida​

Genera un registro temporal en la base de datos y retorna una URL de subida firmada directamente hacia el almacenamiento en la nube (GCS).

POST /api/v1/media/upload

Payload de entrada:

{
  "original_name": "polo_rojo.jpg",
  "content_type": "image/jpeg",
  "size_bytes": 1048576
}

Respuesta 201 Created:

{
  "data": {
    "file_id": "a9c3d2b2-f046-40d3-852f-423089c73ba3",
    "upload_url": "https://storage.googleapis.com/omnibuy-media-bucket/tenants/mi-tienda/a9c3d2b2-f046-40d3-852f-423089c73ba3?GoogleAccessId=...",
    "expires_at": "2026-06-02T21:00:00Z"
  }
}

Nota: La URL firmada expira en un periodo corto (normalmente 15 minutos).

2. Confirmar subida​

Se llama después de realizar con éxito la subida directa a la URL firmada. Marca el archivo en estado uploaded (subido) y activa el procesamiento asíncrono (ej. generación de variantes optimizadas para web).

POST /api/v1/media/:id/confirm

Respuesta 200 OK:

{
  "data": {
    "id": "a9c3d2b2-f046-40d3-852f-423089c73ba3",
    "tenant_id": "8a1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "original_name": "polo_rojo.jpg",
    "storage_key": "tenants/mi-tienda/a9c3d2b2-f046-40d3-852f-423089c73ba3",
    "content_type": "image/jpeg",
    "size_bytes": 1048576,
    "status": "uploaded",
    "alt_text": "",
    "variants": [],
    "public_url": "https://storage.googleapis.com/omnibuy-media-bucket/tenants/mi-tienda/a9c3d2b2-f046-40d3-852f-423089c73ba3",
    "created_at": "2026-06-02T20:45:00Z",
    "updated_at": "2026-06-02T20:45:10Z"
  }
}

3. Listar archivos​

Retorna la lista de archivos registrados para el tenant.

GET /api/v1/media

Soporta paginación por cursores.

4. Obtener archivo​

GET /api/v1/media/:id

5. Actualizar texto alternativo (Alt Text)​

Modifica el campo de accesibilidad para la imagen.

PATCH /api/v1/media/:id/alt-text

Payload de entrada:

{
  "alt_text": "Polo rojo clásico de algodón Pima"
}

Respuesta 200 OK

6. Agregar variante procesada​

Añade información de una versión procesada de la imagen (ej. miniatura, versión optimizada webp). Este endpoint suele ser consumido por workers de procesamiento en segundo plano.

POST /api/v1/media/:id/variants

Payload de entrada:

{
  "name": "thumbnail",
  "storage_key": "tenants/mi-tienda/variants/a9c3d2b2-f046-40d3-852f-423089c73ba3_thumb.jpg",
  "width": 150,
  "height": 150,
  "size_bytes": 12450,
  "public_url": "https://storage.googleapis.com/omnibuy-media-bucket/tenants/mi-tienda/variants/a9c3d2b2-f046-40d3-852f-423089c73ba3_thumb.jpg"
}

Respuesta 200 OK

7. Registrar fallo de procesamiento o subida​

Marca el archivo en estado failed en caso de errores en la red o en las colas de conversión.

POST /api/v1/media/:id/fail

Payload de entrada:

{
  "reason": "La conversión de formato no pudo completarse (imagen corrupta)."
}

Respuesta 200 OK

8. Eliminar archivo​

Elimina el archivo de la base de datos y lo remueve del almacenamiento persistente en la nube (GCS).

DELETE /api/v1/media/:id

Respuesta 204 No Content