Generador de maquetas API

Para generar maquetas, primero necesitarás decidir en qué productos las quieres. Los métodos API para recuperar productos y variantes se pueden encontrar en la API del catálogo de Printful.

Nota: Recuerda distinguir la diferencia entre una id de producto y una id de variante. Algunos puntos finales de API requieren la id de una variante y otras de un producto.

Archivos de impresión

Un archivo de impresión define la resolución que debería usarse para crear una maqueta o para presentar un pedido.

La información sobre los archivos de impresión de una variante de producto puede recuperarse del punto final del archivo de impresión.

Por ejemplo, un póster de 10×10 requiere un archivo de impresión de 1500×1500 píxeles para producir una impresión de 150 DPI. Puedes utilizar archivos de una mayor resolución para conseguir un mejor resultado, pero mantén el aspecto del radio igual que el definido para el archivo de impresión. Eso significa que si usas un archivo de 3000x3000 píxeles, se producirá una impresión de 300 DPI. Pero si usas un archivo de 3000×1500 píxeles (relación de aspecto diferente) en un póster 10×10, puede que haya que recortar. El parámetro del archivo de impresión modo_rellenar define si se necesita cortar o el archivo se ajustará en el archivo de impresión resultante del producto.

Algunos archivos se pueden rotar. El campo puede_rotar define esta función. Esto se aplica a productos de decoración de pared y debería usarse si quieres generar una maqueta de producto horizontal o vertical.

Los archivos de impresión de decoración de pared son horizontales. Si deseas crear una maqueta vertical, puedes rotar los archivos de impresión y la maqueta generada recibirá esa orientación. Por ejemplo, el archivo de impresión de un póster de 16x12 es de 2400x1800 píxeles y se genera de manera horizontal. Si deseas obtener una maqueta vertical, puedes crear el archivo de impresión de 1800x2400 píxeles. La misma estrategia se aplica cuando presentas un pedido.

Los archivos de impresión a veces se reutilizan para múltiples variantes y productos. Por ejemplo, los pósteres de 14x14 utilizan el mismo archivo de impresión que el póster enmarcado. La mayoría de camisetas con impresiones frontales utilizan el mismo archivo de impresión.

Nota: cuando generas maquetas no hay necesidad de proporcionar un archivo de impresión de tamaño completo. Las maquetas se generan a un ancho de 1000px, así que puedes reducir el archivo a 1000px. Esto reducirá el tiempo de procesamiento tanto en tu parte como en la de Printful.

Generación de maquetas

La generación de maquetas requiere tiempo, por eso no puede ocurrir de manera instantánea.

Cuando solicitas la generación de una maqueta, se crea una tarea y recibes la clave tarea que podrás utilizar para recuperar la lista de maquetas generadas. No podemos garantizar que tras un tiempo determinado las maquetas se generen, así que tendrás que ir comprobando si las tareas se han completado. La primera solicitud de resultados no debe ser antes de 10 segundos, así que planea con antelación que la tarea de generación se realizará en dos pasos: crear una tarea y comprobar con intervalos si la tarea está lista.

Importante Las URL para imágenes de maquetas son temporales, expirarán tras un día, así que tendrás que guardarlas en tu propio servidor.

Flujo del proceso

  1. Decide qué variantes de productos quieres generar.

  2. Recupera la lista de archivos de impresión para los productos y las variantes elegidas. Utiliza las variantes de archivos de impresión para determinar qué archivo necesitarás para generar una colocación específica en una variante específica de un producto.

  3. Sube tu archivo a una URL pública que coincida con el radio del tamaño del archivo de impresión (u ofrece posiciones para la solicitud de generación)

  4. Crea una tarea de generación de maquetas y guarda la clave de la tarea.

  5. Usa la última clave para comprobar si la tarea se ha completado. Si todavía está pendiente, repite después del intervalo.

  6. Cuando la tarea se haya realizado, descarga y guarda las maquetas en tu propio servidor. Las URL de las maquetas son temporales y se eliminarán tras un día.

Ejemplo de uso

Vamos a ver un ejemplo. Quieres ofrecer a los usuarios el diseño de su propia camiseta.

Elegiremos esta camiseta como ejemplo: Bella + Canvas 3001 camiseta unisex

El ID del producto es 71.

Vamos a buscar algunas variantes disponibles para esta camiseta:
https://api.printful.com/products/71

Elegiremos una camiseta blanca y negra en las tallas M, L y XL. Las respectivas ID de las variantes son:
4012, 4013, 4014, 4017,4018 y 4019.

Después, vamos a necesitar obtener los tamaños de archivos de impresión para estas variantes:
https://api.printful.com/mockup-generator/printfiles/71

