# Sube la imagen de producto a BigCommerce con la API v3
> Añade la imagen al producto por la API v3 de BigCommerce usando la URL que devuelve SocialCutter, ya recortada a su medida.
- URL: https://socialcutter.theboomer.dev/guias/bigcommerce/
- Idioma: es
- Familia: cms
- Actualizado: 2026-09-24
- Palabras clave: BigCommerce, Catalog API, imagen de producto, API v3, image_url, is_thumbnail, scopes, Python
## Por qué generar los tamaños antes de subir

Una imagen de producto se ve en la rejilla del catálogo, en la página del producto, en la ficha del carrito y en las publicaciones de redes que anuncian ese producto. Cada hueco pide una proporción distinta, y subir una copia por hueco deja el catálogo lleno de ficheros casi idénticos.

El flujo es: **un maestro entra, SocialCutter devuelve cada medida y BigCommerce recibe la que toca en cada sitio**. El recorte del modo `cover` (el que se aplica por defecto) es **centrado**: escala la imagen y reparte el sobrante por igual a los dos lados. No hay detección de sujeto ni ningún paso automático que decida qué recortar.

| Uso en BigCommerce | Destino SocialCutter | Medida |
|---|---|---|
| Imagen principal del producto | `instagram` `post` | 1080x1080 (1:1) |
| Segunda imagen del producto | `instagram` `story` | 1080x1920 (9:16) |
| Banner de categoría | `facebook` `post` | 1200x630 (1.91:1) |
| Cabecera de la tienda | `twitter` `header` | 1500x500 (3:1) |
| Vídeo de producto (miniatura) | `youtube` `thumbnail` | 1280x720 (16:9) |

El catálogo completo sale de `GET /api/v1/platforms`, que es público, y está resumido en la [guía de medidas por red social](/guias/medidas-redes-sociales/).

> Nota: no hay un 4:5 en el catálogo de SocialCutter. Lo vertical es 9:16 (1080x1920) y lo cuadrado es 1:1 (1080x1080). Usa 1:1 como imagen principal; si necesitas 4:5 exacto, recorta fuera.

## Antes de empezar: credencial y scopes

Una cuenta de API de BigCommerce se crea en el panel, en **Settings → API → API accounts**. Al crearla eliges el scope. Como en el catálogo de SocialCutter las peticiones van a la Catalog API v3, necesitas el scope de productos:

| Scope | Para qué lo necesitas aquí |
|---|---|
| `store_v2_products` | Crear y actualizar imágenes de producto |
| `store_v2_products_read_only` | Solo si únicamente lees catálogo |

Los scopes se conceden al crear la credencial y no se amplían por petición: si falta, hay que regenerarla. La lista vigente y sus nombres están en https://developer.bigcommerce.com/docs/start/authentication/api-accounts — compruébala, porque BigCommerce ha ido agrupando endpoints bajo un scope de productos común.

La autenticación usa dos cabeceras: `X-Auth-Token` con el access token y `Accept: application/json`. El store hash va en la ruta:

```bash
export BC_STORE="tu_store_hash"
export BC_TOKEN="tu_access_token"
export SC_KEY="sc_tu_clave"
export BC_API="https://api.bigcommerce.com/stores/$BC_STORE/v3"
```

```bash
curl -s "$BC_API/catalog/products?limit=1" \
  -H "X-Auth-Token: $BC_TOKEN" \
  -H "Accept: application/json" | jq '.data[0] | {id, name}'
```

## 1. Procesa el maestro con SocialCutter

```bash
curl -s -X POST "https://api.socialcutter.theboomer.dev/api/v1/images/process" \
  -H "X-API-Key: *** \
  -H "Content-Type: application/json" \
  -d '{
    "source": { "type": "url", "value": "https://tu-cdn.com/maestro.jpg" },
    "destinations": [
      { "platform": "instagram", "format": "post" },
      { "platform": "instagram", "format": "story" }
    ]
  }' > sc.json

jq '.image_id, (.outputs[] | {url, platform, format, width, height})' sc.json
```

Cada salida es una URL pública. BigCommerce acepta URLs en la creación de imagen, así que no hace falta descargar el fichero.

## 2. Crea la imagen del producto

El endpoint de creación vive bajo el producto y admite **una sola imagen por petición**. Tiene dos modos mutuamente excluyentes:

- `image_url` en JSON: le pasas la URL de SocialCutter y BigCommerce la descarga.
- `image_file` en multipart: subes el binario. Entonces la cabecera debe ser `multipart/form-data`.

```bash
MAIN_URL=$(jq -r '.outputs[] | select(.platform=="instagram" and .format=="post") | .url' sc.json)

curl -s -X POST "$BC_API/catalog/products/123/images" \
  -H "X-Auth-Token: $BC_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{\"image_url\": \"$MAIN_URL\", \"is_thumbnail\": true, \"description\": \"Vista frontal 1:1\"}" \
  > image.json

jq '.data | {id, is_thumbnail, url_standard, url_thumbnail}' image.json
```

