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-KEY a tu solicitud
Establece 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": "order",
  "currency": "USD",
  "shippingAddress": {
    "country": "US",
    "firstName": "John",
    "lastName": "Doe",
    "addressLine1": "123 Main St",
    "city": "New York",
    "postCode": "10001",
    "state": "NY",
    "email": "[email protected]",
    "phone": "1234567890"
  },
  "items": [
    {
      "itemReferenceId": "item-123",
      "productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor",
      "quantity": 1,
      "files": [
        {
          "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}/order

Incluye 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": "your-order-ref-123",
  "createdAt": "2025-04-12T10:23:28+00:00"
}

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}/cancel

Buscar pedidos

Encuentra pedidos según los criterios que elijas:

POST https://api.partner-connect.io/api/{partner-prefix}/search

Actualizar 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": "Business Card",
  "productVariant": {
    "Size": "Standard",
    "Paper": "Premium Matte",
    "Color": "Full Color Both Sides"
  }
}

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:

Prueba con pedidos de muestra: Crea pedidos de prueba con cantidades bajas y comprueba que aparezcan 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:secreto en la cabecera X-API-KEY
Está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

Próximos pasos

Ahora que ya entiende los conceptos básicos de la API de GelatoConnect, está listo para:

Lee la documentación completa de la API para obtener información detallada sobre los endpoints
Descubre las mejores prácticas de API para autenticación, límites de uso y gestión de errores
Descubre cómo trabajar con endpoints de la API con ejemplos detallados de operaciones

Para obtener ayuda adicional con su integración de la API, póngase en contacto con nuestro equipo de asistencia en [email protected].

[Empezar - GCW] Empezar con la API de GelatoConnect