Ao enviar pedidos para o GelatoConnect via API, você tem duas opções para especificar produtos: usar UIDs de Produto ou usar Produtos Personalizados. Este guia explica ambas as abordagens, seus benefícios e quando usar cada uma.
Abordagem do UID do produto
A abordagem de UID do produto envolve o uso de identificadores únicos de produto (UIDs) para especificar produtos em seus pedidos.
Como Funciona
Ao utilizar UIDs de Produto, inclua o parâmetro productUid no item do seu pedido:
{ "itemReferenceId": "ITEM-001", \"productUid\": \"flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor\", \"quantidade\": 1, "arquivos": [ { "type": "default", "url": "https://example.com/files/printfile.pdf" } ]}
Estrutura do UID do produto
Um UID de Produto é uma string estruturada que codifica atributos do produto. Por exemplo, em flat_product_pf_a4_pt_200-g/m² (Gramatura)-não revestido_cl_4-0_ct_none_prt_none_sft_none_set_none_hor:
flat_product: Tipo de produtopf_a4: Formato de papel (tamanho A4)pt_200-gsm-uncoated: Tipo de papel (papel não revestido de 200 g/m² (Gramatura))cl_4-0: Configuração de cor (processo de 4 cores na frente, 0 cores no verso)ct_none: Corte (nenhum)prt_none: Efeitos especiais de impressão (nenhum)sft_none: Tratamentos de superfície (nenhum)set_none: Efeitos especiais (nenhum)hor: Orientação (horizontal)
Abordagem de produtos personalizados para o cliente
A abordagem de Produtos do Cliente envolve criar definições de produtos personalizados no GelatoConnect e referenciá-los pelo nome e variante em seus pedidos.
Como Funciona
Primeiro, você configura os Produtos do Cliente no GelatoConnect, definindo os nomes dos produtos e suas opções de variantes. Depois, ao fazer pedidos, basta referenciar esses produtos usando os parâmetros productName e productVariant:
{ "itemReferenceId": "ITEM-001", \"productName\": \"Cartão de visita\", "productVariant": { "Size": "Padrão", "Paper": "Fosco premium", \"Cor\": \"Colorido em ambos os lados\" }, "quantity": 100, "arquivos": [ { "type": "frente", "url": "https://example.com/files/front.pdf" }, { "type": "voltar", "url": "https://example.com/files/back.pdf" } ]}
Configurando Produtos do Cliente
Antes de usar Produtos Personalizados em seus pedidos de API, você precisa configurá-los no GelatoConnect:
Navegue até a seção Produtos no GelatoConnect
Crie Produtos do Cliente com nomes específicos e opções de variantes
Mapeie estes Produtos do Cliente para as especificações de produtos da Gelato
Quando usar cada abordagem
Use os UIDs de Produto Quando:
Você está só começando com o GelatoConnect
Você tem um pequeno número de produtos fixos
Você quer implementar rapidinho, sem precisar de configurações extras
Você está criando um protótipo ou uma implementação de teste
Use produtos personalizados para clientes quando:
Você tem um grande catálogo de produtos
Você quer referências de produtos mais intuitivas no seu código
Os nomes dos seus produtos diferem das convenções de nomenclatura da Gelato
As configurações do produto podem mudar com o tempo
Exemplos de implementação
Exemplo de UID do Produto
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": "ORDER-123", "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", \"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\", "quantity": 1, \"files\": [ { "type": "padrão", \"url\": \"https://example.com/files/printfile.pdf\" } ] } ]}'
Exemplo de produtos do cliente
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \--header 'Content-Type: application/json' \--header "X-API-KEY: seu-key:seu-secret" \--data '{ \"orderReferenceId\": \"ORDER-124\", "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": "123-456-7890" }, "itens": [ { \"itemReferenceId\": \"ITEM-001\", "productName": "Panfleto", "productVariant": { "Size": "A4", \"Papel\": \"Não revestido 200gsm\", "Printing": "Colorido em um lado só" }, "quantity": 100, "arquivos": [ { "type": "padrão", \"url\": \"https://example.com/files/flyer.pdf\" } ] } ]}'
Melhores práticas
Independentemente da abordagem que você escolher, siga estas melhores práticas:
Consistência: Mantenha uma abordagem única durante toda a sua implementação
Documentação: Mantenha uma documentação clara dos seus mapeamentos de produtos
Validação: Valide os identificadores dos produtos antes de enviar os pedidos
Testes: Faça testes completos com pedidos de exemplo antes de começar a vender de verdade
Tratamento de erros: Implemente um tratamento de erros eficiente para produtos inválidos
Transição Entre Abordagens
Se você começar com UIDs de Produto e posteriormente quiser mudar para Produtos do Cliente:
Configure os seus Produtos para Clientes no GelatoConnect
Mapeie-os para os UIDs de Produto que você já vem usando
Atualize a sua implementação de API para usar productName e productVariant
Realize testes completos antes de implantar em produção
A transição inversa também é possível, mas é menos comum.
Conclusão
Ambas as abordagens têm seus méritos, e a escolha depende de seus requisitos e restrições específicos. Os UIDs de produto oferecem simplicidade e acesso direto ao catálogo da Gelato, enquanto os Produtos do Cliente proporcionam melhor legibilidade, flexibilidade e gerenciamento centralizado.
Na maioria das implementações de longo prazo, os Produtos do Cliente oferecem vantagens em termos de manutenção e clareza. No entanto, para implementações rápidas ou casos de uso específicos, os UIDs de Produto podem ser mais indicados.
Para mais informações sobre como configurar Produtos Personalizados no GelatoConnect, consulte o guia Criando Produtos Personalizados.