Introducción
Bienvenido a la documentación de la API de gestión de pedidos. Esta API te permite enviar pedidos, cancelarlos, consultar los detalles, buscar pedidos y actualizar direcciones o métodos de envío dentro del sistema GelatoConnect. La API está organizada según los principios de REST y utiliza los métodos estándar de HTTPS para interactuar con los recursos. Todas las respuestas se devuelven en formato JSON, incluidos los errores.
Autenticación
Todas las llamadas a la API de gestión de pedidos requieren autenticación con una clave y un secreto de API válidos, que debes incluir en la cabecera de cada solicitud. Toda la comunicación debe realizarse a través de HTTPS; las llamadas hechas por HTTP no funcionarán.
Método de autenticación
Añade la cabecera
X-API-KEYa tu solicitudEstablece el valor usando este formato:
key:secret
Ejemplo:
X-API-KEY: your-key:your-secret
Recibirás tu clave y secreto de API específicos cuando configures un conector para tu cliente.
Límites de uso
La API pone límites a la cantidad de solicitudes que puedes hacer en un periodo determinado. Todas las solicitudes cuentan para tu límite personal de 100 solicitudes por segundo.
Por qué existen los límites de uso
Los límites de uso cumplen varias funciones importantes:
Proteger frente al uso indebido o abusivo de la API
Garantizar que todos los usuarios tengan las mismas oportunidades
Evita interrupciones del servicio por exceso de tráfico
Lógica de reintentos para errores por límite de solicitudes
Si superas el límite de solicitudes de la API, recibirás un código de estado 429. Para que tu trabajo no se vea afectado, pon en práctica estas técnicas para volver a intentarlo:
Reintentar: Vuelve a intentar automáticamente las solicitudes que hayan fallado. Añade una lógica de reintento en el código de tu aplicación para todas las llamadas a la API.
Retroceso exponencial: Espera cada vez más tiempo entre intentos cuando recibas errores seguidos. Establece un tiempo máximo de espera y un número máximo de intentos según la operación que estés realizando.
Jitter: Añade un tiempo aleatorio antes de volver a intentar las solicitudes para evitar que todos los clientes lo hagan a la vez. Así se reparte la carga y se evitan choques seguidos.
Para más información sobre las estrategias de reintento, consulta:
Códigos de respuesta
La API de gestión de pedidos utiliza los códigos de respuesta HTTP habituales para indicar si las solicitudes se han realizado correctamente o si ha habido algún problema:
Códigos 2xx: Señalan que todo ha salido bien
Códigos 4xx: Indican errores de estructura o de datos en la solicitud (por ejemplo, falta de parámetros obligatorios o pedido no encontrado)
Códigos 5xx: Indican errores del servidor (esto ocurre muy pocas veces)
Puntos finales de la API
Enviar pedido
Haz tu pedido de una sola vez.
Punto final: POST /{submitOrderUrl}
La URL base y el endpoint específico se te facilitarán durante la configuración del conector.
Formato de solicitud
{ "orderReferenceId": "test", "orderType": "order", "currency": "EUR", "retailCurrency": "GBP", "retailShippingPriceInclVat": 6.99, "shipmentMethodUid": "normal,standard,fed_ex_2_day", "shippingAddress": { "country": "SE", "firstName": "My first name", "lastName": "My last name", "addressLine1": "17", "addressLine2": "Address 1", "city": "City", "postCode": "11111", "state": "", "email": "[email protected]", "phone": "+47222222", "companyName": "MyCompany" }, "items": [ { "itemReferenceId": "test1", "productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", "quantity": 1, "retailPriceInclVat": 19.99, "files": [ { "type": "default", "url": "https://www.example.com/path/to/printfile.pdf" } ] } ]}Ejemplo de solicitud curl (haz clic aquí)
Ejemplo de solicitud curl (haz clic aquí)
curl --location --request POST 'https://api.partner-connect.io/api/your-partner-prefix/order' \--header 'Content-Type: application/json' \--header 'X-API-KEY: tu-clave:tu-secreto' \--data-raw '{ "orderReferenceId": "test", "orderType": "order", "preventDuplicate": true, "currency": "EUR", "retailCurrency": "GBP", "retailShippingPriceInclVat": 6.99, "shipmentMethodUid": "normal,standard,fed_ex_2_day", "shippingAddress": { "country": "SE", "firstName": "My first name", "lastName": "My last name", "addressLine1": "17", "addressLine2": "Address 1", "city": "City", "postCode": "11111", "state": "", "email": "[email protected]", "phone": "+47222222", "companyName": "MyCompany" }, "items": [ { "itemReferenceId": "test1", "productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", "quantity": 1, "retailPriceInclVat": 19.99, "files": [ { "type": "default", "url": "https://www.example.com/path/to/printfile.pdf" } ] } ]}'Parámetros clave de la solicitud
Parámetro | Tipo | Obligatorio | Descripción |
orderReferenceId | cadena | Obligatorio | Tu identificador interno de pedido |
tipo de pedido | cadena | Opcional | Type of order: "order" (default) or "draft" |
moneda | cadena | Obligatorio | Moneda del pedido (código ISO) |
moneda de venta | cadena | Opcional | Moneda utilizada para los precios de venta al público (en pedidos internacionales) |
Precio de envío al por menor con IVA incluido | número | Opcional | Precio de envío sin IVA (aunque el nombre del parámetro diga lo contrario) |
UID del método de envío | cadena | Opcional | Método(s) de envío a utilizar, puedes separarlos con comas |
Dirección de envío | objeto | Obligatorio | Detalles de la dirección de entrega del cliente |
artículos | colección | Obligatorio | Lista de productos para pedir |
evitar duplicados | booleano | Opcional | Si está activado, evita que se creen pedidos duplicados con el mismo orderReferenceId. Si se detecta un duplicado, se mostrará un mensaje de error en lugar de crear un nuevo pedido. |
"packagingInstructions": [ | matriz | Opcional | Lista de objetos de instrucciones de embalaje |
Parámetros del artículo
Parámetro | Tipo | Obligatorio | Descripción |
idReferenciaDelArtículo | cadena | Obligatorio | Tu identificador interno de artículo |
productUid | cadena | Obligatorio* | Identificador de producto de GelatoConnect (*Se requiere o bien productUid o bien productName junto con productVariant) |
nombre del producto | cadena | Obligatorio* | Nombre del producto personalizado del cliente (*Se requiere productUid o productName+productVariant) |
Variante de producto | objeto | Obligatorio* | Detalles de la variante para el producto personalizado del cliente (*Obligatorio cuando se usa productName) |
cantidad | número | Obligatorio | Cantidad de artículos a pedir |
Precio de venta con IVA incluido | número | Opcional | Precio sin IVA (aunque el nombre del parámetro diga lo contrario) |
archivos | colección | Obligatorio | Lista de archivos de impresión para el producto |
Acabado de bordes personalizado | objeto | Opcional | Dimensiones de acabado de bordes personalizado para el producto |
Parámetros del archivo
Parámetro | Tipo | Obligatorio | Descripción |
tipo | cadena | Obligatorio | Tipo de archivo. Consulta la lista de opciones en la tabla de abajo. |
url | cadena | Obligatorio | URL pública para acceder al archivo de impresión |
Tipo de archivo
Parámetro | Descripción |
predeterminado | El diseño se imprime en la zona principal del producto. En el caso de la ropa, es la parte delantera, mientras que en las tarjetas plegadas, son la portada y la contraportada.
Si subes un PDF de varias páginas, el número de páginas debe coincidir con las áreas de impresión, ya que se usará para imprimir en todas ellas. |
frontal | Imprime el archivo en la parte delantera del producto. |
volver | Imprime el archivo en la parte trasera del producto. |
cubierta | El archivo para la portada de un libro |
interior del cuello | Imprime el archivo en la parte interior del cuello de la prenda de ropa. |
cuello exterior | Imprime el archivo en la parte exterior del cuello de la prenda de ropa. |
manga izquierda | Imprime el archivo en la manga izquierda del producto de ropa. |
manga derecha | Imprime el archivo en la manga derecha del producto de ropa. |
dentro | Imprime el archivo en las páginas interiores. |
bordado en el lado izquierdo del pecho | Borda el archivo en el lado izquierdo del pecho de la prenda de ropa. |
bordado en el centro del pecho | Borda el archivo en el centro del pecho de la prenda de ropa. |
bordado grande en el pecho | Borda el archivo en la parte delantera del producto de ropa. |
bordado en la manga izquierda | Borda el archivo en la manga izquierda del producto de ropa. |
bordado en la manga derecha | Borda el archivo en la manga derecha del producto de ropa. |
bordado en la muñeca izquierda | Borda el archivo en la muñeca izquierda del producto de ropa. |
bordado en la muñeca derecha | Borda el archivo en la muñeca derecha del producto de ropa. |
Tipos de archivo flexibles para productos con Workflow builder
Para los productos que tienen habilitado el Workflow builder, puedes usar cualquier nombre personalizado de tipo de archivo en el campo type del array files. Esta función simplifica las integraciones con la API, ya que elimina la necesidad de asignar archivos a tipos predefinidos.
Puntos clave:
Puedes nombrar los tipos de archivo como prefieras, por ejemplo:
default_1,default_2,cover_front,inside_page, etc.Caracteres permitidos: letras (A–Z, a–z), números (0–9), guiones bajos (_), puntos (.) y guiones (-)
Longitud máxima: 100 caracteres
La unicidad del tipo de archivo sigue aplicando: cada valor de
typedebe ser único dentro del mismo arrayfiles.
Ejemplo de uso:
{ "items": [ { "productUid": "your-workflow-enabled-product-uid", "quantity": 1, "files": [ { "type": "default_1", "url": "https://your-file-url.com/file1.pdf" }, { "type": "default_2", "url": "https://your-file-url.com/file2.pdf" }, { "type": "custom_cover", "url": "https://your-file-url.com/cover.pdf" } ] } ]}
Parámetros personalizados de Acabado de bordes
Parámetro | Tipo | Obligatorio | Descripción |
anchoMm | número | Obligatorio | Ancho de acabado de bordes en milímetros (*Obligatorio cuando se utiliza personalizadoTrim) |
alturaMm | número | Obligatorio | Altura del acabado de bordes en milímetros (*Obligatorio cuando se utiliza personalizadoAcabado de bordes) |
Parámetros de instrucciones de embalaje
Parámetro | Tipo | Obligatorio | Descripción |
"packageItems": [ | colección | Obligatorio | Artículos que incluir en este paquete |
orderItemReferenceId | cadena | Obligatorio | Referencia al artículo del pedido (debe coincidir con itemReferenceId) |
cantidad | número | Obligatorio | Cantidad del artículo en este paquete |
"packingSlip": { | objeto | Opcional | Configuración del albarán de envío |
fileUrl | cadena | Obligatorio | URL del archivo PDF del albarán de envío |
GelatoConnect descargará y guardará tu albarán de embalaje en PDF para que siempre esté disponible durante el proceso de empaquetado, incluso si la URL original caduca.
Ejemplo de uso:
{ "orderReferenceId": "ORDER-12345", "orderType": "order", "currency": "USD", "shippingAddress": {...}, "items": [...], "packagingInstructions": [ { "packageItems": [ { "orderItemReferenceId": "ITEM-001", "quantity": 1 } ], "packingSlip": { "fileUrl": "https://example.com/slip.pdf" } } ]}
Migración desde albaranes basados en metadatos
Si actualmente usas metadatos para enviar albaranes, puedes utilizar la siguiente plantilla para extraer las URLs de los albaranes desde los metadatos y convertirlas al formato packagingInstructions, asegurando el almacenamiento permanente de archivos por parte de GelatoConnect.
{%- set payload = context.payload -%}{#-- Extraer la URL del albarán de embalaje y filtrar 'tenant-packing-slip' --#}{%- set ns = namespace(packing_slip_url=None) -%}{%- set filtered_metadata = [] -%}{%- for m in payload.metadata or [] %} {%- if m.key == "tenant-packing-slip" %} {%- set ns.packing_slip_url = m.value %} {%- else %} {%- set filtered_metadata = filtered_metadata + [m] %} {%- endif %} {%- endfor -%}{#-- JSON actualizado --#}{ {%- for key, value in payload.items() %} {%- if key != "metadata" %} "##{{ key }}": ##{{ value | tojson }}, {%- endif %} {%- endfor %} "metadata": ##{{ filtered_metadata | tojson }},instrucciones de embalaje {artículos del paquete {%- for item in payload.get("items") or [] -%} { "orderItemReferenceId": ##{{ item.itemReferenceId|js }}, "quantity": ##{{ item.quantity }} }{% if not loop.last %},{% endif %}{%- endfor %} ],albarán de embalaje "fileUrl": "##{{ ns.packing_slip_url }}" } } ]}
Parámetros de dirección de envío
Parámetro | Tipo | Obligatorio | Descripción |
país | cadena | Obligatorio | Código de país de dos letras (ISO 3166-1 alfa-2) |
nombre | cadena | Obligatorio | Nombre de pila del destinatario |
Apellido | cadena | Obligatorio | Apellido del destinatario |
dirección (línea 1) | cadena | Obligatorio | Primera línea de la dirección |
dirección (línea 2) | cadena | Opcional | Segunda línea de la dirección |
ciudad | cadena | Obligatorio | Nombre de la ciudad |
código postal | cadena | Obligatorio | Código postal |
estado | cadena | Obligatorio | Código de estado o provincia (*Obligatorio para direcciones de EE. UU., CA y AU) |
correo electrónico | cadena | Obligatorio* | Correo electrónico del destinatario |
teléfono | cadena | Obligatorio | Número de teléfono del destinatario con código de país |
companyName | cadena | Opcional | Nombre de la empresa (si corresponde) |
esNegocio | booleano | Opcional | Si la dirección es para un negocio |
identificación fiscal federal | cadena | Opcional | Identificación fiscal federal para direcciones comerciales |
identificación fiscal estatal | cadena | Opcional | Identificación fiscal estatal para direcciones comerciales |
estado de registro | cadena | Opcional | Indica en qué comunidad autónoma está registrada tu empresa |
Notas especiales para pedidos internacionales
Para pedidos internacionales, indica el precio de venta del producto y el precio de envío al por menor de la siguiente manera:
retailCurrency: Moneda en la que se muestran los precios de venta al públicoretailShippingPriceInclVat: Precio de envío sin IVA (ignora el nombre del parámetro)items[i].retailPriceInclVat: Precio total del producto sin IVA (ignora el nombre del parámetro)
Elegir un producto
La API para enviar pedidos puede recibir la información del producto de dos formas:
Usando
productUid:
"productUid": "frame_product_frs_10x10-inch_frc_oak_frm_wood_frp_w13xt22-mm_gt_plexiglass"
Usando
productNameyproductVariant:
"productName": "Framed Poster","productVariant": { "FrameColour": "Black", "PaperSize": "A3"}No utilices ambos métodos en la misma solicitud de pedido.
Elegir un método de envío
El campo shipmentMethodUid puede aceptar:
Identificadores específicos de métodos de envío (por ejemplo,
fed_ex_2_day)Nombres de empresas de mensajería (por ejemplo,
DHL)Niveles de opciones de envío (por ejemplo,
Express)
Puedes indicar varios métodos de envío separados por comas, y el sistema elegirá la opción más económica.
Formato de respuesta
{ "id": "32884a3e-bd09-42be-8225-c5cea7d24611", "orderReferenceId": "test", "createdAt": "2024-07-17T10:23:28+00:00"}
Uso de metadatos en todo GelatoConnect
La información adicional que se incluye tanto a nivel de pedido como de artículo en las solicitudes de pedido puede ser utilizada por varias herramientas dentro de GelatoConnect y también se devuelve en las notificaciones. Esto resulta especialmente útil para quienes necesitan mantener la continuidad de los datos entre sus sistemas.
Metadatos del pedido:
Los metadatos a nivel de pedido se aplican a todo el pedido y se definen en el nivel superior de la solicitud.
{ "orderReferenceId": "ORD-12345", "orderType": "order", "currency": "USD", "metadata": [ { "key": "campaign", "value": "summer_promo" }, { "key": "source", "value": "web" } ], "shippingAddress": {...}, "items": [...]}
Metadatos a nivel de artículo:
Los metadatos a nivel de artículo se aplican a elementos concretos y se definen dentro de cada uno en la lista de artículos.
{ "orderReferenceId": "ORD-12345", "orderType": "order", "currency": "USD", "shippingAddress": {...}, "items": [ { "itemReferenceId": "ITEM-001", "productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", "quantity": 1, "metadata": [ { "key": "position", "value": "A1" }, { "key": "machine", "value": "Printer3" } ], "files": [...] } ]}
Metadatos a nivel de archivo:
Los metadatos a nivel de archivo se aplican a archivos específicos y se definen dentro de cada archivo en el array files. En el siguiente ejemplo, se utilizan para definir el texto alternativo de la imagen embroideryText asociada al archivo.
{ "orderReferenceId": "ORD-12345", "orderType": "order", "currency": "USD", "shippingAddress": {...}, "items": [ { "itemReferenceId": "ITEM-001", "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://www.example.com/path/to/printfile.pdf", "metadata": [ { "key": "embroideryText", "value": "James" } ] } ] } ]}
Cancelar orden
Detén y cancela la producción y el envío de un pedido. Solo puedes hacerlo hasta que el estado del pedido cambie a "enviado".
Punto final: POST /{orderCancelUrl}
Este endpoint puede aceptar tanto el ID de pedido (que se proporciona en la respuesta al enviar el pedido) como el ID de referencia de pedido (tu propio identificador interno de pedido).
Usando el ID de pedido
POST /{orderCancelUrl}/32884a3e-bd09-42be-8225-c5cea7d24611/cancelUsar el ID de referencia del pedido
POST /{orderCancelUrl}/test/cancelFormato de respuesta
{ "code": 200, "message": "OK"}
Actualizar envío
Puedes cambiar el método de envío o actualizar la dirección de entrega hasta que el pedido pase al estado "enviado".
Endpoint: PUT /{updateShipmentURL}
Este punto de acceso puede aceptar tanto el ID de pedido como la referencia del pedido.
Formato de solicitud
{ "shipmentMethodUid": "fed_ex_2_day", "shippingAddress": { "country": "GB", "firstName": "Alexis", "lastName": "Apollo", "addressLine1": "Longusta str. 4", "addressLine2": "app. 144", "city": "myCity", "postCode": "111111", "state": "myState", "email": "[email protected]", "phone": "+34 111444111", "companyName": "Company_example", "isBusiness": false, "federalTaxId": "", "stateTaxId": "", "registrationState": "" }}Puedes actualizar el método de envío, la dirección de envío o ambos. Debes incluir al menos uno de estos campos en la solicitud.
Parámetros de solicitud
Parámetro | Tipo | Obligatorio | Descripción |
shipmentMethodUid | cadena | Opcional* | Nuevo método de envío (*Debes proporcionar al menos shipmentMethodUid o shippingAddress) |
Dirección de envío | objeto | Opcional* | Nuevos detalles de la dirección de envío (*Debes proporcionar al menos shipmentMethodUid o shippingAddress) |
Formato de respuesta
{ "shippingAddress": { "id": "2f85d65b-4814-4b5f-90a2-a7de28250bd1", "orderId": "148c5a06-35c9-40d3-8ef7-e85eb2da317d", "country": "GB", "firstName": "Test Order", "lastName": "4", "companyName": "company_example", "addressLine1": "address example 1", "addressLine2": "address example 2", "city": "myCity", "postCode": "111111", "state": "", "email": "[email protected]", "phone": "+34 111444222", "isBusiness": false, "federalTaxId": "", "stateTaxId": "", "registrationState": "" }, "shipment": { "shipmentMethodUid": "fed_ex_2_day", "shipmentMethodName": "DHL Global Parcel", "fulfillmentCountry": "DE", "fulfillmentFacilityId": "db0622e7-d7af-4453-b39f-cdf1b67f3daa", "packageCount": 1, "initialMinDeliveryDate": "2024-11-16", "initialMaxDeliveryDate": "2024-11-16", "serviceType": "normal" }}
Haz tu pedido
Consulta la información de un pedido existente.
Punto final: GET /{getOrderURL}/{order_id}
Puedes usar tanto el ID de pedido de Gelato como tu referencia de pedido.
Formato de respuesta
La respuesta incluirá información detallada sobre el pedido, como:
Detalles del pedido (ID, referencia, estado, etc.)
"shippingAddress": {
Artículos pedidos con detalles del producto
Información del envío (método, seguimiento, etc.)
Información financiera
Ejemplo de respuesta (haz clic aquí)
Ejemplo de respuesta (haz clic aquí)
{ "id": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "orderReferenceId": "healthcheck_middleware_order_create_2024-12-02-11:05:06_1991", "customerReferenceId": "sandbox-customer", "fulfillmentStatus": "failed", "financialStatus": "canceled", "currency": "USD",Dirección de envío "id": "29de7336-95a9-48d2-aa85-d7d40e6ea65c", "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "country": "GB", "firstName": "TEST", "lastName": "PRINT", "companyName": "", "addressLine1": "19 June Lewis Way", "addressLine2": "", "city": "Fairford", "postCode": "GL7 4GH", "state": "", "email": "[email protected]", "phone": "1111111119", "isBusiness": false, "federalTaxId": null, "stateTaxId": null, "registrationState": null }, "items": [ { "id": "e9f6de69-670b-47c5-a953-3710cac053a1", "itemReferenceId": "1111111111", "productUid": "large-posters_pf_500x700-mm_pt_170-gsm-coated-silk_cl_4-0_ver", "storeProductVariantId": null, "storeProductId": null, "files": [ { "id": null, "type": "default", "url": "https://URLexample.com/order", "threadColors": [], "isVisible": false, "fitMethod": null, "fillMethod": null, "mimeType": "application/pdf", "metadata": [] } ], "processedFileUrl": null, "quantity": 1, "options": [], "category": "Posters", "productCategoryUid": "wall-art", "productTypeUid": "poster", "productNameUid": "classic-semi-glossy-poster", "productName": "Classic Semi-Glossy Poster", "fulfillmentStatus": "failed", "pageCount": null, "printJobs": [], "eventLog": [], "previews": [ { "type": "preview_default", "url": "https://URLexample.com/order" }, { "type": "preview_thumbnail", "url": "https://URLexample.com/order" }, { "type": "preview_flat", "url": "https://URLexample.com/order" } ], "designId": null, "productFileMimeType": "application/pdf", "finalProductUid": "large-posters_pf_500x700-mm_pt_170-gsm-coated-silk_cl_4-0_ver", "metadata": [ { "key": "unitWeight", "value": "800" }, { "key": "unitPrice", "value": "" },} "key": "supplierPartAuxiliaryId", "value": ""{} "retailPriceInclVat": null, "attributes": [ ] "name": "size", "title": "Size", "value": "500x700-mm", "formattedValue": "50 x 70 cm" } { "name": "orientation", "title": "Orientation", "value": "ver", "formattedValue": "Vertical (portrait) orientation"{} "itemReferenceName": null, "isIgnored": false, "price": 0, "customTrim": null, "fileUrl": "https://URLexample.com/order", "dpi": 0, "appServices": [], "filesSize": 3.8, "productVariant": [] ]{ "shipment": { "id": "33163694-1437-407f-99ef-57a0d579114f", "orderProductId": null, "shippingAddressId": "29de7336-95a9-48d2-aa85-d7d40e6ea65c", "promiseUid": "d_dfae1a1c58d230dbe73690a2", "packageCount": 1, "shipmentMethodUid": "dhl_global_parcel", "shipmentMethodName": "DHL Global Parcel", "isCheapest": true, "minDeliveryDays": 1, "maxDeliveryDays": 1, "minDeliveryDate": "2024-12-03", "maxDeliveryDate": "2024-12-03", "totalWeight": 139, "price": 0, "status": null, "packages": [], "fulfillmentCountry": "DE", "fulfillmentFacilityId": "db0622e7-d7af-4453-b39f-cdf1b67f3daa", "retailShippingPriceInclVat": null, "initialMinDeliveryDate": "2024-12-03", "initialMaxDeliveryDate": "2024-12-03", "serviceType": "normal", "speedType": ""} "receipts": [ }, "id": "f9f6e29a-de14-4755-bafe-7cf0cdf6e3fc", "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "type": "contract", "currency": "USD", "items": [ }, "id": "a99224b0-6e96-430e-84dd-82995f274840", "receiptId": "f9f6e29a-de14-4755-bafe-7cf0cdf6e3fc", "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "type": "product", "referenceId": "e9f6de69-670b-47c5-a953-3710cac053a1", "title": "1x large-posters_pf_500x700-mm_pt_170-gsm-coated-silk_cl_4-0_ver", "currency": "USD", "priceBase": 0, "amount": 1, "priceInitial": 0, "discount": 0, "price": 0, "vat": 0, "priceInclVat": 0, "pricePlanId": null, "createdAt": "2024-12-02T11:05:09+00:00", "updatedAt": "2024-12-02T11:05:09+00:00" ], } "id": "1d2936c3-eb3f-456d-94b9-b2be8c4eec50", "receiptId": "f9f6e29a-de14-4755-bafe-7cf0cdf6e3fc", "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "type": "shipment", "referenceId": "33163694-1437-407f-99ef-57a0d579114f", "title": "Delivery using DHL Global Parcel", "currency": "USD", "priceBase": 0, "amount": 1, "priceInitial": 0, "discount": 0, "price": 0, "vat": 0, "priceInclVat": 0, "pricePlanId": null, "createdAt": "2024-12-02T11:05:09+00:00", "updatedAt": "2024-12-02T11:05:09+00:00" { }, "id": "b7d6899c-3a00-46eb-8d14-e9b3e2bb3e4e", "receiptId": "f9f6e29a-de14-4755-bafe-7cf0cdf6e3fc", "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "type": "packaging", "referenceId": "33163694-1437-407f-99ef-57a0d579114f", "title": "Packaging", "currency": "USD", "priceBase": 0, "amount": 1, "priceInitial": 0, "discount": 0, "price": 0, "vat": 0, "priceInclVat": 0, "pricePlanId": null, "createdAt": "2024-12-02T11:05:09+00:00", "updatedAt": "2024-12-02T11:05:09+00:00" { ], "createdAt": "2024-12-02T11:05:09+00:00", "updatedAt": "2024-12-02T11:05:10+00:00", "receiptNumber": "005-0014597660", "billingEntity": { "id": 218720, "companyName": "Gelato", "companyNumber": "", "companyVatNumber": "", "companyVatNumbers": [], "countryIsoCode": "DE", "country": "DE", "recipientName": "Alex Shiltcev", "addressLine1": "Something 1", "addressLine2": "", "city": "Berlin", "postCode": "10113", "stateCode": "", "state": "", "email": "[email protected]", "phone": "", "currencyIsoCode": "EUR", "currency": "EUR", "status": 1, "iossNumber": null, "invoiceType": null } "billingTag": "gelato-norway-de", "transactionType": "purchase", "productsPriceInitial": 0, "productsPriceDiscount": 0, "productsPrice": 0, "productsPriceVat": 0, "productsPriceInclVat": 0, "digitizationPriceInitial": 0, "digitizationPriceDiscount": 0, "digitizationPrice": 0, "digitizationPriceVat": 0, "digitizationPriceInclVat": 0, "shippingPriceInitial": 0, "shippingPriceDiscount": 0, "shippingPrice": 0, "shippingPriceVat": 0, "shippingPriceInclVat": 0, "packagingPriceInitial": 0, "packagingPriceDiscount": 0, "packagingPrice": 0, "packagingPriceVat": 0, "packagingPriceInclVat": 0, "discount": 0, "discountVat": 0, "discountInclVat": 0, "totalInitial": 0, "total": 0, "totalVat": 0, "totalInclVat": 0, "isCalculated": true }, ], "createdAt": "2024-12-02T11:05:09+00:00", "refusalReason": "Order is failing as it’s going to be cross border and product retail prices are missing.", "channel": "api", "storeId": null, "orderedByUserId": null, "orderType": "order", "metadata": [ } "key": "tenant-customer-id", "value": "02be1010-5f59-4504-a669-5cf88e84f627" { }, "key": "tenant-customer-uid", "value": "sandbox-customer" { }, "billingEntity": { "id": 218720, "companyName": "Gelato", "companyNumber": "", "companyVatNumber": "", "companyVatNumbers": [], "countryIsoCode": "DE", "country": "DE", "recipientName": "Alex Shiltcev", "addressLine1": "Something 1", "addressLine2": "", "city": "Berlin", "postCode": "10113", "stateCode": "", "state": "", "email": "[email protected]", "phone": "", "currencyIsoCode": "EUR", "currency": "EUR", "status": 1, "iossNumber": null, "invoiceType": null { "retailCurrency": null, "paymentMethodType": null, "paymentMethodId": null, "prepaymentTransactionId": null, "orderedAt": "2024-12-02T11:05:07+00:00", "updatedAt": "2024-12-02T11:05:10+00:00", "connectedOrderIds": [], "discounts": [], "returnAddress": { "id": "6eeb262a-92ce-45a4-9cd6-128473a0acb0", "country": null, "addressLine1": null, "addressLine2": null, "city": null, "postCode": null, "state": null, "email": null, "phone": null, "companyName": "Gelato Connect Sandbox" { "iossNumber": null, "refusalReasonCode": "missing_retail_prices", "refusalReasonDetails": null, "comment": "Order is failing as it’s going to be cross border and product retail prices are missing.", "digitizationId": null, "appServices": [], "shipmentMethodUid": "normal" },
Buscar pedidos
Obtén una lista de pedidos según los criterios que elijas.
Punto final: POST /{searchOrdersURL}
Formato de solicitud
], "fulfillmentStatus": [ "canceled", "delivered" } ],
Parámetros de la solicitud
Parámetro | Tipo | Obligatorio | Descripción |
estado de cumplimiento | string[] | Opcional | Filtra por estado de procesamiento del pedido |
estado financiero | string[] | Opcional | Filtra por estado financiero del pedido |
ID de referencia de pedido | cadena | Opcional | Filtra por tu ID de pedido interno |
referenciasDePedido | string[] | Opcional | Filtra por varios ID de pedido internos |
fecha de inicio | cadena | Opcional | Filtra por pedidos creados después de esta fecha (formato ISO 8601) |
Fecha de finalización | string[] | Opcional | Filtra por pedidos creados antes de esta fecha (formato ISO 8601) |
países | cadena | Opcional | Filtra por códigos de país de envío |
límite | número | Opcional | Número máximo de resultados a mostrar (por defecto: 50, máximo: 100) |
desfase | número | Opcional | Número de resultados que se omiten para la paginación (por defecto: 0) |
Formato de respuesta
} "orders": [ { "id": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "orderReferenceId": "orderref_123", "fulfillmentStatus": "failed", "financialStatus": "canceled", "currency": "USD", "totalInclVat": "0.00", "orderType": "order", "channel": "api", "storeId": null, "connectedOrderIds": [], "firstName": "TEST", "lastName": "PRINT", "country": "GB", "itemsCount": 1, "createdAt": "2024-12-02T11:05:09+00:00", "updatedAt": "2024-12-02T11:05:10+00:00", "orderedAt": "2024-12-02T11:05:07+00:00", "refusalReasonCode": "missing_retail_prices", "appServices": [], "customerReferenceId": "custref_456" }, { ],
Gestión de errores
Cuando una solicitud a la API falla, la respuesta incluirá un código de error y un mensaje descriptivo para ayudarte a identificar y solucionar el problema. Algunos de los errores más habituales son:
400 Solicitud incorrecta: Parámetros no válidos o faltantes
401 No autorizado: Las credenciales de autenticación no son válidas o faltan
404 No encontrado: El recurso que buscas no existe
429 Demasiadas solicitudes: Has superado el límite permitido
Error 500 del servidor: Ha ocurrido un error inesperado en el servidor
Ejemplo de respuesta de error:
} "code": 400, "message": "Invalid shipping address: Email is not a valid format" {Para una integración sólida, implementa una gestión adecuada de errores y lógica de reintentos, tal como se explica en la sección de límites de velocidad.
¿Te echamos una mano?
Si tienes algún problema o pregunta sobre la API, ponte en contacto con nuestro equipo de asistencia en [email protected].
Incluye la siguiente información en tu solicitud de soporte:
El punto de acceso API específico que estás utilizando
Tu solicitud (con información confidencial oculta)
La respuesta de error que recibiste
Cualquier fecha y hora relevante
Esto ayudará a nuestro equipo a resolver tu problema de forma más rápida y eficaz.