Sube imágenes de catálogo a WooCommerce con SocialCutter

Por qué pre-generar los tamaños del catálogo

Una ficha aparece en la parrilla, en el buscador interno, en el carrito y en los anuncios, y cada hueco tiene su proporción.

El flujo es: entra un solo maestro, SocialCutter devuelve cada medida y WooCommerce recibe la que toca en cada hueco. El recorte de cover, el modo por defecto, es centrado: escala y reparte el recorte por igual a los dos lados. Encuadra el maestro dejando aire.

Hueco en la tienda	Destino SocialCutter	Medida
Imagen principal del producto	instagram post	1080x1080 (1:1)
Variante o segunda imagen vertical	instagram story	1080x1920 (9:16)
Banner de categoría	facebook post	1200x630 (1.91:1)
Cabecera de la tienda	twitter header	1500x500 (3:1)
Anuncio o ficha de marketplace	facebook story	1080x1920 (9:16)

Las medidas salen de GET /api/v1/platforms, que es público.

WooCommerce ya genera sus propios tamaños

Al subir cada adjunto, WordPress y WooCommerce generan sus miniaturas: parrilla, ficha, carrito. Las medidas se definen en Apariencia → Personalizar → WooCommerce → Product Images y el recorte en Ajustes → Medios: reglas del CMS, no tuyas.

Conviene pre-generar con SocialCutter cuando:

• Necesitas una medida exacta que el CMS no produce (1080x1920, 1500x500): el tema recortaría a su proporción.
• No quieres depender de la regeneración: un cambio de tema deja las miniaturas desfasadas.
• Trabajas en lote, con POST /api/v1/images/batch, para preparar cientos de productos antes de tocar la tienda.
• El mismo maestro alimenta canales externos (marketplace, anuncios) con otros formatos.

Para una miniatura cuadrada en la parrilla, los tamaños del CMS bastan.

Antes de empezar

• WordPress 5.6 o superior, con HTTPS, para las Application Passwords.
• Clave sc_ de SocialCutter, creada en Perfil → API keys del dashboard.
• Claves ck_ y cs_ de WooCommerce → Ajustes → Avanzado → REST API.

export WP_URL="https://tu-tienda.com"
export WP_USER="usuario"
export WP_APP_PASSWORD="abcd efgh ijkl mnop qrst uvwx"
export WC_CK="ck_..."
export WC_CS="cs_..."
export SC_KEY="sc_tu_clave"

1. El maestro: subirlo a la biblioteca o pasar su URL

Vía biblioteca de medios. El endpoint acepta el fichero en el cuerpo, con Content-Disposition para el nombre:

curl -s -X POST "$WP_URL/wp-json/wp/v2/media" \
  --user "$WP_USER:$WP_APP_PASSWORD" \
  -H "Content-Disposition: attachment; filename=maestro.jpg" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@maestro.jpg" | jq -r '.id, .source_url'

Se crean en Usuarios → Perfil → Application Passwords y viajan por HTTP Basic: https://developer.wordpress.org/rest-api/reference/media/

Vía URL pública. Si el maestro ya está en un CDN, pasa su URL como source.value y sube solo las salidas que vayas a usar.

2. Genera los tamaños con SocialCutter

curl -s -X POST "https://api.socialcutter.theboomer.dev/api/v1/images/process" \
  -H "X-API-Key: $SC_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: producto-99-catalogo" \
  -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. Idempotency-Key hace seguros los reintentos. Con un fichero local usa POST /api/v1/images/process/upload (multipart, máximo 5 MB).

3. Asigna las imágenes al producto

El campo images es una lista: la primera imagen es la principal y el resto forma la galería. Cada elemento acepta id (adjunto de la biblioteca) o src (URL que WooCommerce descarga), más alt y position.

SQUARE=$(jq -r '.outputs[0].url' sc.json)
PORTRAIT=$(jq -r '.outputs[1].url' sc.json)

curl -s -X PUT "$WP_URL/wp-json/wc/v3/products/99" \
  --user "$WC_CK:$WC_CS" \
  -H "Content-Type: application/json" \
  -d "{
    \"images\": [
      { \"src\": \"$SQUARE\", \"alt\": \"Camiseta vista frontal\", \"position\": 0 },
      { \"src\": \"$PORTRAIT\", \"alt\": \"Camiseta detalle de tejido\", \"position\": 1 }
    ]
  }" | jq '{id, images: [.images[] | {id, src, position}]}'

