Ir al contenido principal

[Recepción de pedidos - GCW] Trabajando con los puntos finales de la API de pedidos

T
Escrito por Toby Dawson
Actualizado hace más de 3 semanas

Esta guía te ofrece instrucciones prácticas y ejemplos para trabajar con los endpoints de la API de pedidos de GelatoConnect. Te mostraremos cómo enviar pedidos, cancelarlos, actualizar la información de envío, consultar los detalles de los pedidos y buscar pedidos usando la API.

Requisitos previos

Antes de empezar a trabajar con estos endpoints, asegúrate de tener lo siguiente:

  • Tu clave y secreto de API (te los damos cuando configuras un conector para tu cliente)

  • La URL base para tus puntos finales de API

  • Conocimientos básicos para hacer solicitudes HTTP con curl o la herramienta que prefieras

Enviar pedido

El endpoint Enviar pedido te permite crear un nuevo pedido en GelatoConnect.

Punto final: POST /{submitOrderUrl}

Ejemplo de solicitud

# Enviar un pedido básicocurl --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": "YOUR-ORDER-123", "orderType": "pedido", "currency": "USD", "shippingAddress": { "country": "EE. UU.", "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": "default", "url": "https://example.com/files/printfile.pdf" } ] } ]}'

Ejemplo de respuesta

{ "id": "32884a3e-bd09-42be-8225-c5cea7d24611", "orderReferenceId": "TU-PEDIDO-123", "createdAt": "13/04/2025 10:23:28"}

Usar productos personalizados

En lugar de indicar un productUid, puedes usar productos personalizados con productName y productVariant:

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": "YOUR-ORDER-124", "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", "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": "volver", "url": "https://example.com/files/back.pdf" } ] } ]}'

Pedidos internacionales

Para pedidos internacionales, indica los precios de venta al público para las declaraciones de aduana:

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": "INTL-ORDER-456", "orderType": "pedido", "currency": "EUR", "retailCurrency": "GBP", "retailShippingPriceInclVat": 6,99, "shippingAddress": { "country": "DE", "firstName": "Hans", "lastName": "Schmidt", "addressLine1": "Unter den Linden 10", "city": "Berlín", "postCode": "10117", "email": "[email protected]", "phone": "+49123456789" }, "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, "retailPriceInclVat": 19,99, "files": [ { "type": "default", "url": "https://example.com/files/printfile.pdf" } ] } ]}'

Problemas habituales

  1. Faltan campos obligatorios: Asegúrate de incluir todos los campos necesarios en tu solicitud.

  2. URLs de archivos no válidas: Asegúrate de que las URLs de tus archivos sean accesibles para todo el mundo.

  3. UID de producto desconocido: Comprueba que el UID del producto existe o utiliza productos personalizados.

  4. ID de referencia de pedido duplicado: Usa un ID de referencia único para cada pedido.

Cancelar orden

El endpoint Cancel Order te permite detener el proceso de producción y envío de un pedido que aún no ha sido enviado.

Punto final: POST /{orderCancelUrl}/{orderId}/cancel

Ejemplo de solicitud

# Cancelar usando el ID de pedido de Gelatocurl --location --request POST 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611/cancel' \--header 'X-API-KEY: tu-clave:tu-secreto'# Cancela usando tu ID de referencia de pedidocurl --location --request POST 'https://api.partner-connect.io/api/{partner-prefix}/YOUR-ORDER-123/cancel' \--header 'X-API-KEY: tu-clave:tu-secreto'

Ejemplo de respuesta

{ "code": 200, "message": "Todo bien"}

Problemas habituales

  1. Pedido ya enviado: Los pedidos que ya han salido de camino no se pueden cancelar.

  2. Pedido no encontrado: Comprueba que el ID del pedido o la referencia sean correctos.

  3. Problemas de autenticación: Asegúrate de que tu clave y secreto de API sean correctos.

Actualizar envío

El endpoint de actualización de envío te permite cambiar el método de envío o actualizar la dirección de entrega de un pedido que aún no ha sido enviado.

Punto de acceso: POST /{updateShipmentURL}/{orderId}

Ejemplo de solicitud

# Actualiza los datos de envíocurl --location --request PUT 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \--header 'Content-Type: application/json' \--header 'X-API-KEY: your-key:your-secret' \--data '{ "shipmentMethodUid": "fed_ex_2_day", "shippingAddress": { "country": "US", "firstName": "Jane", "lastName": "Smith", "addressLine1": "456 Park Ave", "city": "Nueva York", "postCode": "10022", "state": "NY", "email": "[email protected]", "phone": "987-654-3210" }}'# Actualiza solo el método de envíocurl --location --request PUT 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \--header 'Content-Type: application/json' \--header 'X-API-KEY: tu-clave:tu-secreto' \--data '{ "shipmentMethodUid": "fed_ex_2_day"}'

Ejemplo de respuesta