Vemos que hay dos posiciones disponibles para este producto: frontal y trasera. Los pósteres, por ejemplo, solo tendrán una posición llamada por defecto.

En nuestros ID de variantes elegidas, vemos que utilizan el mismo archivo de impresión para impresiones traseras y frontales:

{
    "product_id": 71,
    "available_placements": {
        "front": "Front print",
        "back": "Back print",
        "label_outside": "Outside label"
    },
    "printfiles": [
        {
            "printfile_id": 1,
            "width": 1800,
            "height": 2400,
            "dpi": 150,
            "fill_mode": "fit",
            "can_rotate": false
        }
    ],
    "variant_printfiles": [
        {
            "variant_id": 4012,
            "placements": {
                "front": 1,
                "back": 1
            }
        }
    ]
}
  • dpi Para ancho y altura conocido, este es el DPI resultante del producto actual.

  • modo_rellenar Valores posibles: "ajustar" o "cubrir". Indica en qué modo se generarán las maquetas.

  • puede_rotar Los pósteres, por ejemplo, permiten la rotación. Si pasas la imagen a una posición horizontal.

  • colocación.frontal ID de archivo de impresión.

Podemos ver que el tamaño completo del archivo de impresión es 1800×2400 para variantes con impresiones traseras y frontales.

Importante: este tamaño de archivo de impresión se utiliza para estampados. Para la generación de maquetas la imagen no debería exceder un ancho 1000px, porque las maquetas resultantes no serán mayores de 1000px.

Cuando conocemos el tamaño de un archivo de impresión, necesitamos calcular las posiciones. Los valores de posición son relativos, el tamaño de imagen no tiene que coincidir con el ancho y la altura de las posiciones. Cuando se genera una maqueta rellenamos el área de posición dentro del área de impresión o la cubrimos, dependiendo de valor modo_rellenar del archivo de impresión.

Las posiciones que se dan a continuación resultarían en una imagen cuadrada centrada verticalmente en el área de impresión.

    {
        "area_width": 1800,
        "area_height": 2400,
        "width": 1800,
        "height": 1800,
        "top": 300,
        "left": 0
    }
  • ancho_área Ancho relativo del área de impresión.

  • altura_área Altura relativa del área de impresión.

  • ancho Ancho relativo de tu imagen.

  • altura Altura relativa de tu imagen.

  • superior Compensación superior de imagen del área.

  • izquierda Compensación izquierda de imagen del área.

Importante: para pósteres, lienzos y otros productos cuyos archivos de impresión permitan el valor de rotación (puede_rotar en respuesta de archivo de impresión), puedes cambiar el ancho y la altura para crear una maqueta de producto que sea horizontal o vertical.

Una vez que hayamos calculado las posiciones, podemos realizar la generación de maquetas utilizando el punto final de generador de maquetas:

POST a https://api.printful.com/mockup-generator/create-task/71con parámetros de cuerpo:

{
    "variant_ids" : [4012, 4013, 4014, 4017, 4018, 4019],
    "format": "jpg",
    "files" : [
        {
            "placement": "front",
            "image_url": "http://your-site/path-to-front-printfile.jpg",
            "position": {
                "area_width": 1800,
                "area_height": 2400,
                "width": 1800,
                "height": 1800,
                "top": 300,
                "left": 0
            }
        },
        {
            "placement": "back",
            "image_url": "http://your-site/path-to-back-printfile.jpg",
            "position": {
                "area_width": 1800,
                "area_height": 2400,
                "width": 1800,
                "height": 1800,
                "top": 300,
                "left": 0
            }
        }
    ]
}

En respuesta, recibirás una clave de tarea y el estado actual de la tarea:

{
    "task_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "pending"
}

Después de un intervalo de unos segundos, puedes intentar comprobar el resultado haciendo una solicitud GET en https://api.printful.com/mockup-generator/task? task_key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Si la tarea se ha completado, la respuesta será así:

{
    "task_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "completed",
    "mockups": [
        {
            "variant_ids": [
                4011,
                4012,
                4013
            ],
            "placement": "front",
            "mockup_url": "https://url-to/front-mockup.png"
        },
        {
            "variant_ids": [
                4011,
                4012,
                4013
            ],
            "placement": "back",
            "mockup_url": "https://url-to/back-mockup.png"
        },
        {
            "variant_ids": [
                4016,
                4017,
                4018
            ],
            "placement": "front",
            "mockup_url": "https://url-to/front-mockup.png"
        },
        {
            "variant_ids": [
                4016,
                4017,
                4018
            ],
            "placement": "back",
            "mockup_url": "https://url-to/back-mockup.png"
        }
    ]
}