Con `is_thumbnail: true` en la propia creación la imagen ya nace como principal. `description` es el texto alternativo que usa la tienda.

Documentación: https://developer.bigcommerce.com/docs/store-operations/catalog

## 3. Variante en Python y variante multipart

Con `requests` el flujo es el mismo. El JSON se envía con `json=` y el multipart con `files=`; mezclar `image_url` con `image_file` es un error.

```python
import os
import requests

SC_KEY = os.environ["SC_KEY"]
BC_API = f'https://api.bigcommerce.com/stores/{os.environ["BC_STORE"]}/v3'
BC_HEADERS = {
    "X-Auth-Token": os.environ["BC_TOKEN"],
    "Accept": "application/json",
}

sc = requests.post(
    "https://api.socialcutter.theboomer.dev/api/v1/images/process",
    headers={"X-API-Key": SC_KEY, "Content-Type": "application/json"},
    json={
        "source": {"type": "url", "value": "https://tu-cdn.com/maestro.jpg"},
        "destinations": [{"platform": "instagram", "format": "post"}],
    },
    timeout=30,
)
sc.raise_for_status()
main_url = sc.json()["outputs"][0]["url"]

product_id = 123
created = requests.post(
    f"{BC_API}/catalog/products/{product_id}/images",
    headers=BC_HEADERS,
    json={"image_url": main_url, "is_thumbnail": True, "description": "Vista frontal 1:1"},
    timeout=30,
)
created.raise_for_status()
image = created.json()["data"]
print(image["id"], image["is_thumbnail"], image["url_standard"])

# Variante multipart, si la imagen solo existe en disco:
with open("story.jpg", "rb") as fh:
    up = requests.post(
        f"{BC_API}/catalog/products/{product_id}/images",
        headers=BC_HEADERS,          # requests pone el Content-Type multipart solo
        files={"image_file": ("story.jpg", fh, "image/jpeg")},
        data={"is_thumbnail": "false"},
        timeout=60,
    )
up.raise_for_status()
```

El campo de un formulario no lleva tipos: `is_thumbnail` viaja como la cadena `"false"` o `"true"`.

## 4. Cambiar la imagen principal después

Si la imagen ya existe y quieres que pase a ser la principal, actualízala por su id. Un producto solo puede tener un thumbnail a la vez, así que la anterior deja de serlo de forma implícita.

```bash
IMAGE_ID=$(jq -r '.data.id' image.json)

curl -s -X PUT "$BC_API/catalog/products/123/images/$IMAGE_ID" \
  -H "X-Auth-Token: $BC_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"is_thumbnail": true}' | jq '.data.is_thumbnail'
```

Para cambiar el orden en que se muestran las imágenes se usa `sort_order` (los números más altos pierden prioridad). Referencia del endpoint de actualización: https://developer.bigcommerce.com/docs/store-operations/catalog

## Coste

- **1 uso por destino** (plataforma y formato) por petición; los repetidos no se cobran dos veces.
- Los procesamientos fallidos se devuelven.
- Planes 0/3/9/29 EUR, todos con API y MCP.

## Errores típicos

| Síntoma | Causa | Solución |
|---|---|---|
| `401` de BigCommerce | Access token ausente o de otra tienda | Comprueba `X-Auth-Token` y que el store hash de la ruta sea el correcto |
| `403` de BigCommerce | Falta el scope de productos en la credencial | Regenera la cuenta de API con `store_v2_products` |
| `422` con `image_url` | La URL no es pública, pasa de 255 caracteres o el formato no está admitido | Pasa la URL de SocialCutter y usa JPEG, PNG, GIF, WEBP, BMP, WBMP o XBM |
| `413`/imagen rechazada | El fichero pesa más de 8 MB | Genera con SocialCutter un maestro menor y reintenta |
| `400` al mandar los dos campos | Se envió `image_url` y `image_file` juntos | Elige uno: JSON con URL o multipart con fichero |
| `413` de SocialCutter | El maestro pasa de 5 MB | Reduce el maestro antes de procesarlo |

## Sin código y siguientes pasos

Un automatizador encadena los mismos pasos con nodos: disparador, nodo HTTP a `/api/v1/images/process` y nodo HTTP a la Catalog API con la URL de salida. El patrón general está en la [guía de automatización de imágenes para redes sociales](/guias/automatizar-imagenes-redes-sociales/).

- Shopify: [Integra SocialCutter con la Admin API de Shopify](/guias/shopify/)
- WordPress y WooCommerce: [Integra SocialCutter con WordPress y WooCommerce](/guias/wordpress/)
- Python: [Procesa imágenes con la API desde Python](/guias/python/)
- Terminal: [Procesa imágenes con la API desde la terminal (curl)](/guias/curl/)
- Documentación: https://docs.socialcutter.theboomer.dev