Cambia src por id si el fichero ya está en la biblioteca y no se duplicará. Documentación: https://developer.woocommerce.com/docs/apis/rest-api/v3/products/ — los campos cambian entre releases: comprueba los de tu versión.

4. Snippet PHP con wp_remote_post

wp_remote_post es la función estándar de WordPress para llamar a APIs externas y acepta el argumento method, que reenvía a wp_remote_request. Con eso mismo haces el PUT a WooCommerce:

<?php
/**
 * Plugin Name: SocialCutter Catalogue
 * Description: Genera los tamanos de catalogo y los asigna a un producto WooCommerce.
 */

function sc_tamanos_catalogo( int $producto_id, string $maestro_url ): array {
    $respuesta = wp_remote_post( 'https://api.socialcutter.theboomer.dev/api/v1/images/process', array(
        'timeout' => 30,
        'headers' => array(
            'X-API-Key'       => SOCIALCUTTER_API_KEY,
            'Content-Type'    => 'application/json',
            'Idempotency-Key' => 'producto-' . $producto_id,
        ),
        'body' => wp_json_encode( array(
            'source'       => array( 'type' => 'url', 'value' => $maestro_url ),
            'destinations' => array(
                array( 'platform' => 'instagram', 'format' => 'post' ),
                array( 'platform' => 'instagram', 'format' => 'story' ),
            ),
        ) ),
    ) );

    if ( is_wp_error( $respuesta ) ) {
        return array( 'error' => $respuesta->get_error_message() );
    }

    $salidas = json_decode( wp_remote_retrieve_body( $respuesta ), true )['outputs'] ?? array();
    if ( ! $salidas ) {
        return array( 'error' => 'La API no devolvio salidas' );
    }

    $imagenes = array();
    foreach ( $salidas as $salida ) {
        $imagenes[] = array( 'src' => $salida['url'], 'alt' => get_the_title( $producto_id ) );
    }

    $peticion = wp_remote_post(
        rest_url( 'wc/v3/products/' . $producto_id ),
        array(
            'method'  => 'PUT', // wp_remote_post reenvia 'method' a wp_remote_request.
            'timeout' => 30,
            'headers' => array(
                'Authorization' => 'Basic ' . base64_encode( WC_CK . ':' . WC_CS ),
                'Content-Type'  => 'application/json',
            ),
            'body'    => wp_json_encode( array( 'images' => $imagenes ) ),
        )
    );

    return json_decode( wp_remote_retrieve_body( $peticion ), true )['images'] ?? array();
}

Define SOCIALCUTTER_API_KEY, WC_CK y WC_CS en wp-config.php, nunca en el tema. Para adjuntar desde la biblioteca, media_sideload_image( $url, $producto_id, null, 'id' ) devuelve el id del adjunto.

5. Sin código: importador CSV y automatizadores

El importador de WooCommerce acepta una columna Images con URLs separadas por comas: las descarga al importar y monta la galería en ese orden. Genera las medidas, arma el CSV y usa Productos → Importar. Referencia: https://woocommerce.com/document/product-csv-import-suite-column-header-reference/

Con n8n, Zapier o Make el patrón es una llamada HTTP a /api/v1/images/process y otra que actualiza el producto: guía de n8n.

Coste

• 1 uso por destino (plataforma y formato) por petición; los repetidos no se cobran dos veces.
• Los procesamientos fallidos se devuelven.
• Todos los planes incluyen API y MCP: Free 3 usos/día, Basic 10, Pro 30, Agency 100.

Errores típicos

Síntoma	Causa	Solución
401 en la biblioteca de medios	Application Password mal copiada o sitio sin HTTPS	Regenera la contraseña de aplicación y comprueba el TLS
401 en /wc/v3/	Claves ck_/cs_ revocadas o mal pegadas	Revisa WooCommerce → Ajustes → Avanzado → REST API
400 con “image is invalid”	src no es una URL pública o no es una imagen	Comprueba que la URL apunta a una salida de SocialCutter
La principal no es la que querías	Orden de la lista images	Reordena con position; la primera entrada manda

Siguientes pasos

• WordPress: Integra SocialCutter con WordPress y WooCommerce
• PrestaShop: Imágenes de producto en PrestaShop por el Webservice
• Shopify: Integra SocialCutter con la Admin API de Shopify
• Documentación: https://docs.socialcutter.theboomer.dev