Integrações
A tela de Integrações é o ponto único onde a empresa cadastra, configura e acompanha todas as suas integrações com sistemas externos — marketplaces (Mercado Livre, Magalu, Amazon, Shopee), transportadoras (Correios, Loggi, Total Express, Intelipost), bancos e adquirentes (Stark Bank, Itaú, Stone, Cielo), gateways de pagamento, ERPs, plataformas fiscais, e-mail e operacionais. Cada integração que você ativa vira uma "instância" do tipo escolhido, com parametrizações próprias (URL, credenciais, códigos externos, opções de comportamento) e um status que reflete a saúde da conexão.
A tela tem duas abas. Minhas Integrações mostra as integrações já cadastradas pela empresa, com logo do canal, nome interno, categoria de canal de venda (quando aplicável), reputação, código e status (Ativo, Erro de autenticação, Não autenticado, Inativo). Cada linha tem ações: Autenticar Integração (quando o tipo pede uma autorização externa — abre o login do canal numa nova aba), De-Paras (mapeamento de Armazém, Transportadora e Tipo de Pagamento para integrações de Canal de Venda e Adquirente), Editar (nome e status) e Configuração (ícone de engrenagem — abre a janela onde você define as credenciais e o comportamento da integração).
Integrações Disponíveis mostra o catálogo completo de tipos suportados, agrupados por categoria (Canal de Venda, Banco, Adquirente, Gateway, Transportadora, Outros, etc.). Use a aba para encontrar e ativar uma nova integração — o sistema abre um modal pedindo só o nome interno (e a empresa, no caso de multi-conta), e a partir daí você passa pela tela de parametrizações para preencher as credenciais.
Índice
Conceito
- O que é a tela Integrações?
- Qual a diferença entre tipo de integração, integração da empresa e parametrização?
- Quais categorias de integração existem?
- O que significa cada status (Ativo, Erro, Não Autenticado, Inativo)?
- O que é a coluna Reputação?
Cadastro e edição
- Como criar uma nova integração?
- Como preencher as parametrizações de uma integração?
- Como autenticar uma integração que pede autorização externa?
- Como verificar se a integração está funcionando?
- Minha integração parou de funcionar: como reautenticar?
- Erros estranhos que na verdade são integração caída: como reconhecer?
- Reautenticei a integração: e os pedidos que faltaram?
- O canal pede para desvincular e revincular o idworks (Mercado Livre, Magalu): como faço?
- Recebi um e-mail avisando que meu acesso vai expirar: o que fazer?
- Como editar o nome e o status de uma integração?
Busca e visualização
Regras de negócio
- O que é a ação "De-Paras" em integrações de Marketplace?
- Como excluir uma integração?
- Por que não consigo excluir uma integração?
- O que acontece com os dados quando excluo uma integração?
Boas práticas
Referência rápida
O que é a tela Integrações?
É o centro de controle das integrações da empresa com sistemas externos. Em vez de você cadastrar credenciais espalhadas em várias telas, todas ficam aqui — listadas por tipo (Mercado Livre, Correios, Stark Bank, etc.), com o status atual (Ativo, Erro, Não Autenticado, Inativo) e atalhos para configurar, autenticar, verificar e remover cada uma.
A tela tem duas abas:
- Minhas Integrações — a lista das que já estão cadastradas pela empresa.
- Integrações Disponíveis — o catálogo de tipos suportados, agrupado por categoria, com botão + para ativar uma nova.
📍 Onde: menu lateral → Configurações → Integrações.
Qual a diferença entre tipo de integração, integração da empresa e parametrização?
| Tipo de integração | Integração da empresa | Parametrização | |
|---|---|---|---|
| O que é | Um conector pronto que o idworks oferece (Mercado Livre, Stark Bank, Correios). É definido pela idworks. | Uma instância de um tipo, ativada pela sua empresa. Você pode ter mais de uma do mesmo tipo (ex.: duas contas de Mercado Livre, três contas no Itaú). | Um campo de configuração dentro de uma integração — URL, credencial, identificador externo, opção de comportamento. |
| Onde aparece | Aba Integrações Disponíveis. | Aba Minhas Integrações. | Janela aberta pelo ícone de engrenagem (Configuração) na linha da integração. |
| Onde está armazenado | Catálogo de tipos do idworks. | Cadastro da sua empresa. | Valor por integração, ligado a um nome de configuração. |
A relação é um para muitos para muitos: o idworks oferece dezenas de tipos; sua empresa pode ativar quantos quiser (e mais de uma instância de cada); e cada instância tem suas próprias parametrizações.
Quais categorias de integração existem?
O idworks agrupa os tipos de integração em categorias para facilitar a navegação na aba Integrações Disponíveis. As categorias que aparecem no catálogo são:
- Canal de Venda — marketplaces (Mercado Livre, Magalu, Amazon, Shopee, Americanas via SkyHub, Carrefour, Via, Madeira Madeira, Webcontinental e muitos outros), plataformas de e-commerce (Vtex, Shopify, WooCommerce, Tray, Nuvem Shop, etc.), ERPs como Bling e Tiny, e o tipo próprio idworks (integração interna).
- Banco — bancos para envio de pagamentos e conciliação de extrato (Stark Bank, Itaú, Inter, Bradesco, Banco do Brasil, etc.).
- Adquirente — adquirentes/processadoras de cartão para conciliação financeira (Cielo, Rede, PayPal).
- Gateway — gateways de pagamento (Pagar.me, PayGo, Mercado Pago).
- Transportadora — Correios, Loggi, Total Express, Intelipost, Jadlog, Mandaê, etc., para cotação de frete, geração de etiqueta e rastreamento.
- Simulação Frete — Shopee Logistics.
- Serviços Adicionais — WhatsApp próprio e Chat WhatsApp.
- Outros — e-mail (SMTP, para disparar e-mails transacionais), Webhook, WhatsApp (Meta), Domínio e Cresce Vendas.
Cada categoria muda o que aparece na lista de parametrizações e que ações fazem sentido (ex.: De-Paras só aparece em Canal de Venda e Adquirente; Autenticar Integração só aparece em tipos que pedem autorização externa).
O que significa cada status (Ativo, Erro, Não Autenticado, Inativo)?
| Status | Significado |
|---|---|
| Ativo | A integração está operacional. As parametrizações estão preenchidas e (quando aplicável) as credenciais foram autenticadas com sucesso. As ações automáticas vinculadas — sincronizar anúncios, importar pedidos, enviar pagamentos, atualizar rastreio — rodam normalmente. |
| Erro | A última chamada ao sistema externo retornou erro de autenticação. Geralmente significa que a credencial foi revogada, expirou ou está incorreta. Verifique as parametrizações e refaça a autenticação. |
| Não Autenticado | A integração foi cadastrada mas o fluxo de autenticação ainda não foi concluído. Aparece para tipos que exigem uma autorização externa (Mercado Livre, Amazon, etc.) — você precisa fazer login no canal e liberar o acesso ao idworks. Clique em Autenticar Integração na linha para iniciar. |
| Inativo | A integração foi desligada manualmente (no botão de edição) ou excluída. Não dispara nenhuma ação automática. Pode ser reativada editando e mudando o status para Ativo. No Mercado Livre, inativar também revoga a autorização no canal: depois de reativar, é preciso clicar em Autenticar Integração de novo (ver Como editar o nome e o status de uma integração?). |
Os status são fixos — não é possível personalizar.
O que é a coluna Reputação?
Para integrações de Marketplace, alguns canais expõem um indicador de reputação do vendedor (verde, amarelo, laranja, vermelho). O idworks captura esse valor por uma parametrização específica de Reputação e mostra na listagem como uma célula colorida:
| Cor | Nível interno | Significado típico |
|---|---|---|
| Vermelho | 1_red | Reputação ruim — risco de bloqueio do canal. |
| Laranja | 2_orange | Reputação baixa — atenção. |
| Amarelo claro | 3_yellow / 4_yellow | Reputação intermediária. |
| Verde | 5_green | Reputação boa — sem restrições. |
A coluna só fica preenchida para tipos que sincronizam essa informação do canal. Para os demais (banco, transportadora, adquirente), a célula fica em branco.
Como criar uma nova integração?
- Acesse Configurações → Integrações.
- Clique na aba Integrações Disponíveis.
- Use o campo Buscar integração para filtrar pelo nome do canal, ou expanda a categoria desejada (Canal de Venda, Banco, Transportadora, etc.).
- Clique no botão + dentro do card da integração que você quer ativar.
- Um modal abre pedindo:
- Conta — só aparece quando a empresa tem mais de uma conta cadastrada. Selecione a conta dona da integração. (Para integrações do tipo idworks, em vez de conta, o sistema pede Empresa — escolha a filial faturadora correta.)
- Nome da Integração — texto livre. Use um nome que identifique facilmente a instância (ex.: Mercado Livre - Loja Principal, Stark Bank - PJ Carrefour). Útil quando você ativa mais de uma integração do mesmo tipo.
- Clique em Salvar.
A integração aparece imediatamente na aba Minhas Integrações com status Não Autenticado ou Ativo, dependendo do tipo (ver pergunta sobre status). A partir daí, configure as parametrizações.
Cadastros que você precisa ter antes
Esta tela não exige nenhum cadastro prévio próprio — basta ter a Conta da empresa configurada. Algumas integrações específicas precisam de cadastros antes para terem onde "apontar" (ex.: integração de banco precisa de Conta Bancária cadastrada para vincular depois). Verifique a coluna "O que pedir" nas parametrizações da integração.
Pré-requisito: privilégio Criar parametrizações empresa.
Como preencher as parametrizações de uma integração?
- Na aba Minhas Integrações, localize a integração desejada.
- Clique no ícone de engrenagem (Configuração) na linha (ou dê duplo clique). Abre uma janela com todas as parametrizações que o tipo expõe, agrupadas por subgrupo (Credenciais de Acesso, Fiscal Produto, Produto, Pedido, Transporte, Webhook, etc.).
- Cada campo tem um tipo:
- Texto — entrada livre (URL, identificador, descrição).
- Senha — credencial sensível; aparece mascarada.
- Sim/Não — switch para ligar ou desligar comportamento.
- Lista única ou Lista múltipla — seleção a partir de uma lista (tipo de documento, plano de contas, conta bancária, etc.). Algumas listas vêm do catálogo nacional (Modalidade de Frete, Tabela de Listing do Mercado Livre); outras, da própria empresa (tipos de documento cadastrados em Financeiro → Tipo Documento, planos de contas, contas bancárias).
- Copiar URL — exibe uma URL pronta (com tokens/identificadores embutidos) para você colar no sistema externo (ex.: webhooks de marketplaces).
- Preencha o que se aplica e clique em Salvar. Você não precisa preencher tudo de uma vez — pode salvar parcialmente e voltar depois.
Por que o campo de token, senha ou chave aparece como ********?
Os campos que guardam segredo — como token, senha, chave de API e client_secret — aparecem sempre como ******** quando você abre a janela, mesmo que o campo seja do tipo Texto. Campos de identificação (como a App Key da VTEX ou o Seller ID) não são mascarados e continuam visíveis. O idworks não mostra mais o valor gravado de um campo de segredo e não dá para copiá-lo da tela. Um campo de segredo ainda não preenchido continua vazio, então os asteriscos indicam que existe um valor guardado.
- Para manter o valor, deixe o campo como está e clique em Salvar: o valor gravado não muda.
- Para trocar o valor, apague os asteriscos e digite o novo valor no lugar.
- Para ver o valor atual, consulte o painel do canal onde a credencial foi gerada. Se não encontrar, gere uma nova lá e digite no campo.
Mudei o estoque de segurança, o estoque fixo ou o estoque fictício: o canal recebe o novo saldo?
Sim. Quatro parâmetros disparam o reenvio do saldo ao salvar: Atualizar saldo estoque, Estoque de segurança, Estoque fixo e o estoque fictício (Ativar estoque fictício). Se, ao salvar, o valor de algum deles ficou diferente do que estava gravado, o idworks reenvia o saldo de todos os anúncios ativos e vinculados daquela integração — você não precisa esperar cada SKU ter uma movimentação de estoque para o novo valor valer.
- O reenvio cobre todos os anúncios, mas o novo valor não muda o saldo de todos: o Estoque de segurança da integração só vale para SKUs sem estoque de segurança próprio no cadastro, e o Estoque fixo só vale para SKUs com estoque infinito. Para os outros, o saldo reenviado não muda.
- Só esses quatro disparam o reenvio. Armazéns para somar quantidade e Percentual disponibilidade de estoque também mudam o saldo enviado, mas não disparam o reenvio: o novo valor só chega ao canal na próxima movimentação de cada SKU. Mudar qualquer outro parâmetro, ou salvar a janela sem alterar nenhum deles, não reenvia nada.
- Com Atualizar saldo estoque desligado, nada é enviado.
- O reenvio segue os mesmos filtros do envio normal de saldo. Por exemplo, ficam de fora os anúncios Full da Amazon, os anúncios Full do Mercado Livre (exceto os que também operam Flex) e os anúncios do Mercado Livre que ainda não têm código do anúncio.
- O reenvio entra numa fila e é processado aos poucos: o saldo não chega ao canal no mesmo instante, e em integrações com muitos anúncios pode demorar.
Pré-requisito: privilégio Editar parametrizações empresa.
Como autenticar uma integração que pede autorização externa?
Para tipos que pedem autorização externa (a maioria dos marketplaces), o cadastro inicial deixa a integração com status Não Autenticado. Para concluir:
- Na linha da integração, clique em Autenticar Integração (ícone de cadeado).
- Uma janela pede confirmação. Confirme.
- O sistema abre uma nova aba com a URL de autenticação do canal externo (ex.: tela de login do Mercado Livre ou do Kwai Shop).
- Faça login com as credenciais do canal e autorize o idworks a acessar a conta.
- O canal redireciona de volta. Quando a autorização é confirmada, o status muda para Ativo.
Se a autorização expira ou é revogada (por exemplo, você desautorizou o idworks no painel do canal), o status volta para Erro — basta repetir o processo. Para integrações que não pedem autorização externa (apenas chave/senha), não há esse fluxo: preencha as credenciais nas parametrizações e o status passa direto para Ativo.
Em vários desses canais (o Kwai Shop, por exemplo), o idworks renova o acesso sozinho depois da primeira autorização: você só precisa repetir o cadeado se a autorização for revogada no painel do canal.
Quem clica no cadeado e o prazo no Mercado Livre
A autorização só começa com a sessão de quem está logado no idworks naquela conta: ao confirmar, a nova aba já abre com a sua sessão. Se o link for aberto sem uma sessão válida dessa conta — um link antigo, uma aba que ficou aberta por muito tempo, uma sessão de outra conta —, a nova aba mostra um texto no formato {"errorMessage":"[BadRequest] - ..."} (os acentos podem aparecer em código, como \u00e3) com a mensagem:
Sessão inválida ou expirada. Entre na idworks e clique no cadeado da integração de novo.
Se o idworks não conseguir conferir a sessão na hora, a mensagem é Não foi possível conferir a sua sessão agora. Tente de novo em instantes., com o prefixo [Retry] - no lugar de [BadRequest] - . Espere um pouco e clique no cadeado de novo. Em vez de copiar e enviar o link para outra pessoa, peça para quem tem o login do canal entrar no idworks e clicar no cadeado.
No Mercado Livre, o retorno do canal vale uma única vez e por 15 minutos depois do clique no cadeado. Se o login no canal passar desse prazo, ou se você voltar a usar uma aba antiga da autorização, aparece, no mesmo formato:
Autorização expirada ou já usada. Volte à tela da integração e clique no cadeado de novo.
Conclua o login e a autorização no canal sem pausa. Se o prazo passar, volte à tela Integrações e clique no cadeado outra vez.
Como verificar se a integração está funcionando?
Depois de salvar as parametrizações, use o botão Validar credenciais da Configuração (quando disponível) — o idworks faz uma chamada síncrona ao sistema externo para confirmar que as credenciais respondem. O resultado aparece na tela com mensagem de sucesso ou de erro técnico (ex.: "401 Unauthorized", "timeout").
Quando a verificação não é suportada pelo tipo, o idworks devolve a mensagem "Integração não tem consulta de status" — nesse caso, o teste é indireto: salve as parametrizações e observe se ações automáticas (sincronização de anúncios, importação de pedidos) começam a chegar.
Para acompanhar a saúde da integração no dia a dia, observe o Status na listagem: enquanto estiver Ativo, está tudo certo. Se entrar em Erro, abra a integração para ver o que mudou nas credenciais.
Minha integração parou de funcionar: como reautenticar?
É o problema mais comum com marketplaces (Mercado Livre, Magalu, Shopee, Kabum, TikTok, Kwai Shop, Tray, entre outros) e algumas plataformas de e-commerce: de um dia para o outro os anúncios param de sincronizar, os pedidos deixam de chegar ou o preço/estoque não atualiza. Quase sempre a causa é a autorização que expirou ou foi revogada — não um defeito no idworks.
Como identificar. Abra Configurações → Integrações → Minhas Integrações e olhe a coluna Status da integração afetada:
- Erro — a autorização foi revogada ou expirou. Mensagens típicas do canal são "caller not authorized", "token inválido", "token expirado" ou "credenciais não validam".
- Não Autenticado — a integração nunca concluiu a autorização (ou ela caiu por completo).
Outras situações que levam a isso: você (ou alguém da equipe) trocou a senha no painel do próprio canal, desautorizou o idworks no painel do marketplace, ou o canal passou por migração e exige um novo consentimento.
Como reautenticar (canais com login externo). Para a maioria dos marketplaces:
- Na linha da integração, clique em Autenticar Integração (ícone de cadeado). Faça isso logado no idworks, na conta dona da integração.
- Confirme. O sistema abre uma nova aba com a tela de login do canal.
- Faça login com a conta daquele marketplace (não com o usuário do idworks) e autorize o acesso, marcando todas as permissões pedidas. No Mercado Livre, conclua em até 15 minutos (ver Como autenticar uma integração que pede autorização externa?).
- O canal redireciona de volta e o status muda para Ativo.
Como reautenticar (canais com chave/senha). Alguns canais e plataformas não usam login externo — eles validam por chave/token informados nas parametrizações. Nesses casos, abra a Configuração (ícone de engrenagem) da integração, gere uma chave nova no painel do canal quando necessário, apague o conteúdo do campo de credenciais (os ********, ou os pontos que os representam nos campos do tipo Senha), digite a chave nova, salve e use Validar credenciais para confirmar.
Depois de reautenticar, o status volta para Ativo e as ações automáticas (sincronizar anúncios, importar pedidos, atualizar preço/estoque) voltam a rodar sozinhas. Você não precisa recadastrar a integração nem refazer os De-Paras — eles continuam preservados. Se o status voltar a cair logo em seguida, confira no painel do canal se o idworks continua autorizado e se a conta do canal não está com pendências.
Erros estranhos que na verdade são integração caída: como reconhecer?
Nem sempre o sintoma aponta direto para a integração. Muitas vezes o canal está em Erro ou Não Autenticado e o que aparece para você é uma mensagem que parece falar de outra coisa — estoque, imagem, preço, pedido. Quando o problema acontece em vários SKUs, vários anúncios ou vários pedidos ao mesmo tempo (e não em um item isolado), suspeite primeiro da integração.
Sinais comuns de que a causa é a autorização expirada, e não o cadastro do produto:
| O que você vê | O que costuma ser de verdade |
|---|---|
| Erro ao sincronizar estoque de vários SKUs de uma vez, mesmo com os anúncios ativos no canal | A integração precisa ser reautenticada. |
| Mensagens como "token inválido", "token expirado", "credenciais inválidas", "acesso negado", "caller not authorized" | A autorização caiu — reautentique. |
| Um pedido não aparece no idworks, mas outros do mesmo canal aparecem | A autorização caiu durante a importação daquele pedido. Reautentique e ele entra. |
| Pedido fica pendente dizendo que o status não permite criar o pedido, mas no canal ele está normal | Credenciais inválidas impedem o idworks de ler os dados completos do pedido. |
| Ao sincronizar anúncio, aparece "o produto precisa de pelo menos uma imagem principal" — mas o produto já tem fotos | Quando as credenciais expiram, o canal devolve mensagens enganosas como essa. Reautentique antes de mexer no cadastro. |
| Ao atualizar preço, aparece "credenciais expiradas" ou "o acesso expirou" | A integração precisa ser reautenticada. |
Como confirmar. Abra Configurações → Integrações → Minhas Integrações e olhe a coluna Status do canal envolvido. Se estiver em Erro ou Não Autenticado, a causa é a autorização — siga o passo a passo de reautenticar. Só depois de o status voltar a Ativo é que faz sentido investigar o cadastro do produto. Se o problema for em um único item e o status do canal estiver Ativo, aí sim a causa está no anúncio/produto, não na integração.
Reautenticei a integração: e os pedidos que faltaram?
Depois que o status volta para Ativo, você não precisa lançar nada à mão. O idworks volta a buscar no canal os pedidos que ficaram para trás e eles caem sozinhos — em geral aos poucos, conforme o sistema reprocessa, e não todos no mesmo segundo. É comum ver, por exemplo, o canal mostrar 35 pedidos e o idworks ainda com 19 logo após reautenticar; em alguns minutos os que faltavam terminam de entrar.
O que esperar depois de reautenticar:
- Pedidos atrasados entram automaticamente, aos poucos. Aguarde alguns minutos antes de concluir que algum ficou de fora.
- Anúncios, preço e estoque voltam a sincronizar sozinhos.
- De-Paras, parametrizações e nome da integração ficam preservados — nada precisa ser recadastrado.
Se, depois de um tempo, ainda faltar algum pedido específico que já está finalizado no canal, ele pode ter ficado fora da janela de importação. Nesse caso, confira o filtro de período/status de importação nas parametrizações daquele canal; persistindo, abra um chamado informando o número do pedido no canal para análise pontual.
O canal pede para desvincular e revincular o idworks (Mercado Livre, Magalu): como faço?
Em alguns casos, refazer a autenticação só pelo idworks não resolve — o status continua em Erro mesmo depois de você clicar em Autenticar Integração. Isso costuma acontecer quando:
- a integração foi autorizada com a conta errada do canal (outra loja, outro login); ou
- o canal manteve uma autorização antiga "presa" que precisa ser removida antes de criar uma nova.
Nesses casos a correção é feita dentro do painel do próprio canal de vendas, não no idworks. O caminho geral é:
- Acesse o painel do canal de vendas (Mercado Livre, Magalu, etc.) com a conta correta da loja.
- Vá até a área de aplicativos/integradoras autorizadas do canal e remova (desvincule) a autorização do idworks.
- Autorize o idworks novamente no painel do canal.
- Para o vínculo dar certo, use o mesmo navegador e esteja logado ao mesmo tempo: na conta correta do canal de vendas e no idworks. Isso evita autorizar a integração na conta errada.
- Volte ao idworks, em Minhas Integrações, e clique em Autenticar Integração na linha do canal para concluir.
- Confirme que o Status voltou para Ativo.
No Magalu, essa autorização fica na lista de integradoras autorizadas dentro do portal do parceiro — remova o idworks de lá e autorize de novo. A tela do canal pode mudar de lugar com o tempo; se você não encontrar a opção, fale com o suporte do próprio canal de vendas para localizar onde gerenciar as integradoras.
Depois de revincular no canal, o status no idworks volta a Ativo e as ações automáticas voltam a rodar. Não é preciso recadastrar a integração nem refazer os De-Paras.
Recebi um e-mail avisando que meu acesso vai expirar: o que fazer?
Alguns canais (a Shopee, por exemplo) limitam o tempo de cada autorização — na Shopee, a conexão vence depois de 365 dias e o canal avisa por e-mail com antecedência (em geral algumas semanas antes), pedindo para gerar um novo acesso. Quando a autorização vence, os pedidos param de entrar no idworks até você renovar.
Você não precisa esperar o acesso vencer nem abrir chamado para gerar um "link": a renovação é a mesma reautenticação que você faz a qualquer momento, e pode ser feita por você:
- Acesse Configurações → Integrações → Minhas Integrações.
- Na linha do canal avisado (ex.: Shopee), clique em Autenticar Integração (ícone de cadeado).
- Confirme; o sistema abre a tela de login do canal em uma nova aba.
- Faça login com a conta daquele canal e autorize o acesso, liberando todas as permissões pedidas.
- Confirme que o Status voltou para Ativo.
Depois da renovação, os pedidos que ficaram parados entram automaticamente (ver Reautenticei a integração: e os pedidos que faltaram?). Renovar antes do vencimento evita ficar sem importar pedidos no intervalo — vale fazer assim que o e-mail de aviso chegar.
Como editar o nome e o status de uma integração?
Na linha da integração, clique no ícone Editar. Uma janela abre com:
- Status — seletor Ativo / Inativo. Use para suspender uma integração temporariamente sem perder os dados (ela some das ações automáticas mas continua na listagem). No Mercado Livre e no WhatsApp próprio há diferenças, descritas abaixo.
- Nome da Integração — texto livre.
Clique em Salvar. Para mexer nas parametrizações (URL, credenciais, opções de comportamento), use Configuração (o ícone de engrenagem na mesma linha), não esta janela.
Mercado Livre: inativar revoga a autorização
Em integração do Mercado Livre, salvar com o Status em Inativo revoga a autorização do idworks no próprio Mercado Livre (o aplicativo sai das aplicações conectadas do vendedor) e apaga os tokens gravados na integração. As parametrizações, os De-Paras e o nome continuam. Para voltar a usar, mude o Status para Ativo e clique em Autenticar Integração para autorizar de novo (ver Como autenticar uma integração que pede autorização externa?).
Se o Mercado Livre não confirmar a revogação, o idworks recusa a alteração e o status não muda. A mensagem informa o motivo:
Mercado Livre não confirmou a revogação (HTTP <código>); tente novamente.Não foi possível confirmar a revogação no Mercado Livre; tente novamente.Não foi possível renovar a credencial para revogar no Mercado Livre; tente novamente.Faltam dados para revogar a autorização do Mercado Livre.MeliSecret ausente para revogar a autorização do Mercado Livre.
Nas três primeiras, tente salvar de novo em instantes; nas duas últimas, fale com o suporte. Se a integração não tem token gravado (nunca foi autenticada, por exemplo), ou se o Mercado Livre já recusa os tokens gravados (a autorização já foi removida no painel do canal), não há o que revogar e a alteração segue normalmente.
WhatsApp próprio: inativar desconecta o número
Em integração do tipo WhatsApp-proprio, salvar com o Status em Inativo desconecta o número e nenhuma mensagem nova entra no idDesk. As parametrizações e o nome continuam. Para voltar a usar, mude o Status para Ativo e clique em Autenticar Integração (cadeado): a página Conectar WhatsApp mostra o QR Code de novo para você ler com o celular.
Se a desconexão falhar, o status muda mesmo assim e as mensagens novas continuam fora do idDesk. Se o número ainda aparecer em Aparelhos conectados no celular, salve de novo como Inativo: cada salvamento repete a desconexão. Se continuar aparecendo, fale com o suporte.
Pré-requisito: privilégio Editar parametrizações empresa.
Como buscar e filtrar minhas integrações?
A aba Minhas Integrações já carrega todas as integrações ativas e inativas da empresa, ordenadas pelo nome do tipo. Para localizar uma específica:
- Filtros nas colunas (cabeçalho da tabela) — cada coluna (Logo, Canal de Venda, Nome da Integração, Reputação, Código, Conta, Status) tem busca textual. Clique no ícone de filtro na coluna e informe o valor.
- Filtro de Status — usa as opções fixas Ativo, Erro, Não Autenticado, Inativo. Útil para listar só o que está em erro ou ainda não foi autenticado.
- Filtro Conta — disponível quando a empresa tem mais de uma conta cadastrada.
Como explorar as integrações disponíveis no catálogo?
Clique na aba Integrações Disponíveis. O catálogo aparece agrupado por categoria (Canal de Venda, Banco, Adquirente, Transportadora, etc.). Cada categoria expande/recolhe com um clique. Use o campo Buscar integração no topo para filtrar pelo nome do canal — a busca casa em qualquer parte do nome.
Cada item do catálogo mostra o logo (ou nome textual) e um botão + para ativar. A ativação abre o modal de cadastro descrito na pergunta de criação.
O que é a ação "De-Paras" em integrações de Marketplace?
Para integrações de Canal de Venda e de Adquirente, a linha mostra a ação De-Paras (ícone de seta dupla). Ela abre a janela <integração> - Integração: <código>, onde você mapeia, em três etapas (cada uma gravada pelo botão Salvar etapa), entidades do canal externo para as suas entidades internas:
- Armazém — qual armazém do canal corresponde a qual armazém de estoque interno, com o tipo de pedido e o status de pedido que o sistema deve baixar do canal.
- Transportadora — qual transportadora do canal cai em qual transportadora interna.
- Tipo de Pagamento — qual pagamento do canal vira qual tipo de pagamento interno.
Esse mapeamento é o que permite que pedidos do canal "encaixem" corretamente nas estruturas internas do idworks. A ação aparece nas integrações de Canal de Venda e de Adquirente, para quem tem o privilégio Editar parametrizações empresa, e só fica habilitada com status Ativo (nos demais status, o ícone aparece desabilitado).
Como excluir uma integração?
Na janela de edição da integração (acessada pelo ícone Editar), clique em Deletar no rodapé. Uma janela de confirmação pede o nome da integração para confirmar. Confirme para excluir.
A exclusão é lógica para a integração — ela é marcada como inativa e some da listagem. Os vínculos com:
- Parametrizações — apagadas fisicamente.
- Mapeamentos do Hub (categorias, marcas, transportadoras, pagamentos, política comercial, variações, armazéns) — apagados fisicamente.
A integração em si fica preservada no banco (caso precise auditar), mas todas as configurações são removidas. Para restaurar, é preciso cadastrar e configurar de novo.
Mercado Livre. Ao excluir uma integração do Mercado Livre, o idworks também revoga a autorização no canal (o aplicativo sai das aplicações conectadas do vendedor) e apaga os tokens. A revogação acontece depois das verificações de vínculos que bloqueiam a exclusão. Se o Mercado Livre não confirmar a revogação, a exclusão é recusada e nada muda; a mensagem é:
Não foi possível concluir a exclusão; confirme a revogação no Mercado Livre e tente novamente.
Tente excluir de novo em instantes. Se a integração não tem token gravado, ou se o Mercado Livre já recusa os tokens gravados (por exemplo, você já removeu o idworks no painel do canal), não há o que revogar e a exclusão segue.
Pré-requisito: privilégio Deletar parametrizações empresa.
Por que não consigo excluir uma integração?
A exclusão é bloqueada quando a integração ainda tem vínculos ativos e, no Mercado Livre, quando o canal não confirma a revogação. As regras dependem da categoria:
| Categoria | Bloqueio | Mensagem |
|---|---|---|
| Transportadora | Há fornecedor ativo vinculado a esta integração. | Existe fornecedor vinculado a essa integração, remover antes de excluir a integração |
| Banco / Adquirente / Gateway | Há conta bancária ativa vinculada a esta integração. | Existe conta bancária vinculada a essa integração, remover antes de excluir a integração |
| Canal de Venda e demais com anúncios | Há anúncios no Hub apontando para esta integração. | Integração possui anúncios, excluir antes de deletar a integração |
| Mercado Livre | O Mercado Livre não confirmou a revogação da autorização do idworks. Tente de novo em instantes. | Não foi possível concluir a exclusão; confirme a revogação no Mercado Livre e tente novamente. |
Para destravar um vínculo:
- Vá até a tela apropriada (Fornecedores, Contas Bancárias, ou Hub Anúncios) e remova ou troque os vínculos ativos. Para fornecedor/conta inativos, o sistema já desvincula automaticamente.
- Volte à tela de Integrações e tente excluir novamente.
No Mercado Livre, se a mensagem for a da revogação, não há vínculo para remover: tente excluir de novo em instantes.
O que acontece com os dados quando excluo uma integração?
| O que acontece com... | Ação |
|---|---|
| A integração em si | Marcada como inativa e oculta da listagem. |
| Parametrizações configuradas | Apagadas fisicamente do banco. Não é possível recuperar — se cadastrar de novo, precisa preencher tudo de novo. |
| Mapeamentos do Hub (categorias, marcas, transportadoras, pagamentos, política comercial, variações, armazéns) | Apagados fisicamente. |
| Autorização no Mercado Livre (só integração do Mercado Livre) | Revogada no canal, com os tokens apagados. Se o Mercado Livre não confirmar a revogação, a exclusão não acontece. |
| Número do WhatsApp próprio (só integração do tipo WhatsApp-proprio) | Desconectado, e a conexão é apagada. Mensagens novas deixam de entrar no idDesk. Se a desconexão falhar, a exclusão segue mesmo assim e as mensagens novas continuam fora do idDesk; se o número ainda aparecer em Aparelhos conectados no celular, fale com o suporte. |
| Anúncios | Bloqueio: a exclusão não passa enquanto houver anúncios. Você precisa excluir os anúncios antes (em Hub Anúncios). |
| Fornecedores ativos vinculados | Bloqueio: precisam ser desvinculados antes. |
| Contas bancárias ativas vinculadas | Bloqueio: precisam ser desvinculadas antes. |
| Fornecedores e contas bancárias inativos vinculados | Desvinculados automaticamente (o vínculo com esta integração é removido desses registros). |
| Histórico de pedidos, contas a pagar, anúncios antigos | Preservado — os registros ficam com o id da integração antiga (que continua no banco) e funcionam normalmente para consulta histórica. |
Boas práticas para gerenciar integrações
Integrações bem cuidadas evitam pedido que não entra, anúncio que para de sincronizar e horas perdidas mexendo no cadastro do produto à toa. Recomendações:
- Dê um nome descritivo a cada integração na hora de ativar. Como você pode ter mais de uma instância do mesmo tipo (duas contas de Mercado Livre, três bancos), um nome como "Mercado Livre - Loja Principal" evita confundir qual é qual na hora de configurar ou autenticar.
- Renove a autorização assim que o canal avisar por e-mail que vai expirar. Alguns canais limitam o tempo de cada conexão (a Shopee vence em 365 dias); renovar antes do prazo evita ficar sem importar pedidos no intervalo — e você mesmo faz, sem abrir chamado.
- Quando o erro aparece em vários SKUs, anúncios ou pedidos ao mesmo tempo, olhe o Status da integração primeiro. Mensagens enganosas (produto "sem imagem", "credenciais expiradas") quase sempre são autorização caída, não defeito no cadastro — confira o status antes de mexer no produto.
- Reautentique pelo botão Autenticar Integração em vez de recadastrar. Depois de reautenticar, os De-Paras, as parametrizações e o nome continuam preservados e os pedidos atrasados entram sozinhos — recadastrar do zero só dá retrabalho.
- Use Validar credenciais depois de salvar as parametrizações. A checagem confirma na hora se as credenciais respondem, em vez de você descobrir o problema só quando um pedido deixa de chegar.
- Suspenda com o status Inativo em vez de excluir quando for pausa temporária. Inativar tira a integração das ações automáticas mas preserva as parametrizações e os mapeamentos; excluir apaga tudo de vez, e você teria de preencher tudo de novo. No Mercado Livre, inativar também revoga a autorização no canal: ao reativar, clique em Autenticar Integração de novo.
- Antes de tentar excluir, remova os vínculos ativos (fornecedor, conta bancária, anúncios). O sistema bloqueia a exclusão enquanto houver vínculo ativo; desfazer os vínculos primeiro evita a mensagem de bloqueio.
Resumo de parametrizações
A tela de Integrações funciona como hub de instalação/configuração das integrações cadastradas. Cada integração instalada tem suas próprias parametrizações dentro de Configurações → Parametrizações (cada integração vira um submenu próprio: Cielo, Rede, MercadoPago, MercadoLivre, Amazon, Magalu, Shopee, etc.). A lista exata depende das integrações que a empresa tem ativas — consulte a FAQ específica de cada integração para detalhes.
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. Quando o usuário não tem o privilégio, a ação correspondente fica oculta na tela (o botão Deletar é a exceção: aparece desabilitado).
| Privilégio | Libera |
|---|---|
| Visualizar integrações | Acesso à tela e à listagem (aba Minhas Integrações). |
| Criar parametrizações empresa | Aba Integrações Disponíveis (sem o privilégio, a aba não aparece) e ativar uma nova integração (botão + no catálogo). |
| Editar parametrizações empresa | Abrir a Configuração (engrenagem), editar nome e status, fazer o mapeamento de De-Paras e validar credenciais. |
| Deletar parametrizações empresa | Excluir integrações (botão Deletar na janela de edição). |
O botão Autenticar Integração não depende de privilégio: aparece para quem acessa a tela, sempre que o tipo da integração pede autorização externa.