{ "shippingAddress": { "id": "2f85d65b-4814-4b5f-90a2-a7de28250bd1", "orderId": "32884a3e-bd09-42be-8225-c5cea7d24611", "country": "US", "firstName": "Jane", "lastName": "Smith", "addressLine1": "456 Park Ave", "city": "Nueva York", "postCode": "10022", "state": "NY", "email": "[email protected]", "phone": "987-654-3210" }, "shipment": { "shipmentMethodUid": "fed_ex_2_day", "shipmentMethodName": "FedEx 2Day", "fulfillmentCountry": "US", "fulfillmentFacilityId": "db0622e7-d7af-4453-b39f-cdf1b67f3daa", "packageCount": 1, "initialMinDeliveryDate": "15/04/2025", "initialMaxDeliveryDate": "15/04/2025", "serviceType": "normal" }}

Problemas habituales

  1. Pedido ya enviado: No es posible actualizar los datos de envío de los pedidos que ya han salido camino a su destino.

  2. Faltan campos obligatorios: Asegúrate de incluir todos los campos necesarios en la dirección de envío.

  3. Método de envío no válido: Comprueba que el UID del método de envío sea correcto.

  4. Pedido no encontrado: Comprueba que el ID del pedido o la referencia sean correctos.

Ver pedido

El endpoint Get Order te permite obtener información detallada sobre un pedido existente.

Punto final: POST /{getOrderURL}/{orderId}

Ejemplo de solicitud

# Consulta tu pedido con el ID de pedido de Gelatocurl --location --request GET 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \--header 'X-API-KEY: tu-clave:tu-secreto'# Consulta tu pedido usando tu ID de referenciacurl --location --request GET 'https://api.partner-connect.io/api/{partner-prefix}/YOUR-ORDER-123' \--header 'X-API-KEY: your-key:your-secret'

Ejemplo de respuesta

La respuesta incluye información detallada sobre el pedido, como:

  • Detalles del pedido (ID, referencia, estado, fechas y horas)

  • Dirección de envío

  • Artículos pedidos

  • Información del envío

  • Información financiera

Como la respuesta es larga, consulta la documentación de la API para ver la estructura completa de la respuesta.

Cómo aprovechar los datos de respuesta

La respuesta de Obtener pedido te da información valiosa que puedes aprovechar para:

  1. Mostrar estado del pedido: Enseña a tus clientes en qué punto se encuentra su pedido.

  2. Sigue tus envíos: Obtén la información de seguimiento para saber dónde están tus pedidos.

  3. Verifica los detalles del pedido: Asegúrate de que toda la información sea correcta.

  4. Analiza el historial de pedidos: Crea informes y análisis a partir de los datos de tus pedidos.

Problemas habituales

  1. No encontramos el pedido: Comprueba que el ID del pedido o la referencia sean correctos.

  2. Problemas de autenticación: Asegúrate de que tu clave y secreto de API sean correctos.

Buscar pedidos

El endpoint de búsqueda de pedidos te permite obtener una lista de pedidos según los criterios que elijas.

Punto final: POST /{searchOrdersURL}

Ejemplo de solicitud

# Buscar por estado de procesamientocurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: tu-clave:tu-secreto' \--data '{ "fulfillmentStatus": ["enviado", "entregado"]}'# Buscar por rango de fechascurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: tu-clave:tu-secreto' \--data '{ "startDate": "01/01/2025 00:00:00", "endDate": "13/04/2025 23:59:59"}'# Busca por referencia de pedidocurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: your-key:your-secret' \--data '{ "orderReferenceId": "YOUR-ORDER-123"}'# Buscar con paginacióncurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: tu-clave:tu-secreto' \--data '{ "fulfillmentStatus": ["creado", "impreso"], "límite": 50, "offset": 0}'

Ejemplo de respuesta

