# Sube imágenes de catálogo a WooCommerce con SocialCutter
> Sube el maestro a la biblioteca de medios o pásalo por URL, genera los tamaños con SocialCutter y asígnalos al producto.
- URL: https://socialcutter.theboomer.dev/guias/woocommerce/
- Idioma: es
- Familia: cms
- Actualizado: 2026-09-24
- Palabras clave: WooCommerce, WordPress, biblioteca de medios, REST API, Application Passwords, galería de producto, PHP
## 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**.

```bash
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:

```bash
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

```bash
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`.

```bash
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
<?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](/guias/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](/guias/wordpress/)
- PrestaShop: [Imágenes de producto en PrestaShop por el Webservice](/guias/prestashop/)
- Shopify: [Integra SocialCutter con la Admin API de Shopify](/guias/shopify/)
- Documentación: https://docs.socialcutter.theboomer.dev