En este momento, tendrás que descargar las URL de tus maquetas y guardarlas en tu propio servidor, ¡y ya estará listo!

Plantilla del producto

Si deseas crear tu propia IU de generador de maquetas, este es el lugar para comenzar. Utilizando el punto final de plantilla del producto puedes obtener imágenes de la plantilla y las posiciones necesarias para crear una herramienta en la que los usuarios pueden colocar sus archivos.

Si quieres crear un generador de tazas, por ejemplo, tienes que invocar el punto final /mockup-generator/templates/19 con el ID del producto. Mirando la variante del mapeo de campo, podemos determinar que para la variante 1320 de una taza de 11 cl tenemos que usar el ID de plantilla 919. Así es una estructura de una plantilla:

{
    "template_id": 919,
    "image_url": "https://www.printful.com/files/generator/40/11oz_template.png",
    "background_url": null,
    "background_color": null,
    "printfile_id": 43,
    "template_width": 560,
    "template_height": 295,
    "print_area_width": 520,
    "print_area_height": 202,
    "print_area_top": 18,
    "print_area_left": 20,
    "is_template_on_front": true
}
  • ID_archivo_de_impresión Podemos recuperar el tamaño del archivo de impresión de otros puntos finales de archivos de impresión.

  • ancho_de_plantilla Contenedor principal de ancho y píxeles.

  • altura_de_plantilla Contenedor principal de altura.

  • ancho_área_impresión Área interna donde ocurre el posicionamiento.

  • altura_área_impresión Área interna.

  • área_impresión_superior Compensación del contenedor principal.

  • área_impresión_izquierda Compensación del contenedor principal.

  • plantilla_frontal Indica si la imagen de usuario se debería mostrar encima o debajo de la plantilla de imagen.

Con esta información, podemos crear un marcado HTML:

<div style="position: relative; width: 520px; height: 295px;">
    <div style="position: absolute; width: 520px; height: 202px; top:18px; left:20px; background:rgba(255,233,230,0.33)">
        <img src="/static/images/layout/logo-printful.png" style="position: absolute; left: 43px; top: 77px; width: 140px; height: 63px;">
    </div>
    <div style="position: absolute; width: 560px; height: 295px; background:url(/files/generator/40/11oz_template.png) center center no-repeat"></div>
</div>

Quedaría así en el buscador

Para generar maquetas con posiciones, realizamos una solicitud POST a https://api.printful.com/mockup-generator/create-task/19con parámetros de cuerpo:

{
    "variant_ids" : [1320],
    "format": "jpg",
    "files" : [
        {
            "placement": "default",
            "image_url": "https://duw6wk4ou1qt.cloudfront.net/static/v716/images/layout/logo-printful.png",
            "position": {
                "area_width": 520,
                "area_height": 202,
                "width": 140,
                "height": 63,
                "top": 77,
                "left": 43
            }
        }
    ]
}
  • ancho_área Valor del ancho_del_área_de_impresión en una plantilla.

  • altura_área Valor de la altura_del_área_de_impresión en una plantilla.

  • ancho Ancho de imagen.

  • altura Altura de imagen.

  • superior Compensación superior de imagen en área.

  • izquierda Compensación izquierda de imagen en área.

Puntos finales

Create a mockup generation task

POST https://api.printful.com/mockup-generator/create-task/{id}

Creates an asynchronous mockup generation task. Generation result can be retrieved using mockup generation task retrieval endpoint.

Rate limiting: Up to 10 requests per 60 seconds. A 60 seconds lockout is applied if request count is exceeded.
Parámetros de entrada
id integer Product ID.
Request body CreateGenerationTask Mockup generation data.
variant_ids integer [ ] List of variant ids you want to generate.
format {jpg, png} Generated file format. PNG will have a transparent background, JPG will have a smaller file size.
width integer Width of the resulting mockup images (min 50, max 1000, default is 1000)
product_options string [ ] Key-value list of product options (embroidery thread, stitch colors). Product options can be found in Catalog API endpoint.
option_groups string [ ] List of option group names you want to generate. Product's option groups can be found in printfile API request.
options string [ ] List of option names you want to generate. Product's options can be found in printfile API request.
files GenerationTaskFile [ ] Placement and file mapping to be generated.
placement string Placement identifier (front, back, etc.).
image_url string Public URL where your file is stored.
position GenerationTaskFilePosition Position
area_width integer Positioning area width on print area
area_height integer Positioning area height on print area
width integer Width of the image in given area
height integer Height of the image in given area
top integer Image top offset in given area
left integer Image left offset in given area
Formato de respuesta:
code integer Código del estado de respuesta 200
result GenerationTask
task_key string Task identifier you will use to retrieve generated mockups.
status {pending, completed, failed} Status of the generation task.
error string If task has failed, reason will be provided here.
mockups GenerationTaskMockups [ ] If task is completed, list of mockups will be provided here.
placement string Placement identifier.
variant_ids integer [ ] List of variant ids this mockup is used for. One mockup can be used for multiple variants.
mockup_url string Temporary URL of the primary mockup.
extra GenerationTaskExtraMockup [ ] Optional extra mockups.
title string Display name of the extra mockup.
url string Temporary URL of the mockup.
Clave API
id Product ID.
Request body
Ejecutar