{ "orders": [ { "id": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "orderReferenceId": "YOUR-ORDER-123", "fulfillmentStatus": "enviado", "financialStatus": "pagado", "currency": "USD", "totalInclVat": "33,45", "orderType": "pedido", "channel": "api", "firstName": "John", "lastName": "Doe", "country": "US", "itemsCount": 1, "createdAt": "10/04/2025 11:05:09", "updatedAt": "10/04/2025 14:05:10", "orderedAt": "10/04/2025 11:05:07", "customerReferenceId": "CUST-456" }, // Más pedidos... ]}

Paginación

El endpoint de búsqueda de pedidos permite paginar para que puedas manejar fácilmente grandes volúmenes de resultados:

# Primera página (50 artículos)curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: tu-clave:tu-secreto' \--data '{ "fulfillmentStatus": ["enviado"], "límite": 50, "offset": 0}'# Segunda página (siguientes 50 elementos)curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: tu-clave:tu-secreto' \--data '{ "fulfillmentStatus": ["enviado"], "limit": 50, "offset": 50}'

Situaciones habituales de búsqueda

  1. Pedidos por estado:

    { "fulfillmentStatus": ["creado", "impreso"] }

  2. Pedidos por rango de fechas:

    { "startDate": "01/04/2025 00:00:00", "endDate": "13/04/2025 23:59:59"}

  3. Pedidos por país:

    { "countries": ["US", "CA"] }

  4. Combinando criterios:

    { "fulfillmentStatus": ["enviado"], "countries": ["US"], "startDate": "01/04/2025 00:00"}

Problemas habituales

  1. Sin resultados: Revisa que tus criterios de búsqueda no sean demasiado estrictos.

  2. Demasiados resultados: Usa la paginación y/o más filtros para afinar tu búsqueda.

  3. Formato no válido: Asegúrate de que las fechas sigan el formato ISO 8601 (AAAA-MM-DDTHH:MM:SS+00:00).

Vincular plantillas a los puntos finales de la API

Al enviar pedidos a través de la API, a menudo tendrás que adaptar los datos de tu formato al formato de GelatoConnect. Las plantillas se encargan de esta transformación, pero debes vincular tu plantilla explícitamente con el endpoint de la API para que se aplique.

Cómo conectar una plantilla con un endpoint de envío de pedidos:

  1. Ve a tu lista de conectores y haz clic en el enlace Editar que está junto al endpoint de envío de pedidos.

  2. En la página de configuración del endpoint, busca la sección Plantilla de endpoint

  3. Elige tu plantilla para enviar el pedido en el menú desplegable

  4. Haz clic en el botón Establecer endpoint que encontrarás en la esquina superior derecha de la página.

  5. Haz clic en Guardar cambios arriba a la derecha para aplicar tu configuración

Después de completar estos pasos, todos los envíos de pedidos que lleguen a este endpoint usarán tu plantilla para transformar los datos antes de procesarlos. Así te aseguras de que el formato de tu sistema se convierta correctamente al formato que espera GelatoConnect.

Sin esta configuración, tu plantilla no se aplicará aunque exista y esté bien diseñada, lo que puede provocar que el pedido no se valide si el formato de tus datos no coincide exactamente con los requisitos de GelatoConnect.

Buenas prácticas para integrar

Al integrar con los endpoints de la API de pedidos, ten en cuenta estas buenas prácticas:

1. Guardar los ID de los pedidos de la tienda

Guarda siempre tanto tu ID de referencia de pedido como el ID de pedido de Gelato que recibes en la respuesta. Así te resultará más fácil seguir y consultar los pedidos en ambos sistemas.

2. Gestiona los errores con elegancia

Implementa una gestión adecuada de errores en cada llamada a la API. Analiza el mensaje de error de la respuesta para ofrecer comentarios útiles a los usuarios e implementa mecanismos de recuperación apropiados.

Para obtener orientación sobre cómo implementar una gestión de errores sólida, consulta la sección "Mejores prácticas para la gestión de errores" en la Documentación de la API de gestión de pedidos.

3. Implementa la idempotencia

Genera identificadores de referencia únicos para cada pedido y utiliza el parámetro preventDuplicate para asegurarte de que, aunque haya problemas de red y tengas que volver a intentarlo, el pedido no se envíe dos veces.

4. Usa notificaciones de Webhook

En lugar de estar comprobando constantemente el estado de los pedidos, configura notificaciones por Webhook para recibir actualizaciones en tiempo real cuando cambie el estado de un pedido.

5. Valida los datos antes de enviarlos

Revisa los datos del pedido por tu parte antes de enviarlos a la API para detectar errores evidentes y mejorar la experiencia de usuario.

6. Implementa la lógica de reintento

Añade lógica de reintento con retroceso exponencial para errores temporales, especialmente para respuestas de límite de velocidad (429).

Para más detalles sobre cómo implementar la espera exponencial y el jitter, consulta la sección "Mejores prácticas para límites de velocidad" en la Documentación de la API de gestión de pedidos o la entrada del blog de AWS sobre espera exponencial y jitter.

7. Optimiza las búsquedas

Sé específico con los criterios de búsqueda para reducir la cantidad de resultados y mejorar el rendimiento.

8. Referencia de datos en caché

Guarda en caché los UIDs de productos y otros datos de referencia para reducir la cantidad de llamadas a la API necesarias.

Conclusión

La API de pedidos de GelatoConnect ofrece un conjunto potente de endpoints para gestionar todo el ciclo de vida de los pedidos. Si aprendes a usar estos endpoints de forma eficaz, podrás conectar tus sistemas con GelatoConnect sin complicaciones.

Para obtener información más detallada, consulta la documentación de la API de gestión de pedidos.

Artículos relacionados
[Recepción de pedidos - GCW] Documentación de la API de gestión de pedidos
[Recepción de pedidos - GCW] Usar productos del cliente vs. ProductUID en pedidos de la API
[Recepción de pedidos - GCW] Crear plantillas para la recepción de pedidos
[Order Intake - GCW] Cómo usar los endpoints de la API de pedidos sin datos de cliente
[Recepción de pedidos - GCW] Conceptos básicos de la API de GelatoConnect
¿Ha quedado contestada tu pregunta?