Introdução
A API do GelatoConnect permite integrar seus sistemas ao GelatoConnect de forma programática para enviar pedidos, acompanhar o status e gerenciar detalhes de envio. Este guia vai ajudar você a entender como começar a usar a API e implementar sua primeira integração.
Pré-requisitos
Antes de começar a trabalhar com a API do GelatoConnect, você precisa ter:
Sua chave de API e segredo (fornecidos ao configurar um conector para seu cliente)
Compreensão básica de REST APIs e métodos HTTP
Familiaridade com o formato de dados JSON
Um ambiente de desenvolvimento capaz de fazer solicitações HTTP
Noções básicas de API
A API de Gerenciamento de Pedidos do GelatoConnect é estruturada com base nos princípios REST e utiliza métodos HTTP padrão para interagir com os recursos. Todas as solicitações à API devem usar HTTPS, e todas as respostas são retornadas em formato JSON, inclusive as mensagens de erro.
URL base
A URL base para a API GelatoConnect é:
https://api.partner-connect.io/api/{partner-prefix}/
O seu prefixo de parceiro específico será fornecido durante o processo de integração.
Autenticação
Todas as solicitações de API devem incluir suas credenciais de autenticação no cabeçalho. Para autenticar:
Adicione o cabeçalho
X-API-KEYà sua solicitaçãoDefina o valor para sua chave e segredo no formato
chave:segredo
Exemplo:
X-API-KEY: your-api-key:your-api-secret
Fazendo sua primeira solicitação de API
Vamos passar juntos pelo processo de fazer uma solicitação simples de API para enviar um pedido.
1. Prepare os dados do seu pedido
Crie um objeto JSON com os detalhes do pedido. Aqui está um exemplo mínimo:
{"orderReferenceId": "seu-pedido-ref-123","orderType": "order","currency": "USD","shippingAddress": {"country": "US","firstName": "John","lastName": "Doe","addressLine1": "Rua Principal, 123","city": "Nova York","postCode": "10001","state": "NY","email": "[email protected]","phone": "1234567890"},\"items\": [{"itemReferenceId": "item-123",\"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,"arquivos": [{"type": "default",\"url\": \"https://example.com/path/to/printfile.pdf\"}]}]}
2. Enviar o pedido
Faça uma solicitação POST para o endpoint de envio de pedido:
POST https://api.partner-connect.io/api/{partner-prefix}/order
Inclua seu cabeçalho de autenticação e os dados do pedido em JSON no corpo da requisição.
3. Processar a resposta
Se der certo, você vai receber uma resposta assim:
{\"id\": \"32884a3e-bd09-42be-8225-c5cea7d24611\","orderReferenceId": "seu-pedido-ref-123","createdAt": "12/04/2025 10:23:28"}
O campo id contém o ID do pedido GelatoConnect, que você deve guardar para referência futura.
Operações comuns da API
Quando você já estiver à vontade com o envio básico de pedidos, pode explorar outras operações da API:
Ver detalhes do pedido
Recupere informações sobre um pedido existente:
GET https://api.partner-connect.io/api/{partner-prefix}/{orderId}
Cancelar um pedido
Cancele um pedido que ainda não foi enviado:
POST https://api.partner-connect.io/api/{partner-prefix}/{orderId}/cancel
Pesquisar pedidos
Encontre pedidos com base em critérios específicos:
POST https://api.partner-connect.io/api/{partner-prefix}/search
Atualizar envio
Altere os dados de envio de um pedido:
PUT https://api.partner-connect.io/api/{partner-prefix}/{orderId}
Implementando Produtos Personalizados
Em vez de usar UIDs de produto, você pode usar Produtos do Cliente para uma abordagem mais fácil de entender:
{"productName": "Cartão de visita","productVariant": {\"Tamanho\": \"Padrão\",\"Papel\": \"Fosco Premium\","Color": "Colorido frente e verso"}}
Isso requer a configuração de Produtos Personalizados no GelatoConnect antes de utilizá-los nas chamadas de API.
Testando sua integração
Antes de colocar sua integração no ar, teste tudo cuidadosamente usando estas abordagens:
Teste com pedidos de amostra: Crie pedidos de teste com quantidades baixas e verifique se eles aparecem corretamente no GelatoConnect.
Verifique as atualizações de status do pedido: Acompanhe os pedidos durante seu ciclo de vida para garantir que o seu sistema receba e processe corretamente as mudanças de status.
Tratamento de erros: Crie pedidos inválidos intencionalmente para testar sua lógica de tratamento de erros.
Teste de ponta a ponta: Realize todo o processo do pedido, do envio até a entrega, usando um pequeno conjunto de pedidos de teste.
Melhores práticas
Para garantir a melhor integração com a API do GelatoConnect:
IDs dos pedidos da loja: Sempre armazene o ID do pedido do GelatoConnect retornado na resposta de criação do pedido.
Implemente o tratamento de erros: Adicione um sistema sólido de tratamento de erros para lidar com respostas inesperadas ou indisponibilidade da API.
Use Idempotência: Gere IDs de referência de pedidos únicos para evitar pedidos duplicados.
Implemente o recuo exponencial: Ao receber erros de limite de taxa (429), aumente o tempo de espera entre as tentativas.
Monitore o uso da API: Acompanhe o uso da sua API para evitar atingir os limites de requisições.
Resolvendo problemas comuns
Erros de autenticação
Se você receber um erro 401 Não Autorizado, verifique se:
Sua chave e segredo de API estão corretos
O formato é
key:secretno cabeçalho X-API-KEYVocê está usando HTTPS, não HTTP
Erros de solicitação inválida
Se você receber um erro 400 Bad Request:
Verifique a mensagem de erro para problemas específicos do campo
Verifique se todos os campos obrigatórios estão incluídos
Confirme se o formato JSON é válido
Erros de Limite de Taxa
Se você receber um erro 429 Too Many Requests (Muitas solicitações):
Implementar uma estratégia de recuo para espaçar as solicitações
Considere agrupar solicitações quando possível
Revise sua integração para evitar chamadas repetidas desnecessárias
Próximo passo
Agora que você compreende o básico da API GelatoConnect, você também está pronto para ler a documentação completa da API para informações detalhadas sobre os endpoints 🔗 [Recebimento de Pedidos - GCW] Documentação da API de Gerenciamento de Pedidos