Etapa prévia antes de obter a guia de remessa.
Antes de consultar ou baixar uma guia de remessa do Yuju, é importante ter certas configurações e conhecer o fluxo correto do processo.
Essas informações permitirão evitar erros, reduzir consultas manuais e garantir que as guias estejam disponíveis no momento certo, seja por meio de automações ou do uso da API.
1. Ativar o download automático de guias
O Yuju permite automatizar o download das guias de remessa diretamente da plataforma, evitando a necessidade de consultas manuais por meio da API para cada pedido.
Na seção Guias de remessa, é possível:
Ativar o download automático por canal.
Selecionar o tipo de arquivo que você deseja receber (Excel, arquivo ZIP com todas as guias, entre outros).
Definir se deseja que o Yuju confirme automaticamente os pedidos antes de baixar a guia (isso é essencial para que a guia fique disponível).
Uma vez configurada essa opção, as guias são geradas e baixadas automaticamente, o que agiliza significativamente o processo de expedição e operação logística.
Observação importante: para habilitar o download automático de guias, é necessário que as vendas estejam previamente confirmadas.
Você pode consultar na documentação o passo a passo sobre como realizar essa configuração.
2. Obter o ID do pedido para consultar a guia
Para consultar uma guia de remessa por meio da API, é indispensável ter o ID do pedido. Existem duas formas de obtê-lo:
Opção 1: Webhook (notificação em tempo real)
A Yuju envia notificações em tempo real quando um pedido é recebido de um canal de vendas.
Esses eventos (webhooks) incluem o ID do pedido, que pode ser armazenado e utilizado posteriormente para consultar a guia de remessa.
Essa opção é ideal se você trabalha com integrações em tempo real e automações.
Opção 2: Relatório de vendas
Você também pode obter o ID do pedido por meio dos relatórios de vendas disponíveis no Yuju.
Esses relatórios permitem consultar pedidos históricos e extrair o identificador necessário para solicitar a nota fiscal de remessa quando necessário.
Você pode consultar na documentação o passo a passo sobre como baixar um relatório de vendas.
3. Como usar o endpoint de guias?
A API do Yuju inclui um endpoint específico para obter as guias de remessa de um pedido:
id_channel: Identificador do canal de venda (por exemplo, Mercado Livre, Amazon, Shopify, etc.).
id_order: Identificador do pedido de venda.
body: É possível incluir o formato desejado (geral ou zpl) e os itens do pedido para os quais você deseja gerar a guia.
Ao chamar este endpoint, a API retorna a etiqueta de envio no formato especificado ou um link para baixá-la.
4. Quando consultar a guia?
A guia de um pedido pode não estar disponível imediatamente após o recebimento do evento do pedido (por exemplo, quando chega um webhook). Por isso, recomenda-se o seguinte:
Aguarde pelo menos 5 minutos após receber o webhook para consultar a guia.
Se a guia ainda não estiver disponível, tente novamente após intervalos crescentes (por exemplo, 10 minutos, 30 minutos, várias horas, etc.).
Isso ocorre porque a geração do guia depende, em primeiro lugar, da confirmação do pedido pelo vendedor e da geração do guia pelo marketplace (disponibilização da etiqueta). Em alguns casos, os marketplaces podem demorar para gerar a etiqueta; isso costuma acontecer em épocas de alta demanda.
5. O que acontece se a guia não estiver disponível?
Se a guia ainda não estiver disponível quando você tentar obtê-la (seja por consulta direta ou por meio de automações), você pode:
Configurar novas tentativas programadas, aumentando o intervalo entre elas até que a guia esteja disponível.
Se, após várias tentativas, a guia nunca for gerada, pode ser que o pedido ainda não tenha a guia disponível no canal externo, o que pode exigir a verificação do status no marketplace.
É importante lembrar que a guia não será gerada no Yuju se o pedido não for confirmado adequadamente na plataforma (seja manualmente ou automaticamente), pois sem a confirmação prévia a geração da guia não será habilitada.