Introducción
La API de GelatoConnect te permite integrar tus sistemas con GelatoConnect de forma automática para enviar pedidos, seguir su estado y gestionar los detalles de envío. Esta guía te ayudará a entender cómo empezar a usar la API y a poner en marcha tu primera integración.
Requisitos previos
Antes de empezar a trabajar con la API de GelatoConnect, deberías tener lo siguiente:
Tu clave y secreto de API (te los damos cuando configuras un conector para tu cliente)
Conocimientos básicos sobre las API REST y los métodos HTTP
Conocer el formato de datos JSON
Un entorno de desarrollo que pueda hacer solicitudes HTTP
Conceptos básicos de la API
La API de gestión de pedidos de GelatoConnect está basada en los principios REST y utiliza los métodos HTTP estándar para interactuar con los recursos. Todas las solicitudes a la API deben usar HTTPS y todas las respuestas se devuelven en formato JSON, incluidos los mensajes de error.
URL base
La URL base para la API de GelatoConnect es:
https://api.partner-connect.io/api/{partner-prefix}/Recibirás tu prefijo de socio específico durante el proceso de incorporación.
Autenticación
Todas las solicitudes a la API deben incluir tus credenciales de autenticación en el encabezado. Para autenticarte:
Añade la cabecera
X-API-KEYa tu solicitudEstablece el valor con tu clave y secreto en el formato
clave:secreto
Ejemplo:
X-API-KEY: your-api-key:your-api-secret
Cómo hacer tu primera solicitud a la API
Vamos a ver juntos, paso a paso, cómo hacer una solicitud sencilla a la API para enviar un pedido.
1. Prepara los datos de tu pedido
Crea un objeto JSON con los detalles del pedido. Aquí tienes un ejemplo sencillo:
{"orderReferenceId": "your-order-ref-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": "1234567890"},"items": [{"itemReferenceId": "item-123","productUid": "flat_product_pf_a4_pt_200-gsm-no estucado_cl_4-0_ct_none_prt_none_sft_none_set_none_hor","cantidad": 1,"archivos": [{"type": "default","url": "https://example.com/path/to/printfile.pdf"}]}]}2. Envía el pedido
Haz una solicitud POST al endpoint para enviar el pedido:
POST https://api.partner-connect.io/api/{partner-prefix}/orderIncluye tu encabezado de autenticación y los datos del pedido en formato JSON en el cuerpo de la solicitud.
3. Gestiona la respuesta
Si todo va bien, recibirás una respuesta como esta:
{"id": "32884a3e-bd09-42be-8225-c5cea7d24611","orderReferenceId": "tu-referencia-pedido-123","createdAt": "12/04/2025 10:23:28"}El campo id contiene el ID de pedido de GelatoConnect, que deberías guardar para futuras consultas.
Operaciones habituales de la API
Cuando ya domines cómo enviar pedidos básicos, puedes descubrir otras funciones de la API:
Ver detalles del pedido
Consulta la información de un pedido existente:
GET https://api.partner-connect.io/api/{partner-prefix}/{orderId}Cancelar un pedido
Cancelar un pedido que aún no ha sido enviado:
POST https://api.partner-connect.io/api/{partner-prefix}/{orderId}/cancelBuscar pedidos
Encuentra pedidos según los criterios que elijas:
POST https://api.partner-connect.io/api/{partner-prefix}/searchActualizar envío
Modifica los datos de envío de un pedido:
PUT https://api.partner-connect.io/api/{partner-prefix}/{orderId}Poner en marcha productos personalizados para tus clientes
En lugar de usar los UIDs de producto, puedes utilizar Productos de cliente para que todo sea más fácil de entender:
{"productName": "Tarjeta de visita","productVariant": {"Size": "Estándar","Papel": "Mate premium","Color": "Color completo en ambas caras"}}Para poder usarlos en las llamadas a la API, primero tienes que configurar los productos de cliente en GelatoConnect.
Probando tu integración
Antes de lanzar tu integración, pruébala a fondo siguiendo estos pasos:
Haz pruebas con pedidos de muestra: Crea pedidos de prueba con pocas unidades y comprueba que aparecen correctamente en GelatoConnect.
Verifica las actualizaciones de estado de los pedidos: Sigue el recorrido de los pedidos para asegurarte de que tu sistema recibe y gestiona correctamente los cambios de estado.
Gestión de errores: Crea pedidos no válidos a propósito para poner a prueba tu lógica de gestión de errores.
Pruebas de principio a fin: Recorre todo el proceso de pedido, desde que lo envías hasta que lo recibes, usando un pequeño grupo de pedidos de prueba.
Buenas prácticas
Para lograr una integración perfecta con la API de GelatoConnect:
ID de pedido de la tienda: Guarda siempre el ID de pedido de GelatoConnect que recibes al crear el pedido.
Implementa una gestión de errores: Añade un sistema sólido para manejar respuestas inesperadas o caídas de la API.
Usa la idempotencia: Genera identificadores de pedido únicos para evitar pedidos duplicados.
Implementa la espera progresiva: Si recibes errores por límite de solicitudes (429), espera cada vez un poco más antes de volver a intentarlo.
Controla el uso de la API: Lleva un seguimiento de tu uso de la API para no llegar al límite de solicitudes.
Solución de problemas habituales
Errores de autenticación
Si ves un error 401 Unauthorized, comprueba lo siguiente:
Tu clave y secreto de API son correctos
El formato es
clave:secretoen la cabecera X-API-KEYEstás usando HTTPS, no HTTP
Errores de solicitud no válida
Si ves un error 400 de solicitud incorrecta:
Revisa el mensaje de error para ver qué campos tienen problemas
Verifica que todos los campos obligatorios estén incluidos
Confirma que el formato JSON es válido
Errores por límite de solicitudes
Si ves un error 429 de demasiadas solicitudes:
Aplica una estrategia de espera para espaciar las solicitudes
Si puedes, agrupa las solicitudes
Revisa tu integración para evitar llamadas repetidas innecesarias
Siguiente paso
Ahora que ya conoces lo básico de la API de GelatoConnect, también estás listo para consultar la documentación completa de la API y descubrir toda la información detallada sobre los endpoints 🔗 [Recepción de pedidos - GCW] Documentación de la API de gestión de pedidos