Este guia oferece instruções práticas e exemplos para trabalhar com os endpoints da API de Pedidos do GelatoConnect. Vamos mostrar como enviar pedidos, cancelar pedidos, atualizar informações de envio, acessar detalhes dos pedidos e buscar pedidos usando a API.
Pré-requisitos
Antes de trabalhar com estes endpoints, certifique-se de que você tem:
Sua chave de API e segredo (fornecidos ao configurar um conector para seu cliente)
A URL base para os seus endpoints de API
Conhecimento básico para fazer requisições HTTP com curl ou sua ferramenta preferida
Enviar pedido
O endpoint Submit Order permite criar um novo pedido no GelatoConnect.
Endpoint: POST /{submitOrderUrl}
Exemplo de solicitação
# Envio básico de pedidocurl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \--header "Content-Type: application/json" \--header "X-API-KEY: sua-chave:seu-segredo" \--data '{" "orderReferenceId": "SEU-PEDIDO-123", \"orderType\": \"order\", \"currency\": \"USD\", \"shippingAddress\": { "country": "US", \"firstName\": \"John\", \"lastName\": \"Doe\", "addressLine1": "Rua Principal, 123", "city": "Nova York", \"CEP\": \"10001\", \"state\": \"NY\", "email": "[email protected]", "phone": "123-456-7890" }, \"items\": [ { "itemReferenceId": "ITEM-001", "productUid": "flat_product_pf_a4_pt_200-g-m2-gramatura-nao-revestido_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", \"quantidade\": 1, "arquivos": [ { \"type\": \"default\", \"url\": \"https://example.com/files/printfile.pdf\" } ] } ]}'"
Exemplo de resposta
{ "id": "32884a3e-bd09-42be-8225-c5cea7d24611", \"orderReferenceId\": \"YOUR-ORDER-123\", \"createdAt\": \"2025-04-13T10:23:28+00:00\"}
Como usar produtos personalizados do cliente
Em vez de especificar um productUid, você pode usar produtos personalizados com productName e productVariant:
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \--header 'Content-Type: application/json' \\--header 'X-API-KEY: your-key:your-secret' \\--data '{" \"orderReferenceId\": \"YOUR-ORDER-124\", "orderType": "pedido", \"currency\": \"USD\", "shippingAddress": { "country": "US", \"firstName\": \"John\", "lastName": "Doe", \"addressLine1\": \"Rua Principal, 123\", \"city\": \"Nova York\", \"postCode\": \"10001\", \"state\": \"NY\", "email": "[email protected]", "phone": "123-456-7890" }, "itens": [ { "itemReferenceId": "ITEM-001", "productName": "Cartão de visita", "productVariant": { "Size": "Padrão", \"Papel\": \"Fosco Premium\", \"Cor\": \"Colorido em Ambos os Lados\" }, "quantity": 100, "arquivos": [ { \"type\": \"front\", \"url\": \"https://example.com/files/front.pdf\" }, { \"type\": \"back\", \"url\": \"https://example.com/files/back.pdf\" } ] } ]}'"
Pedidos internacionais
Para pedidos internacionais, informe os preços de varejo para declarações alfandegárias:
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \--header 'Content-Type: application/json' \\--header 'X-API-KEY: your-key:your-secret' \\--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\": \"Berlim\", \"postCode\": \"10117\", "email": "[email protected]", "phone": "+49123456789" }, "itens": [ { \"itemReferenceId\": \"ITEM-001\", "productUid": "flat_product_pf_a4_pt_200-g-m²-(Gramatura)-não-revestido_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", "quantidade": 1, "retailPriceInclVat": 19,99, "arquivos": [ { \"type\": \"default\", "url": "https://example.com/files/printfile.pdf" } ] } ]}'
Problemas comuns
Campos obrigatórios ausentes: Certifique-se de que todos os campos obrigatórios estejam incluídos em sua solicitação.
URLs de arquivo inválidas: Certifique-se de que suas URLs de arquivo sejam acessíveis publicamente.
UID de produto desconhecido: Verifique se o UID do produto existe ou use produtos do cliente.
ID de referência de pedido duplicado: Use um ID de referência de pedido exclusivo para cada pedido.
Cancelar pedido
O endpoint Cancelar Pedido permite que você interrompa o processo de produção e envio de um pedido que ainda não foi despachado.
Endpoint: POST /{orderCancelUrl}/{orderId}/cancel
Exemplo de solicitação
# Cancelar usando o ID do pedido Gelatocurl --location --request POST 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611/cancel' \--header "X-API-KEY: seu-key:seu-secret"# Cancele usando o seu ID de referência do pedidocurl --location --request POST 'https://api.partner-connect.io/api/{partner-prefix}/YOUR-ORDER-123/cancel' \--header 'X-API-KEY: sua-chave:seu-segredo'
Exemplo de resposta
{ "code": 200, \"message\": \"OK\"}
Problemas comuns
Pedido já enviado: Pedidos que já foram enviados não podem ser cancelados.
Pedido não encontrado: Verifique se o ID do pedido ou o ID de referência está correto.
Problemas de autenticação: Certifique-se de que sua chave e segredo de API estão corretos.
Atualizar envio
O endpoint Atualizar Envio permite que você modifique o método de envio ou atualize o endereço de entrega para um pedido que ainda não foi enviado.
Endpoint: POST /{updateShipmentURL}/{orderId}
Exemplo de solicitação
# Atualizar detalhes de enviocurl --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: seu-key:seu-secret" \--data '{" "shipmentMethodUid": "fed_ex_2_day", \"shippingAddress\": { "country": "US", "firstName": "Jane", \"sobrenome\": \"Smith\", \"addressLine1\": \"456 Park Ave\", "city": "Nova York", "postCode": "10022", \"state\": \"NY\", \"email\": \"[email protected]\", "phone": "987-654-3210" }}'"# Atualize apenas o método de enviocurl --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"}'
Exemplo de resposta
{ "shippingAddress": { \"id\": \"2f85d65b-4814-4b5f-90a2-a7de28250bd1\", "orderId": "32884a3e-bd09-42be-8225-c5cea7d24611", \"country\": \"US\", "firstName": "Jane", "lastName": "Smith", "addressLine1": "Avenida Park, 456", "city": "Nova 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 comuns
Pedido já enviado: Os detalhes de envio para pedidos já despachados não podem ser atualizados.
Campos obrigatórios ausentes: Certifique-se de que todos os campos obrigatórios estejam preenchidos no endereço de entrega.
Método de Envio Inválido: Verifique se o UID do método de envio é válido.
Pedido não encontrado: Verifique se o ID do pedido ou o ID de referência está correto.
Obter Pedido
O endpoint Obter Pedido permite que você recupere informações detalhadas sobre um pedido existente.
Endpoint: POST /{getOrderURL}/{orderId}
Exemplo de solicitação
# Obtenha o pedido usando o ID do pedido Gelatocurl --location --request GET 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \--header 'X-API-KEY: your-key:your-secret'# Obtenha o pedido usando o seu ID de referência do pedidocurl --location --request GET 'https://api.partner-connect.io/api/{partner-prefix}/YOUR-ORDER-123' \\--header "X-API-KEY: sua-chave:seu-segredo"
Exemplo de resposta
A resposta traz informações detalhadas sobre o pedido, incluindo:
Detalhes do pedido (ID, referência, status, carimbos de data/hora)
Endereço de entrega
Itens pedidos
Informações do envio
Informações financeiras
Devido ao tamanho da resposta, consulte a documentação da API para ver a estrutura completa da resposta.
Usando os dados de resposta
A resposta de Get Order traz informações valiosas que você pode usar para:
Exibir Status do Pedido: Mostre aos clientes o status atual dos pedidos deles.
Rastrear Remessas: Extraia informações de rastreamento para acompanhar suas remessas.
Verifique os detalhes do pedido: Confirme se as informações do pedido estão corretas.
Analise o histórico de pedidos: Crie relatórios e análise de dados com base nas informações dos pedidos.
Problemas comuns
Pedido Não Encontrado: Verifique se o ID do pedido ou ID de referência está correto.
Problemas de Autenticação: Certifique-se de que sua chave de API e senha secreta estejam corretas.
Pesquisar pedidos
O endpoint Search Orders permite que você recupere uma lista de pedidos com base em critérios específicos.
Endpoint: POST /{searchOrdersURL}
Exemplo de solicitação
# Pesquisar por status de atendimento de pedidoscurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \\--header 'X-API-KEY: your-key:your-secret' \\--data '{ \"fulfillmentStatus\": [\"enviado\", \"entregue\"]}'"# Pesquise por intervalo de datascurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: your-key:your-secret' \\--data '{ "startDate": "2025-01-01T00:00:00+00:00", \"endDate\": \"2025-04-13T23:59:59+00:00\"}'# Pesquise pelo ID de referência do pedidocurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \\--header 'X-API-KEY: seu-key:seu-secret' \--data '{ \"orderReferenceId\": \"YOUR-ORDER-123\"}'# Pesquisa com paginaçãocurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \\--header 'X-API-KEY: seu-key:seu-secret' \--data '{ \"fulfillmentStatus\": [\"created\", \"printed\"], "limit": 50, "offset": 0}'
Exemplo de resposta
{ "pedidos": [ { \"id\": \"9f9ff09f-5891-4d3d-be35-9b302db835a1\", \"clientId\": \"ddb4371a-ad83-4f68-b99d-6b48c7eff366\", \"orderReferenceId\": \"YOUR-ORDER-123\", "fulfillmentStatus": "enviado", \"financialStatus\": \"pago\", "currency": "USD", \"totalInclVat\": \"33.45\", "orderType": "pedido", "channel": "api", "firstName": "John", "lastName": "Doe", "country": "US", "itemsCount": 1, "createdAt": "2025-04-10T11:05:09+00:00", "updatedAt": "2025-04-10T14:05:10+00:00", "orderedAt": "10/04/2025 11:05:07", \"customerReferenceId\": \"CUST-456\" }," // Mais pedidos... ]}
Paginação
O endpoint de Pesquisa de Pedidos suporta paginação para gerenciar grandes conjuntos de resultados:
# Primeira página (50 itens)curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header "X-API-KEY: seu-key:seu-secret" \--dados '{ "fulfillmentStatus": ["enviado"], "limite": 50, "offset": 0}'"# Segunda página (próximos 50 itens)curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: your-key:your-secret' \--data '{ "fulfillmentStatus": ["enviado"], \"limit\": 50, \"offset\": 50}'
Cenários comuns de pesquisa
Pedidos por status:
{ \"fulfillmentStatus\": [\"criado\", \"impresso\"] }Pedidos por Intervalo de Datas:
{ "startDate": "2025-04-01T00:00:00+00:00", \"endDate\": \"2025-04-13T23:59:59+00:00\"}Pedidos por país:
{ "countries": ["US", "CA"] }Combinando critérios:
{ \"fulfillmentStatus\": [\"enviado\"], "countries": ["US"], \"startDate\": \"2025-04-01T00:00:00+00:00\"}
Problemas comuns
Nenhum resultado: Verifique se os critérios de pesquisa não estão muito restritos.
Muitos resultados: Use a paginação e/ou mais filtros para refinar sua busca.
Formato inválido: Certifique-se de que os formatos de data sigam o padrão ISO 8601 (AAAA-MM-DDTHH:MM:SS+00:00).
Vinculando modelos a endpoints de API
Ao enviar pedidos pela API, muitas vezes será necessário adaptar os dados do seu formato para o formato do GelatoConnect. Os modelos fazem essa conversão, mas é preciso vincular explicitamente o seu modelo ao endpoint da API para que ele seja aplicado.
Como vincular um modelo a um endpoint de envio de pedido:
Acesse sua lista de conectores e clique no hiperlink Editar ao lado do endpoint de envio de pedido.
Na página de configuração do endpoint, localize a seção Modelo de endpoint
Selecione seu modelo de envio de pedido no menu suspenso
Clique no botão Definir endpoint no canto superior direito da página
Clique em Salvar alterações no canto superior direito para aplicar sua configuração
Após concluir essas etapas, todos os envios de pedidos enviados para este endpoint usarão seu modelo para transformar os dados antes do processamento. Isso garante que o formato do seu sistema seja corretamente convertido para o formato esperado pelo GelatoConnect.
Sem essa configuração, seu modelo não será aplicado mesmo que exista e esteja corretamente projetado, o que pode levar a falhas na validação do pedido se o formato dos seus dados não corresponder exatamente aos requisitos do GelatoConnect.
Melhores práticas de integração
Ao integrar com os endpoints da API de pedidos, considere estas melhores práticas:
1. IDs de pedidos da loja
Sempre armazene tanto o ID de referência do seu pedido quanto o ID do pedido Gelato retornado na resposta. Assim, fica mais fácil acompanhar e localizar os pedidos em ambos os sistemas.
2. Lide com erros de forma cuidadosa
Implemente um tratamento de erros adequado para cada chamada de API. Analise a mensagem de erro da resposta para oferecer um retorno claro aos usuários e adote mecanismos apropriados de recuperação.
Para orientações sobre como implementar um tratamento de erros eficiente, consulte a seção "Melhores práticas para tratamento de erros" na Documentação da API de gerenciamento de pedidos.
3. Implementar Idempotência
Gere identificadores de referência de pedido únicos para cada pedido e utilize o parâmetro preventDuplicate para garantir que, mesmo que ocorram problemas de rede e seja necessário tentar novamente, o pedido não será enviado duas vezes.
4. Use notificações de Webhook
Em vez de consultar atualizações de status de pedidos, configure notificações de webhook para receber atualizações em tempo real quando os status dos pedidos mudarem.
5. Validar dados antes do envio
Valide os dados do pedido do seu lado antes de enviá-los para a API. Assim, evita erros óbvios e melhora a experiência de quem usa.
6. Implementar lógica de repetição
Adicione lógica de nova tentativa com aumento exponencial do tempo de espera para erros temporários, especialmente para respostas de limite de taxa (429).
Para detalhes de implementação sobre recuo exponencial e jitter, consulte a seção "Melhores Práticas para Limite de Taxa" na Documentação da API de Gerenciamento de Pedidos ou o post do blog da AWS sobre recuo exponencial e jitter.
7. Otimize as consultas de pesquisa
Seja específico nos critérios de busca para reduzir o número de resultados e melhorar o desempenho.
8. Armazenar dados de referência em cache
Armazene em cache os UIDs de produtos e outros dados de referência para reduzir o número de chamadas de API necessárias.
Conclusão
A API de Pedidos do GelatoConnect oferece um conjunto poderoso de endpoints para gerenciar todo o ciclo de vida do pedido. Ao compreender como usar esses endpoints de forma eficaz, você pode criar uma integração perfeita entre seus sistemas e o GelatoConnect.
Para informações mais detalhadas, consulte a Documentação da API de Gerenciamento de Pedidos.