JetEcommerce
A integração com a JetEcommerce conecta a sua loja Jet ao idworks. O idworks envia para a Jet as categorias, as marcas, os produtos (com variações, preço, estoque e imagens) e recebe de volta os pedidos aprovados. Depois, devolve à Jet a nota fiscal e o despacho de cada pedido.
Nas mensagens do sistema o canal aparece também como JetCommerce (às vezes em minúsculas, jetcommerce). É a mesma integração.
Índice
Conceito
Cadastro e autenticação
- Como ativar a integração?
- Quais credenciais a JetEcommerce pede?
- Como autenticar e validar as credenciais?
Catálogo
- Como as categorias e as marcas chegam à JetEcommerce?
- O que a JetEcommerce exige para publicar um produto?
- Quais dados do produto são enviados?
- Como funcionam as variações na JetEcommerce?
- Como o preço e o estoque são enviados?
- Como as imagens são enviadas?
- Como trazer para o idworks os produtos que já estão na Jet?
Pedidos
- Como os pedidos da JetEcommerce entram no idworks?
- Como enviar a nota fiscal e despachar o pedido?
- O que acontece quando o pedido é cancelado na Jet?
Referência rápida
O que é a integração JetEcommerce?
É a conexão entre a sua loja na JetEcommerce e o idworks. Diferente dos marketplaces, em que a categoria e a marca vêm do canal, aqui o idworks é a origem do catálogo: as categorias, as marcas e os produtos são criados na Jet a partir do seu cadastro no idworks.
📍 Onde: menu lateral → Configurações → Integrações → aba Integrações Disponíveis → busque pela Jet.
O nome exibido no catálogo de integrações e o agrupamento em que o canal aparece são definidos pela idworks e podem mudar. Se não encontrar expandindo as categorias, use a busca pelo nome.
Como ativar a integração?
- Acesse Configurações → Integrações.
- Na aba Integrações Disponíveis, busque pela integração da Jet e clique no botão +.
- Preencha:
- Conta (apenas multi-conta): empresa dona da integração.
- Nome da Integração: texto livre. Útil para distinguir mais de uma loja Jet.
- Clique em Salvar.
A integração aparece em Minhas Integrações. Para abrir os parâmetros, clique no ícone de engrenagem (Configuração) na linha da integração. A janela abre na aba Configurações Gerais.
Pré-requisito: privilégio Criar parametrizações empresa.
Quais credenciais a JetEcommerce pede?
A JetEcommerce usa credencial fixa: não existe cadeado nem tela de login do canal para autorizar. Na tela de parâmetros da integração você informa os dados fornecidos pela Jet:
- Usuário;
- Senha;
- Id da loja;
- Chave integração.
Os campos ficam na aba Configurações Gerais, aberta pelo ícone de engrenagem (Configuração) da integração em Minhas Integrações.
Com usuário, senha e id da loja, o idworks gera o acesso a dois serviços da Jet: um de produtos e outro de pedidos. A chave de integração vai junto em todas as chamadas: envio de produto, preço, estoque, imagem, pedidos, nota fiscal e despacho.
Como autenticar e validar as credenciais?
Geração do acesso. Uma rotina do idworks lê usuário, senha e id da loja e pede à Jet o acesso aos dois serviços (produtos e pedidos):
| Situação | Status da integração |
|---|---|
| Falta usuário, senha ou id da loja | Erro |
| Um dos dois serviços recusa | Erro |
| Os dois serviços liberam o acesso | Ativo |
A rotina só roda para integrações com status Ativo ou Erro. Com a integração Inativo ou Não Autenticado, o acesso não é gerado e os pedidos também não são importados.
⚠️ Essa rotina não confere a chave de integração. A integração pode ficar Ativo mesmo com a chave em branco ou errada, e aí os envios e os pedidos falham. Confira a chave ao preencher.
Validação das credenciais. O botão de validação só aparece quando a integração traz o item de validação entre os parâmetros. Se ele aparecer na aba Configurações Gerais, clique nele e confirme em "Confirma validar as credenciais?". O idworks salva os parâmetros e consulta a fila de pedidos da Jet com o acesso de pedidos já gerado e a Chave integração: se a Jet aceitar, aparece "Integração validada com sucesso!" e o status vai para Ativo; se recusar, o status vai para Erro e aparece "Credenciais inválidas (Header: …)", com o código e a resposta devolvidos pela Jet. A validação não gera um acesso novo: se o acesso ainda não foi gerado, ela pode dar erro. Aguarde a rotina de acesso, que roda para integrações Ativo ou Erro, e valide de novo.
Se o botão não aparecer:
- O status Ativo só diz que a Jet liberou o acesso aos dois serviços com Usuário, Senha e Id da loja. Ele não confirma a Chave integração.
- Para confirmar a chave, sincronize um produto em Integrações (HUB) → Anúncios (veja O que a JetEcommerce exige para publicar um produto?) e confira se o envio passa sem erro. A chegada do primeiro pedido aprovado em Integrações (HUB) → Pedidos Integrados também mostra que a chave está certa.
- Se o envio falhar com o erro devolvido pela Jet, corrija o campo em Configurações Gerais e envie de novo.
Pré-requisito: privilégio Editar parametrizações empresa, para preencher as credenciais.
Como as categorias e as marcas chegam à JetEcommerce?
Na Jet, o idworks cria a categoria e a marca. Não existe uma árvore de categorias "vinda da Jet" para escolher.
Categoria
- Em Integrações (HUB) → Hub Categorias, crie o mapeamento da integração Jet apontando para a categoria do idworks (lado PARA). Veja Como criar um novo mapeamento DE-PARA?.
- Envie a categoria à Jet pelo reprocessamento do mapeamento. Veja O que faz o botão Reprocessar?.
- O idworks envia o nome, a descrição (quando preenchida) e o identificador da categoria no idworks como código externo. A primeira vez cria a categoria na Jet e grava no mapeamento o código devolvido pela Jet. As vezes seguintes atualizam a mesma categoria.
Marca: o caminho é o mesmo, em Integrações (HUB) → Hub Marcas. O idworks envia o nome da marca e o identificador dela no idworks. Veja O que faz o botão Reprocessar?.
Parametrizações: a categoria só é enviada com a parametrização de atualizar categoria ligada, e a marca só com a de atualizar marca ligada. Desligadas, aparecem os avisos:
| Aviso | Quando |
|---|---|
| "configuração não está ativa" | Envio de categoria com a parametrização de categoria desligada. |
| "Atualização de Marca desativada nas configurações" | Envio de marca com a parametrização de marca desligada. |
O que a JetEcommerce exige para publicar um produto?
Antes de sincronizar o produto, confira:
- Parametrização de atualizar produto ligada. Sem ela, o envio para com "Atualização de produto desativada nas configurações", e o log do produto registra "configuração de produto não está ativa".
- Categoria do produto já criada na Jet. A categoria do cadastro do produto precisa ter o mapeamento na Jet com o código da Jet preenchido, como explicado acima. Sem isso, o envio para com "Categoria não cadastrada na plataforma". Essa exigência vale em todo envio, inclusive nas atualizações.
- Marca do produto já criada na Jet, apenas na primeira publicação. Na criação do produto na Jet, sem a marca mapeada, o envio para com "Marca não cadastrada na plataforma". Depois que o produto já existe na Jet, a falta de marca mapeada não bloqueia o envio: a atualização vai sem a informação de marca.
O envio é feito em Integrações (HUB) → Anúncios, pela ação Sincronizar. Veja Como sincronizo anúncios com o canal?.
Quais dados do produto são enviados?
| Dado na Jet | De onde vem no idworks |
|---|---|
| Nome | O título do anúncio no Hub. Se estiver vazio, o título de e-commerce do SKU, quando a parametrização de usar o título está ligada e o campo está preenchido. Caso contrário, o nome do cadastro do produto. |
| Descrição | A descrição do anúncio. Se estiver vazia, a descrição de e-commerce do produto. Sem nenhuma das duas, o produto vai sem descrição. |
| Código e identificador externo | O código do produto no idworks. Vai só na criação. |
| Ativo/inativo | O status do anúncio no Hub. |
| Categoria e marca | Os códigos da Jet gravados nos mapeamentos de categoria e de marca. |
| Peso e medidas | Peso como está no cadastro. Altura, largura e comprimento vão divididos por 100. No produto sem variação, vão só na criação: as atualizações seguintes não reenviam peso nem medidas. No produto com variação, o peso e as medidas de cada SKU são reenviados a cada sincronização. |
Produto sem variação leva, no próprio envio, o preço, o preço promocional, o estoque e o código de barras (GTIN).
Código de barras inválido. Se o GTIN do cadastro não for válido, o idworks envia o campo vazio e registra no log do produto um erro "Código de barras inválido (GTIN), enviado vazio: …", com o código. O produto é enviado mesmo assim: esse erro no log é um aviso de que o GTIN não chegou à Jet, não de que a publicação falhou.
⚠️ Preço e estoque vão junto com o produto mesmo com as parametrizações de preço e de estoque desligadas. Isso vale para o produto sem variação e para cada SKU de produto com variação. Se você mantém o preço ou o estoque da Jet fora do idworks, saiba que cada sincronização do produto sobrescreve esses valores.
Como funcionam as variações na JetEcommerce?
Quando o produto tem variações (cor, tamanho etc.), o idworks:
- Confere a grade na Jet. Compara os nomes dos tipos de variação e dos valores do seu cadastro com as grades que a Jet informa na fila de variações, sem diferenciar maiúsculas de minúsculas. Não é uma consulta a todo o cadastro de grades da Jet: uma grade que existe na Jet, mas não aparece nessa fila, não é reconhecida e pode ser criada de novo com o mesmo nome.
- Cria ou completa a grade que falta. Tipo de variação inexistente na Jet é criado como tipo Texto, já com os valores usados nos SKUs. Para um tipo que já existe na Jet, o idworks envia os valores que faltam nele. Se a Jet recusar, o envio para com "Erro ao criar a variação … na jetcommerce: …".
- Envia o produto e, em seguida, cada SKU, com o próprio preço, preço promocional, estoque, código de barras, peso, medidas e ativo/visível, conforme o status do anúncio.
SKU principal. A variação cadastrada primeiro no anúncio é marcada como a principal do produto na Jet. Não é a de maior estoque nem uma escolha manual.
Código de barras inválido em um SKU vai vazio. O log registra um erro "Código de barras inválido (GTIN) no SKU …, enviado vazio: …".
Quando algo falha:
| Situação | O que acontece |
|---|---|
| Um valor de variação continua sem correspondência na Jet mesmo depois da criação da grade | O envio para antes de enviar o produto, com "Variação de grade não encontrada na jetcommerce (tipo: valor) no SKU …". |
| A Jet recusa um SKU | Os outros SKUs seguem sendo enviados. No fim, a mensagem lista cada SKU recusado como "SKU …: …", com o código do SKU no idworks. |
Como o produto já foi enviado antes dos SKUs, um SKU recusado não impede que o produto e os demais SKUs fiquem publicados. Corrija o SKU apontado e sincronize de novo.
Como o preço e o estoque são enviados?
Pela sincronização de preço e de estoque do anúncio no Hub, de forma manual (ação Sincronizar) ou pelas rotinas automáticas do Hub.
Preço (exige a parametrização de atualizar preço ligada):
- se o preço "de" do anúncio for maior que o preço de venda, o idworks manda o "de" como preço e o preço de venda como preço promocional;
- caso contrário, manda o preço de venda e o preço promocional zerado.
Estoque (exige a parametrização de atualizar saldo ligada): envia o saldo que o Hub calcula para o anúncio.
Produto sem variação recebe preço e estoque no próprio produto. Produto com variação recebe por SKU.
Só vão para o que já foi criado na Jet. Preço e estoque só são enviados para os SKUs que a sincronização do produto já criou na Jet. Um SKU ainda não criado lá é pulado sem aviso. Se nenhum SKU do produto foi criado na Jet, aparece "Anúncio não encontrado (…)" ou "Anúncio não publicado (…)". Sincronizar um único anúncio envia todos os SKUs daquele produto.
Parametrização desligada:
| Origem | O que acontece |
|---|---|
| Ação manual | Aparece "Configuração de preço não está ativa" ou "Configuração de saldo não está ativa", e o mesmo texto fica no log de cada SKU. |
| Rotina automática | Nada aparece na tela. O texto só fica registrado no log de cada SKU, e o envio não acontece. |
Quando a Jet recusa, o erro é listado por SKU ("SKU …: Header …"). Nessas mensagens o número que aparece depois de "SKU" é o código do SKU na Jet (no produto sem variação, o código do produto na Jet), não o código do seu cadastro.
Como as imagens são enviadas?
Pela sincronização de imagens do anúncio, com a parametrização de atualizar imagem ligada. Desligada, aparece "Configuração de imagem não está ativa".
- O produto precisa já existir na Jet. Sincronize o produto antes. Sem isso, o envio para com "Anúncio não encontrado (…)" ou "Anúncio não publicado (…)". Assim como no preço e no estoque, só entram os SKUs já criados na Jet, e sincronizar um anúncio envia as imagens de todo o produto.
- Quais imagens vão. Vão as imagens do produto. As imagens próprias de uma variação só entram quando o produto não tem imagens ou quando a variação está marcada para compartilhar as imagens do produto. A mesma imagem não é enviada duas vezes.
- Todas as imagens vão para o produto. O idworks envia tudo para o produto na Jet. As imagens não ficam presas a cada SKU: não conte com uma foto própria por variação.
- O idworks só envia imagens. Ele não remove nem reordena as imagens que já estão na Jet. Para remover uma imagem ou alterar a ordem, faça direto no painel da JetCommerce. A dica do item Sincronizar Imagem, na janela de sincronização do anúncio, traz o mesmo aviso.
- A primeira imagem é a principal. A segunda vai marcada como alternativa.
- Imagem que não pôde ser baixada entra na mensagem de erro como "Erro ao baixar a imagem: …", com o endereço dela. As demais imagens continuam sendo enviadas.
Como trazer para o idworks os produtos que já estão na Jet?
A importação fica na janela de parâmetros da integração (ícone de engrenagem Configuração em Minhas Integrações), aba Importação de Anúncios. A aba fica desabilitada para quem não tem o privilégio Importar Produto / Anúncio.
A importação de anúncios da JetEcommerce lê a fila de produtos da Jet e cria os anúncios no Hub. Ela procura o produto do idworks pelo identificador externo (ou pelo código) do produto na Jet e, sem resultado, pelo código de barras. O anúncio entra ativo ou inativo conforme o produto esteja ativo na Jet.
Como importar: ligue as opções que quiser (tabela abaixo), clique em Importar Anúncios e confirme "Confirma a importação dos anúncios para esta integração?".
8 parâmetros na aba Importação de Anúncios.
| Parâmetro | Tipo | Para que serve |
|---|---|---|
| Incluir Título na ficha do Anúncio | Sim/Não | Grava o nome do produto na Jet como título do anúncio. Desligado, o anúncio fica sem título próprio e o envio segue a regra do nome descrita em Quais dados do produto são enviados?. |
| Incluir Descrição na Ficha do Anúncio. | Sim/Não | Grava a descrição do produto na Jet na ficha do anúncio. Desligado, a ficha fica sem descrição e o envio usa a descrição de e-commerce do produto. |
| Incluir Preços na ficha do Anúncio | Sim/Não | Grava na ficha de cada SKU do anúncio o preço da Jet (o promocional, quando houver). Desligado, vale o preço da política comercial do produto. |
| Importar somente anúncios inexistente dentro da | Sim/Não | Ligado, importa também os anúncios que não acharam Produto/SKU no idworks; eles entram sem vínculo, para você associar depois. Desligado, e com Criar Produto/SKU, com base no Anúncio Importado. também desligado, esses anúncios ficam de fora e o log registra Não foi encontrado sku/produto referente ao produto JetCommerce. Apesar de o rótulo dizer "somente", ligar a opção aumenta a quantidade importada. |
| Não Realizar o vínculo do Anúncio ao Produto/SKU | Sim/Não | Não procura Produto/SKU para o anúncio, nem pelo código nem pelo código de barras, para o vínculo ser feito depois. Para importar os anúncios sem vínculo, ligue também Importar somente anúncios inexistente dentro da. Sem ela (e sem Criar Produto/SKU, com base no Anúncio Importado.), os anúncios ficam de fora. |
| Criar Produto/SKU, com base no Anúncio Importado. | Sim/Não | Quando o anúncio não acha Produto/SKU, cria o cadastro com os dados da Jet: nome, descrição, código de barras, marca, categoria, peso, medidas e imagens do produto. Produto com variações vira um Produto com um SKU para cada variação; produto sem variação vira um SKU. Cria também a categoria e a marca que não existirem (veja os cuidados abaixo). |
| Atualizar anúncios já importados | Sim/Não | Atualiza os anúncios que já existem no idworks com os dados atuais da Jet: título, descrição e preço, conforme as opções acima que estiverem ligadas, e o status ativo/inativo. Desligado, os dados dos anúncios já importados não mudam. |
| Baixar imagens em segundo plano | Sim/Não | Na importação iniciada por esta aba, as imagens já são sempre baixadas em segundo plano, com a opção ligada ou desligada. |
Cuidados:
- O que é lido sai da fila da Jet. Um produto que a importação leu, mas não conseguiu vincular a um produto do idworks, também é retirado da fila, e uma nova importação não o encontra mais ali. Cadastre ou ajuste os produtos no idworks antes de importar.
- Categoria sem DE-PARA vira categoria nova. Com Criar Produto/SKU, com base no Anúncio Importado. ligado, quando a categoria da Jet não tem mapeamento em Hub Categorias, a importação cria uma categoria nova no idworks, com o nome da categoria da Jet, e grava o mapeamento, mesmo que já exista uma com o mesmo nome. Crie os mapeamentos de categoria antes de importar. A marca é diferente: o idworks procura uma marca com o mesmo nome e só cria uma nova se não encontrar.
- Imagens só no produto. As imagens do produto na Jet vêm junto quando a importação cria o produto no idworks. As variações criadas pela importação vêm sem imagem.
Veja também Como importo anúncios que criei direto no canal?.
Como os pedidos da JetEcommerce entram no idworks?
Com a parametrização de importar pedidos ligada, o idworks lê as filas de pedidos e de status da Jet. O pedido é importado quando chega o status aprovado (código 03). Não existe janela de dias: o que conta é o que está na fila.
Status do pedido na Jet. Em Integrações (HUB) → Pedidos Integrados, a coluna Status integração mostra o status do pedido na Jet (a coluna Status mostra o status do pedido no idworks): Novo (01), Em aprovação (02), Aprovado (03), Em Produção (09), Despachado (04), Tracking (07), Concluído (05) e Cancelado (06). A coluna Criar pedido mostra Sim para Novo e Aprovado e Não para os demais. Com um status que mostra Não, o idworks recusa criar o pedido com "Status atual do pedido no canal de vendas não permite criar pedido. Status: …", que traz o código e o nome do status que barrou. Veja Por que o botão "Criar Pedido" aparece em amarelo ou desabilitado?. Dos status acima, o idworks usa Aprovado (03) na importação e no envio da nota fiscal, Despachado (04) no despacho e Cancelado (06) no cancelamento, como descrito nas seções a seguir. Os outros só aparecem na coluna Status integração.
O que vem no pedido:
- Comprador: nome, CPF/CNPJ, e-mail e telefone (o primeiro telefone ou, sem ele, o segundo).
- Entrega: endereço, destinatário (sem destinatário, o nome do comprador), prazo de entrega e a transportadora informada pela Jet.
- Valores: frete, total e desconto total do pedido, além do desconto de cada item.
- Pagamento: um único pagamento com o total do pedido, o número de parcelas e a forma de pagamento descrita pela Jet.
- Itens: casados primeiro pelo código do SKU na Jet (ou do produto) gravado no anúncio do Hub. Sem anúncio vinculado, pelo código externo do SKU (ou do produto) contra o código do SKU no seu cadastro. O detalhe de cada item segue o formato "SKU: … | Anúncio: … | Variação: [tipo: valor, …]".
- Armazém: o código do CD do pedido na Jet, usado no DE-PARA de armazéns.
Com o status aprovado, o pedido de venda é criado no idworks. A criação segue as regras gerais de Integrações (HUB) → Pedidos Integrados: anúncio vinculado ao produto, DE-PARA de armazém e, quando a validação do Hub está ativa, DE-PARA de transportadora. Veja Como o sistema decide o armazém, tipo de pedido e tipo de pagamento? e DE-PARA Transportadora.
Pedido que não chegou completo. Se o idworks registrou o pedido, mas não conseguiu ler os dados dele na Jet, ele tenta de novo nos ciclos seguintes, por até 15 dias. Pedido com dados completos que parou na criação (por exemplo, por falta de DE-PARA) fica em Pedidos Integrados para você corrigir e reprocessar.
Como enviar a nota fiscal e despachar o pedido?
Nota fiscal. Com a NF do pedido emitida no idworks, o idworks envia à Jet o número, a série, a data de emissão e a chave de acesso da nota. Sem NF emitida, aparece "Nota fiscal não emitida".
O pedido ganha o evento de nota fiscal enviada ao canal, com sucesso ou com o erro devolvido pela Jet. O idworks envia a nota junto com o status aprovado (03), e no Hub o status do pedido continua aprovado (03).
Despacho. Também exige a NF emitida ("Nota fiscal não emitida"). O idworks envia à Jet:
- o código de rastreio do pedido ou, se ele estiver vazio, o número do pedido no idworks;
- o nome da transportadora do pedido.
O pedido passa para despachado (04) na Jet e ganha o evento de despachado no canal, com sucesso ou com o erro devolvido.
Preencha o código de rastreio antes de despachar. Sem ele, a Jet recebe o número do pedido no lugar do rastreio.
O que acontece quando o pedido é cancelado na Jet?
Quando o idworks consulta o status do pedido na Jet e encontra cancelado (06), ele grava esse status no Hub. Se o pedido de venda já existe no idworks e a parametrização de cancelar pedido automaticamente está ligada, o pedido do idworks também é cancelado.
Com a parametrização desligada, ou se o pedido de venda ainda não foi criado, o idworks só atualiza o status no Hub. O pedido de venda, se existir, fica para você tratar manualmente.
Privilégios da tela
Esta tela tem privilégios próprios que controlam o que cada usuário pode fazer. Configure os perfis de acesso em Configurações → Perfis de Acesso vinculando os privilégios abaixo aos grupos desejados. Sem o privilégio, a ação some da tela. As exceções são o botão Deletar e a aba Importação de Anúncios, que aparecem desabilitados.
| Privilégio | Libera |
|---|---|
| Visualizar integrações | Acesso à tela de Integrações e a esta página de configuração. |
| Criar parametrizações empresa | Aba Integrações Disponíveis e ativação da integração (botão + no catálogo). Sem ele, a aba não aparece. |
| Editar parametrizações empresa | Ações Editar (nome e status), De-Paras e ícone de engrenagem (Configuração), que abre os parâmetros da integração. Sem ele, essas ações não aparecem e o duplo clique na linha não abre nada. |
| Deletar parametrizações empresa | Botão Deletar. Exige também Editar parametrizações empresa, porque o botão fica dentro da edição. |
| Importar Produto / Anúncio | Aba Importação de Anúncios na janela de parâmetros. Sem ele, a aba fica desabilitada. |
Quando a ação De-Paras aparece na linha da integração, ela fica desabilitada enquanto a integração não está com status Ativo (por exemplo, com status Erro).