Introdução
Bem-vindo à documentação da API de Gerenciamento de Pedidos. Esta API permite que você envie pedidos, cancele pedidos, recupere detalhes de pedidos, pesquise pedidos e atualize endereços ou métodos de envio dentro do sistema GelatoConnect. A API é organizada em torno dos princípios REST e usa métodos HTTPS padrão para interagir com recursos. Todas as respostas são retornadas em formato JSON, incluindo erros.
Autenticação
Todas as chamadas da API de Gerenciamento de Pedidos exigem autenticação com uma chave e um segredo de API válidos, fornecidos no cabeçalho de cada chamada. Toda a comunicação deve ser feita por meio de HTTPS; chamadas feitas por HTTP simples não serão aceitas.
Método de autenticação
Adicione o cabeçalho
X-API-KEYà sua solicitaçãoDefina o valor usando o formato:
key:secret
Exemplo:
X-API-KEY: your-key:your-secret
Sua chave de API específica e senha serão fornecidas ao configurar um conector para seu cliente.
Limites de taxa
A API impõe limites na quantidade de solicitações que um usuário ou cliente pode fazer em um determinado período. Todas as solicitações contam para o seu limite pessoal de 100 solicitações por segundo.
Por que existem limites de uso
Os limites de taxa cumprem vários propósitos importantes:
Protegendo contra abuso ou uso indevido da API
Garantindo acesso justo para todos os usuários
Evitando interrupções de serviço causadas por excesso de tráfego
Lógica de nova tentativa para erros de limite de taxa
Se você exceder o limite de taxa da API, receberá um código de status 429. Para minimizar o impacto em suas cargas de trabalho, implemente estas técnicas de nova tentativa:
Repetir: Tente novamente automaticamente as solicitações com falha. Implemente a lógica de repetição no código do seu aplicativo para todas as chamadas de API.
Recuo Exponencial: Use esperas progressivamente mais longas entre as novas tentativas para respostas de erro consecutivas. Implemente um intervalo máximo de atraso e um número máximo de tentativas com base na operação que está sendo realizada.
Jitter: Adicione um tempo aleatório antes de tentar novamente as solicitações para evitar que todos os clientes tentem ao mesmo tempo. Isso ajuda a distribuir a carga e evita colisões sucessivas.
Para mais informações sobre estratégias de nova tentativa, consulte:
Códigos de resposta
A API de Gerenciamento de Pedidos utiliza códigos de resposta HTTP convencionais para indicar o sucesso ou a falha das solicitações:
Códigos 2xx: Indicam sucesso
Códigos 4xx: Indicam erros estruturais ou de dados na solicitação (por exemplo, parâmetros obrigatórios ausentes, pedido não encontrado)
Códigos 5xx: Indicam erros no servidor (isso acontece raramente)
Endpoints da API
Enviar pedido
Envie um pedido em uma única solicitação.
Endpoint: POST /{submitOrderUrl}
O URL base e o endpoint específico serão fornecidos durante a configuração do conector.
Formato de solicitação
{ "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" } ] } ]}Exemplo de solicitação curl (clique aqui)
Exemplo de solicitação curl (clique aqui)
curl --location --request POST 'https://api.partner-connect.io/api/your-partner-prefix/order' \--header 'Content-Type: application/json' \--header "X-API-KEY: seu-key:seu-secret" \--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" } ] } ]}'Principais parâmetros da solicitação
Parameter | Tipo | Obrigatório | Descrição |
orderReferenceId | string | Obrigatório | Seu identificador interno de pedido |
tipo de pedido | string | Opcional | Type of order: "order" (default) or "draft" |
moeda | string | Obrigatório | Moeda do pedido (código ISO) |
moeda de varejo | string | Opcional | Moeda utilizada para preços de varejo (em pedidos internacionais) |
Preço de envio para varejo com IVA incluso | número | Opcional | Preço de envio excluindo IVA (apesar do nome do parâmetro) |
shipmentMethodUid | string | Opcional | Método(s) de envio a ser(em) utilizado(s), pode(m) ser separado(s) por vírgula |
endereço de entrega | objeto | Obrigatório | Detalhes do endereço de entrega do cliente |
Itens | array | Obrigatório | Lista de produtos para pedir |
evitar duplicidade | booleano | Opcional | Quando definido como verdadeiro, impede a criação de pedidos duplicados com o mesmo orderReferenceId. Se um duplicado for detectado, uma mensagem de erro será exibida em vez de criar um novo pedido. |
"packagingInstructions": [ | array | Opcional | Matriz de objetos de instruções de embalagem |
Parâmetros do item
Parameter | Tipo | Obrigatório | Descrição |
itemReferenceId | string | Obrigatório | Seu identificador interno do item |
productUid | string | Obrigatório* | Identificador de produto GelatoConnect (*É necessário fornecer productUid OU productName+productVariant) |
nome do produto | string | Obrigatório* | Nome do produto do cliente (*É necessário informar o productUid OU productName+productVariant) |
variante do produto | objeto | Obrigatório* | Detalhes da variante para o produto do cliente (*Obrigatório ao usar productName) |
quantidade | número | Obrigatório | Quantidade de itens para pedir |
preço de varejo com IVA incluso | número | Opcional | Preço sem IVA (apesar do nome do parâmetro) |
arquivos | array | Obrigatório | Lista de arquivos para impressão do produto |
bordaPersonalizada | objeto | Opcional | Dimensões de borda personalizadas para o produto |
Parâmetros do Arquivo
Parameter | Tipo | Obrigatório | Descrição |
tipo | string | Obrigatório | Tipo de arquivo. Encontre uma lista de opções na tabela abaixo. |
url | string | Obrigatório | URL pública de acesso ao arquivo para impressão |
Tipo de arquivo
Parameter | Descrição |
padrão | A estampa é aplicada na área principal do produto. Para vestuário, é a parte da frente; para cartões dobrados, são a capa e o verso.
Se você fornecer um PDF com várias páginas, o número de páginas deve corresponder às áreas de impressão, pois será usado para imprimir em todas elas. |
frente | Imprima o arquivo para impressão na parte da frente do produto. |
voltar | Imprima o arquivo na parte de trás do produto. |
capa | O arquivo para a capa de um livro |
interior da gola | Imprima o arquivo na parte interna da gola do produto de vestuário. |
gola externa | Imprima o arquivo na parte externa da gola do produto de vestuário. |
manga esquerda | Imprima o arquivo para impressão na manga esquerda do produto de vestuário. |
manga direita | Imprima o arquivo para impressão na manga direita do produto de vestuário. |
dentro | Imprima o arquivo nas páginas internas. |
bordado-lado-esquerdo-do-peito | Borde o arquivo no lado esquerdo do peito do produto de vestuário. |
bordado-central-no-peito | Borde o arquivo no centro do peito do produto de vestuário. |
bordado grande no peito | Borde o arquivo na frente do produto de vestuário. |
bordado-manga-esquerda | Borde o arquivo para impressão na manga esquerda do produto de vestuário. |
bordado-manga-direita | Borde o arquivo na manga direita do produto de vestuário. |
bordado-pulso-esquerdo | Borde o arquivo no punho esquerdo do produto de Vestuário. |
bordado no punho direito | Borde o arquivo para impressão no punho direito do produto de vestuário. |
Tipos de arquivos flexíveis para produtos habilitados para fluxo de trabalho
Para produtos habilitados para o Workflow builder, você pode usar quaisquer nomes de tipos de arquivo personalizados no campo type do array files. Esse recurso simplifica as integrações de API, eliminando a necessidade de mapear arquivos para tipos predefinidos.
Pontos principais:
Você pode nomear os tipos de arquivo livremente, como
default_1,default_2,cover_front,inside_page, etc.Caracteres permitidos: letras (A–Z, a–z), números (0–9), sublinhados (_), pontos (.) e hífens (-)
Comprimento máximo: 100 caracteres
A exclusividade do tipo de arquivo ainda se aplica - cada valor
typedeve ser único dentro do mesmo arrayfiles
Exemplo 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 de Borda Personalizados
Parameter | Tipo | Obrigatório | Descrição |
larguraMm | número | Obrigatório | Largura da borda em milímetros (*Obrigatório quando usar personalizado) |
alturaMm | número | Obrigatório | Altura da borda em milímetros (*Obrigatório quando usar personalizado) |
Parâmetros de Instruções de Embalagem
Parameter | Tipo | Obrigatório | Descrição |
"packageItems": [ | array | Obrigatório | Itens a incluir neste pacote |
orderItemReferenceId | string | Obrigatório | Referência ao item do pedido (deve corresponder ao itemReferenceId) |
quantidade | número | Obrigatório | Quantidade do item neste pacote |
"packingSlip": { | objeto | Opcional | Configuração da nota de embalagem |
URL do arquivo | string | Obrigatório | URL para o arquivo PDF da nota de embalagem |
O GelatoConnect fará o download e armazenará o PDF da sua guia de remessa para garantir que ele permaneça acessível durante o processo de embalagem, mesmo se a URL original expirar.
Exemplo 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" } } ]}
Migrando de notas de embalagem baseadas em metadados
Para clientes que atualmente usam metadados para enviar notas de embalagem, você pode usar o modelo abaixo para extrair URLs de notas de embalagem dos metadados e convertê-las para o formato packagingInstructions, garantindo o armazenamento persistente de arquivos pelo GelatoConnect.
{%- set payload = context.payload -%}{#-- Extract packing slip URL and filter out '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 -%}{#-- Saída JSON atualizada --#}{ {%- for key, value in payload.items() %} {%- if key != "metadata" %} "##{{ key }}": ##{{ value | tojson }}, {%- endif %} {%- endfor %} "metadata": ##{{ filtered_metadata | tojson }},instruções de embalagem {itens do pacote {%- for item in payload.get("items") or [] -%} { "orderItemReferenceId": ##{{ item.itemReferenceId|js }}, "quantity": ##{{ item.quantity }} }{% if not loop.last %},{% endif %}{%- endfor %} ],nota de embalagem "fileUrl": "##{{ ns.packing_slip_url }}" } } ]}
Parâmetros do endereço de entrega
Parameter | Tipo | Obrigatório | Descrição |
país | string | Obrigatório | Código de país de duas letras (ISO 3166-1 alfa-2) |
nome | string | Obrigatório | Nome do destinatário |
Sobrenome | string | Obrigatório | Sobrenome do destinatário |
endereço linha 1 | string | Obrigatório | Primeira linha do endereço |
complemento do endereço | string | Opcional | Segunda linha do endereço |
cidade | string | Obrigatório | Nome da cidade |
código postal | string | Obrigatório | CEP ou código postal |
estado | string | Obrigatório | Código do estado ou província (*Obrigatório para endereços nos EUA, Canadá e Austrália) |
string | Obrigatório* | Endereço de e-mail do destinatário | |
telefone | string | Obrigatório | Número de telefone do destinatário com código do país |
companyName | string | Opcional | Nome da empresa (se aplicável) |
isBusiness | booleano | Opcional | Se o endereço é comercial |
CNPJ | string | Opcional | CNPJ para endereços comerciais |
inscrição estadual | string | Opcional | Inscrição estadual para endereços comerciais |
estadoDeRegistro | string | Opcional | Estado onde o negócio está registrado |
Observações especiais para pedidos internacionais
Para pedidos internacionais, informe o preço de varejo do produto e o preço de envio de varejo da seguinte forma:
retailCurrency: Moeda na qual os preços de varejo são fornecidosretailShippingPriceInclVat: Preço do frete sem o IVA (ignore o nome do parâmetro)items[i].retailPriceInclVat: Preço total do produto sem incluir o IVA (ignore o nome do parâmetro)
Selecionando um Produto
A API de envio de pedidos pode receber informações sobre o produto de duas formas:
Usando
productUid:
"productUid": "frame_product_frs_10x10-inch_frc_oak_frm_wood_frp_w13xt22-mm_gt_plexiglass"
Usando
productNameeproductVariant:
"productName": "Framed Poster","productVariant": { "FrameColour": "Black", "PaperSize": "A3"}Não use ambos os métodos no mesmo pedido.
Selecionando um método de envio
O campo shipmentMethodUid pode aceitar:
Identificadores específicos de métodos de envio (por exemplo,
fed_ex_2_day)Nomes de transportadoras (por exemplo,
DHL)Níveis de opção de envio (por exemplo,
Expresso)
Vários métodos de envio podem ser informados como uma lista separada por vírgulas, e o sistema usará a opção mais econômica.
Formato de resposta
{ "id": "32884a3e-bd09-42be-8225-c5cea7d24611", "orderReferenceId": "test", "createdAt": "2024-07-17T10:23:28+00:00"}
Uso de metadados em todo o GelatoConnect
Os metadados fornecidos tanto no nível do pedido quanto no nível do item nas solicitações de pedidos podem ser usados por várias ferramentas dentro do GelatoConnect e também retornados em postbacks. Isso é particularmente valioso para aqueles que precisam manter a continuidade de dados entre seus sistemas.
Metadados do pedido:
Os metadados em nível de pedido se aplicam ao pedido inteiro e são definidos no nível superior da solicitação.
{ "orderReferenceId": "ORD-12345", "orderType": "order", "currency": "USD", "metadata": [ { "key": "campaign", "value": "summer_promo" }, { "key": "source", "value": "web" } ], "shippingAddress": {...}, "items": [...]}
Metadados em nível de item:
Os metadados em nível de item se aplicam a itens específicos e são definidos dentro de cada item no array de itens.
{ "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": [...] } ]}
Metadados em nível de arquivo:
Os metadados em nível de arquivo se aplicam a arquivos específicos e são definidos dentro de cada arquivo no array de arquivos. No exemplo abaixo, eles são usados para definir o texto alternativo para a imagem embroideryText associada ao arquivo.
{ "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 pedido
Interrompa e cancele o processo de produção e envio de um pedido. Isso só é possível até que o status do pedido mude para "enviado".
Endpoint: POST /{orderCancelUrl}
Este endpoint pode aceitar tanto o ID do Pedido (fornecido na resposta de envio do pedido) quanto o ID de Referência do Pedido (seu ID de pedido interno).
Usando o ID do pedido
POST /{orderCancelUrl}/32884a3e-bd09-42be-8225-c5cea7d24611/cancelUsando o ID de referência do pedido
POST /{orderCancelUrl}/test/cancelFormato de resposta
{ "code": 200, "message": "OK"}
Atualizar Envio
Modifique o método de envio ou atualize o endereço de entrega até que o pedido tenha mudado para o status \"enviado\".
Endpoint: PUT /{updateShipmentURL}
Este endpoint pode aceitar tanto o ID do Pedido quanto o ID de Referência do Pedido.
Formato de solicitação
{ "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": "" }}Você pode atualizar o método de envio, o endereço de entrega ou ambos. Pelo menos um desses campos deve ser incluído na solicitação.
Parâmetros de Solicitação
Parameter | Tipo | Obrigatório | Descrição |
shipmentMethodUid | string | Opcional* | Novo método de envio (*Pelo menos um dos campos shipmentMethodUid ou shippingAddress deve ser preenchido) |
endereço de entrega | objeto | Opcional* | Novos detalhes do endereço de entrega (*Pelo menos um dos campos shipmentMethodUid ou shippingAddress deve ser preenchido) |
Formato de resposta
{ "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" }}
Receber pedido
Recupere informações sobre um pedido existente.
Endpoint: GET /{getOrderURL}/{order_id}
Você pode usar tanto o ID do pedido Gelato quanto o seu ID de referência do pedido.
Formato de resposta
A resposta incluirá informações detalhadas sobre o pedido, incluindo:
Detalhes do pedido (ID, referência, status, etc.)
"shippingAddress": {
Itens pedidos com detalhes do produto
Informações do envio (método, rastreamento, etc.)
Informações financeiras
Exemplo de resposta (clique aqui)
Exemplo de resposta (clique aqui)
{ "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",Endereço de entrega "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
Recupere uma lista de pedidos com base em critérios específicos.
Endpoint: POST /{searchOrdersURL}
Formato de solicitação
], "fulfillmentStatus": [ "canceled", "delivered" } ],
Parâmetros da solicitação
Parameter | Tipo | Obrigatório | Descrição |
status de atendimento | string[] | Opcional | Filtrar por status de atendimento de pedidos |
situação financeira | string[] | Opcional | Filtre por status financeiro do pedido |
orderReferenceId | string | Opcional | Filtre pelo seu ID de pedido interno |
IDs de referência do pedido | string[] | Opcional | Filtrar por vários IDs de pedidos internos |
dataInício | string | Opcional | Filtre por pedidos criados após esta data (formato ISO 8601) |
data final | string[] | Opcional | Filtre por pedidos criados antes desta data (formato ISO 8601) |
países | string | Opcional | Filtrar por códigos de países de envio |
limite | número | Opcional | Número máximo de resultados a serem exibidos (padrão: 50, máximo: 100) |
compensação | número | Opcional | Número de resultados a serem ignorados para paginação (padrão: 0) |
Formato de resposta
} "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" }, { ],
Gerenciamento de erros
Quando uma solicitação de API falha, a resposta incluirá um código de erro e uma mensagem descritiva para ajudá-lo a identificar e resolver o problema. Os cenários de erro comuns incluem:
400 Requisição Inválida: Parâmetros inválidos ou ausentes
401 Não autorizado: credenciais de autenticação inválidas ou ausentes
404 Não Encontrado: O recurso solicitado não existe
429 Muitas solicitações: Limite de requisições excedido
Erro 500 no servidor: Ocorreu um erro inesperado no servidor
Exemplo de resposta de erro:
} "code": 400, "message": "Invalid shipping address: Email is not a valid format" {Para garantir uma integração sólida, implemente o tratamento adequado de erros e a lógica de repetição conforme descrito na seção de Limites de Taxa.
Precisa de ajuda?
Se você tiver algum problema ou dúvida sobre a API, entre em contato com nossa equipe de suporte pelo e-mail [email protected].
Inclua as seguintes informações em sua solicitação para a Equipe de suporte:
O endpoint específico da API que você está usando
Sua solicitação de dados (com informações confidenciais ocultadas)
A resposta de erro que você recebeu
Quaisquer horários relevantes
Isso ajudará nossa equipe a resolver o seu problema de forma mais rápida e eficaz.