> ## Documentation Index
> Fetch the complete documentation index at: https://ayuda.gudink.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API: crear productos a partir de tu arte

> Cómo subir un PNG y crear una remera lista para pedir, sin abrir el editor de Gudink. Función en prueba.

Si tus clientes diseñan en tu propia web (una banda que arma su merch, un usuario que sube su foto), podés crear el producto en Gudink por la API: subís el PNG, elegís la cara, el área y los colores, y recibís un producto listo para cotizar y pedir. Nadie tiene que entrar al editor de Gudink.

> [!NOTE]
>
> Es una **función en prueba** y se habilita por cuenta. Escribinos a [soporte@gudink.com](mailto:soporte@gudink.com) con el email de tu cuenta y te la activamos. Mientras tu cuenta no la tenga, las dos rutas de esta página responden `404 not_found`.

Los ejemplos usan las mismas variables de entorno que el resto de la API:

```bash theme={null}
export GUDINK_API_BASE="https://app.gudink.com/api/v1"
export GUDINK_API_KEY="gk_live_..."   # nunca la escribas en el código
```

## Qué podés crear hoy

| | |
| - | - |
| Producto | Remera básica (`type: "tshirt"`, `model: "basica"`) |
| Colores | `white`, `black`, `gray` (al menos uno, sin repetir) |
| Caras | `front` y/o `back` (al menos una) |
| Áreas del frente | `full` (35 × 40 cm), `top` (35 × 20 cm), `heart` (10 × 10 cm, sobre el pecho) |
| Áreas de la espalda | `full`, `top` |
| Arte | PNG con fondo transparente, hasta 30 MB, uno por cara. El mismo arte va en todos los colores |
| Ubicación | Centrado a lo ancho y ocupando el 80 % del área. En `full` y `top`, arriba, a 2 cm del borde. En `heart`, centrado |

Todavía no entran otros productos (tazas, cuadros, remera oversize o de mujer), JPG o WebP, un arte distinto para las remeras oscuras, varias capas, rotación ni posición libre. Si necesitás alguno, contanos tu caso.

## Paso 1: subir el arte

El cuerpo es el PNG en binario, no JSON ni base64.

```bash theme={null}
curl -sS -X POST "$GUDINK_API_BASE/files" \
  -H "Authorization: Bearer $GUDINK_API_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @arte-frente.png
```

Respuesta `201`:

```json theme={null}
{ "file_id": "9f2c41…(64 caracteres)", "width": 4134, "height": 4724, "size_bytes": 1843021 }
```

* El `file_id` sólo sirve con tu cuenta. Subir el mismo PNG dos veces da el mismo `file_id`.
* Para que imprima bien en el área completa (35 × 40 cm), el PNG tiene que tener alrededor de 4134 × 4724 px, que es 300 dpi.
* Si tenés arte para la espalda, subilo igual y guardá su `file_id`.

## Paso 2: crear el producto

```bash theme={null}
curl -sS -X POST "$GUDINK_API_BASE/products" \
  -H "Authorization: Bearer $GUDINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "tshirt",
    "model": "basica",
    "name": "Remera Gira 2026",
    "colors": ["black", "white"],
    "placements": {
      "front": { "file_id": "9f2c41…", "area": "full" },
      "back":  { "file_id": "41ab07…", "area": "top" }
    },
    "external_id": "banda-123-remera-1"
  }'
```

La respuesta `201` es **el mismo objeto que `GET /products/:id`** (ver [Listar productos](https://ayuda.gudink.com/api/productos-y-envio.md)): `id`, `name`, `product_type`, `thumbnail_url`, `mockups`, `orderable` y `variants`, con cada talle de cada color que pediste y su precio.

```json theme={null}
{
  "id": 490,
  "name": "Remera Gira 2026",
  "product_type": "tshirt",
  "thumbnail_url": "https://...",
  "mockups": [
    { "url": "https://...", "color": "Negro", "view": "front" },
    { "url": "https://...", "color": "Negro", "view": "back" }
  ],
  "orderable": true,
  "variants": [
    { "id": 41, "size": "M", "color": "Negro", "available": true, "price": 25990 }
  ]
}
```

* Crear un producto tarda unos segundos, porque armamos el archivo de impresión y las imágenes. Poné un timeout de 60 segundos.
* Hay una imagen por cada cara con arte, en el primer color de `colors`. Mostrala en tu web como vista previa.
* El producto queda en **borrador** en tu panel de Gudink: no se publica en ningún canal, pero ya lo podés pedir. Desde el panel lo podés abrir, retocar o archivar.

## Paso 3: cotizar y pedir

Con el `id` del producto y el `id` de una variante, seguís como con cualquier otro producto: [cotizás el envío](https://ayuda.gudink.com/api/productos-y-envio.md) y [creás el pedido](https://ayuda.gudink.com/api/pedidos.md).

## No crear el mismo producto dos veces

`external_id` es opcional: de 1 a 120 caracteres (`A-Z a-z 0-9 . _ : -`), único en tu cuenta. Usalo siempre que puedas, así un reintento no deja productos duplicados.

* Mismo `external_id` y mismo cuerpo: responde `200` con el producto que ya creaste.
* Mismo `external_id` con otro cuerpo (otro nombre, otros colores, otro arte): responde `409 conflict` y el mensaje nombra el producto existente.
* Sin `external_id`, cada llamada crea un producto nuevo.

Si un alta falla a mitad de camino, no queda nada a medias: el producto incompleto se archiva y podés reintentar con el mismo `external_id`.

## Errores

| Status | Código | Cuándo |
| - | - | - |
| 400 | `validation_error` | El cuerpo tiene algo inválido. `details.fields` dice qué campo (por ejemplo `placements.back.area`). En `/files`: no es PNG, está dañado o no vino con `Content-Type: image/png` |
| 404 | `not_found` | Un `file_id` que no es de tu cuenta, o tu cuenta todavía no tiene la función |
| 409 | `conflict` | El `external_id` ya se usó con otro cuerpo |
| 413 | `payload_too_large` | El PNG pesa más de 30 MB |
| 429 | `rate_limited` | Más de 30 productos por hora o 300 por día. Archivos: 60 por hora o 600 por día |
| 503 | `service_unavailable` | Mucha carga o el alta tardó demasiado. Reintentá después de lo que diga `Retry-After` |

El resto de los errores son los de siempre: ver [Errores, límites y versiones](https://ayuda.gudink.com/api/errores-y-limites.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.