Retrieve product variant printfiles

GET https://api.printful.com/mockup-generator/printfiles/{id}

List of printfiles available for products variants. Printfile indicates what file resolution should be used to create a mockup or submit an order.
Parámetros de entrada
id integer Product ID
Formato de respuesta:
code integer Código del estado de respuesta 200
result PrintfileInfo
product_id integer Requested product id.
available_placements object List of available placements. Key is placement identifier, value is display name. (e.g. {embroidery_front: Front, ..}).
printfiles Printfile [ ] Array of printfiles available for product.
printfile_id integer Unique printfile identifier.
width integer Width in pixels.
height integer Height in pixels.
dpi integer Resulting DPI for given width and height.
fill_mode {cover, fit} Indicates if printfile will be used in cover or fit mode. Cover mode can produce cropping if side ratio does not match printfile.
can_rotate boolean Indicates if printfile can be rotated horizontally (e.g. for posters).
variant_printfiles VariantPrintfile [ ] Each variant mapping to placement and their printfiles.
variant_id integer Product variant id.
placements object Key is placement and value is representing printfile_id. (e.g. {front: 1, back: 2, ..}).
option_groups string [ ] List of option groups available (e.g. for leggings Barefoot, High-heels, etc.). Note that not every variant has all groups available for generation.
options string [ ] List of options available for generation (e.g. Front, Back).
Clave API
id Product ID
Ejecutar

Mockup generation task result

GET https://api.printful.com/mockup-generator/task

Returns asynchronous mockup generation task result. If generation task is completed, it will contain a list of generated mockups.
Parámetros de entrada
task_key string Task key retrieved when creating the generation task.
Formato de respuesta:
code integer Código del estado de respuesta 200
result GenerationTask
task_key string Task identifier you will use to retrieve generated mockups.
status {pending, completed, failed} Status of the generation task.
error string If task has failed, reason will be provided here.
mockups GenerationTaskMockups [ ] If task is completed, list of mockups will be provided here.
placement string Placement identifier.
variant_ids integer [ ] List of variant ids this mockup is used for. One mockup can be used for multiple variants.
mockup_url string Temporary URL of the primary mockup.
extra GenerationTaskExtraMockup [ ] Optional extra mockups.
title string Display name of the extra mockup.
url string Temporary URL of the mockup.
Clave API
task_key Task key retrieved when creating the generation task.
Ejecutar

Product templates

GET https://api.printful.com/mockup-generator/templates/{id}

Retrieve list of templates that can be used for client-side positioning.
Parámetros de entrada
id int Product ID.
Formato de respuesta:
code integer Código del estado de respuesta 200
result ProductTemplates
version integer Resource version. If this changes, resources (positions, images, etc.) should be re-cached.
min_dpi integer Recommended minimum DPI for given product.
variant_mapping TemplateVariantMapping [ ] List of product variants mapped to templates. From this information you can determine which template should be used for a variant.
variant_id integer Product variant ID.
templates TemplateVariantMappingItem [ ] Product variant ID.
placement string Placement ID.
template_id integer Corresponding template id which should be used for this variant and placement combination.
templates Template [ ] List of templates. Use variant_mapping to determine which template corresponds to which product variant.
template_id integer Template ID.
image_url string Main template image URL.
background_url string Background image URL (optional).
background_color string HEX color code that should be used as a background color.
printfile_id integer Printfile ID that should be generated for this template. See printfile API endpoint for list of Printfiles.
template_width integer Width of the whole template in pixels.
template_height integer Height of the whole template in pixels.
print_area_width integer Print area width (image is positioned in this area).
print_area_height integer Print area height (image is positioned in this area).
print_area_top integer Print area top offset (offset in template).
print_area_left integer Print area left offset (offset in template).
is_template_on_front boolean Should the main template image (image_url) be used as an overlay or as a background.
conflicting_placements TemplatePlacementConflict [ ] List of conflicting placements. Used to determine which placements can be used together.
placement string Placement ID
conflicts string [ ] List Placement IDs that are conflicting with given placement
Clave API
id Product ID.
Ejecutar

¿Listo para probar Printful?