Sube la imagen de producto a BigCommerce con la API v3

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.

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:

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"

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

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.

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.

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.

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.

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