Al enviar pedidos a GelatoConnect a través de la API, tienes dos opciones para especificar productos: usar los UID de producto o usar productos personalizados del cliente. En esta guía te explicamos ambas formas, sus ventajas y cuándo conviene usar cada una.
Enfoque del UID del producto
El enfoque de UID de producto consiste en utilizar identificadores únicos de producto (UID) para especificar los productos en tus pedidos.
Cómo funciona
Cuando usas los identificadores únicos de producto (UIDs), tienes que incluir el parámetro productUid en el artículo de tu pedido:
{ "itemReferenceId": "ITEM-001", "productUid": "flat_product_pf_a4_pt_200-gsm-no-estucado_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", "quantity": 1, "archivos": [ { "type": "default", "url": "https://example.com/files/printfile.pdf" } ]}Estructura del UID de producto
Un UID de producto es una cadena estructurada que codifica los atributos del producto. Por ejemplo, en flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor:
flat_product: Tipo de productopf_a4: Formato de papel (tamaño A4)pt_200-gsm-uncoated: Tipo de papel (papel no estucado de 200 gsm)cl_4-0: Configuración de color (proceso de 4 colores en la parte delantera, sin color en la parte trasera)ct_none: Corte (ninguno)prt_none: Efectos especiales de impresión (ninguno)sft_none: Acabados superficiales (ninguno)set_none: Efectos especiales (ninguno)hor: Orientación (horizontal)
Enfoque hacia los productos para clientes
El enfoque de Productos para clientes consiste en crear definiciones de productos personalizados en GelatoConnect y referenciarlas por nombre y variante en tus pedidos.
Cómo funciona
Primero, configuras los Productos de Cliente en GelatoConnect, definiendo los nombres de los productos y sus opciones de variante. Después, al hacer pedidos, haces referencia a estos productos usando los parámetros productName y productVariant:
{ "itemReferenceId": "ITEM-001", "productName": "Tarjeta de visita", "productVariant": { "Size": "Estándar", "Paper": "Mate premium", "Color": "Color completo en ambas caras" }, "quantity": 100, "archivos": [ { "type": "frontal", "url": "https://example.com/files/front.pdf" }, { "type": "dorso", "url": "https://example.com/files/back.pdf" } ]}Configura los productos para tus clientes
Antes de usar los productos personalizados en tus pedidos por API, tienes que configurarlos en GelatoConnect:
Ve a la sección de Productos en GelatoConnect
Crea productos personalizados para clientes con nombres y opciones de variante específicas
Relaciona estos productos de clientes con las especificaciones de producto de Gelato
Cuándo elegir cada opción
Cuándo usar los UIDs de producto:
Acabas de dar tus primeros pasos con GelatoConnect
Tienes pocos productos fijos
Quieres ponerlo en marcha rápido, sin complicaciones ni pasos extra
Estás creando un prototipo o una prueba para ver cómo funciona la idea
Cuándo usar productos personalizados:
Tienes un catálogo de productos muy amplio
Quieres referencias de productos más intuitivas en tu código
Los nombres de tus productos no siguen las convenciones de Gelato
Las configuraciones de producto pueden cambiar con el tiempo
Ejemplos de implementación
Ejemplo de UID de producto
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \--header 'Content-Type: application/json' \--header 'X-API-KEY: tu-clave:tu-secreto' \--data '{ "orderReferenceId": "ORDER-123", "orderType": "pedido", "currency": "USD", "shippingAddress": { "country": "US", "firstName": "John", "lastName": "Doe", "addressLine1": "Calle Principal 123", "city": "Nueva York", "postCode": "10001", "state": "NY", "email": "[email protected]", "phone": "123-456-7890" }, "items": [ { "itemReferenceId": "ITEM-001", "productUid": "flat_product_pf_a4_pt_200-gsm-no-estucado_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", "quantity": 1, "archivos": [ { "type": "predeterminado", "url": "https://example.com/files/printfile.pdf" } ] } ]}'Ejemplo de productos para clientes
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \--header 'Content-Type: application/json' \--header 'X-API-KEY: tu-clave:tu-secreto' \--data '{ "orderReferenceId": "ORDER-124", "orderType": "order", "currency": "USD", "shippingAddress": { "country": "US", "firstName": "John", "lastName": "Doe", "addressLine1": "Calle Principal 123", "city": "Nueva York", "postCode": "10001", "state": "NY", "email": "[email protected]", "phone": "123-456-7890" }, "items": [ { "itemReferenceId": "ITEM-001", "productName": "Panfleto", "productVariant": { "Size": "A4", "Paper": "No estucado 200gsm", "Printing": "Color completo por una cara" }, "quantity": 100, "archivos": [ { "type": "predeterminado", "url": "https://example.com/files/panfleto.pdf" } ] } ]}'Buenas prácticas
Elijas el camino que elijas, sigue estos consejos para sacar el máximo partido:
Cohesión: Mantén el mismo enfoque en todo momento durante tu implementación
Documentación: Mantén una documentación clara de los mapeos de tus productos
Validación: Comprueba los identificadores de producto antes de enviar los pedidos
Pruebas: Haz pruebas a fondo con pedidos de ejemplo antes de lanzarte
Gestión de errores: Implementa una gestión de errores sólida para productos no válidos
Cambiando de enfoque
Si empiezas usando identificadores de producto y más adelante quieres pasarte a productos personalizados para clientes:
Configura tus productos personalizados de clientes en GelatoConnect
Asígnalos a los UIDs de producto que has estado usando
Actualiza tu implementación de la API para usar productName y productVariant
Haz pruebas a fondo antes de lanzar en producción
La transición inversa también es posible, aunque no suele ser lo habitual.
Conclusión
Ambos enfoques tienen sus ventajas, y la elección depende de tus necesidades y limitaciones concretas. Los UIDs de producto ofrecen sencillez y acceso directo al catálogo de Gelato, mientras que los productos personalizados aportan mayor claridad, flexibilidad y una gestión centralizada.
Para la mayoría de los proyectos a largo plazo, los productos personalizados ofrecen ventajas en cuanto a mantenimiento y claridad. Sin embargo, para implementaciones rápidas o casos muy concretos, puede ser mejor usar los identificadores únicos de producto (UID).
Para más información sobre cómo configurar productos para clientes en GelatoConnect, consulta la guía Crear productos para clientes.