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, IDs externos, flags 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 categorias, marcas, transportadoras etc. para tipos de Marketplace), Editar (nome e status) e Configurar parâmetros (a aba lateral 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 (Marketplace, ERP, Banco, Adquirente, Transportadora, Fiscal, 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?
- 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?
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. | Aba Configurar parâmetros (acionada pelo ícone 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 principais são:
- Marketplace — Mercado Livre, Magalu, Amazon, Shopee, Americanas, Carrefour, Via, Madeira Madeira, Webcontinental, B2W, e muitos outros canais de venda.
- Banco — bancos para envio de pagamentos e conciliação de extrato (Stark Bank, Itaú, Sicredi, Inter, etc.).
- Adquirente — adquirentes/processadoras de cartão para conciliação financeira (Stone, Cielo, Rede, Getnet, Pagar.me, etc.).
- Gateway de pagamento — gateways usados em e-commerce próprio ou cobrança recorrente.
- Transportadora — Correios, Loggi, Total Express, Intelipost, Jadlog, Mandaê, etc., para cotação de frete, geração de etiqueta e rastreamento.
- Fiscal — emissão de NF-e, NFC-e, NFS-e (Webmania, Bling, etc.), GNRE, SPED.
- E-mail — provedores SMTP para disparar e-mails transacionais.
- Outras — ERPs (idworks tem um tipo próprio para a integração interna), CRM, BI, atendimento, automação de produção.
Cada categoria muda o que aparece na lista de parametrizações e que ações fazem sentido (ex.: De-Paras só aparece em Marketplace; 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. |
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 (ReputationLevel) 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, fiscal), 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 (Marketplace, 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 Configurar parâmetros 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.
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).
- 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.
Como verificar se a integração está funcionando?
Depois de salvar as parametrizações, use a ação Verificar credenciais (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.
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).
- Nome da Integração — texto livre.
Clique em Salvar. Para mexer nas parametrizações (URL, credenciais, flags), use Configurar parâmetros (a outra ação na mesma linha), não esta janela.
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 (Marketplace, 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 Marketplace (e algumas de canal especial), a linha mostra a ação De-Paras (ícone de seta dupla). Ela abre o Hub Modal, onde você mapeia entidades do canal externo para as suas entidades internas:
- Categorias — qual categoria do canal corresponde a qual categoria interna.
- Marcas — qual nome de marca recebido do canal aponta para qual marca cadastrada.
- Transportadoras — qual modalidade de frete do canal cai em qual transportadora interna.
- Formas de pagamento — qual pagamento do canal vira qual tipo de pagamento interno.
- Política comercial — quais regras do canal se aplicam.
- Variações e Armazéns — mapeamento adicional para integrações de estoque.
Esse mapeamento é o que permite que pedidos do canal "encaixem" corretamente nas estruturas internas do idworks. A ação só aparece quando a integração é da categoria Marketplace (ou outras categorias com mapeamento equivalente) e tem status Ativo.
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 (
CompanyParameters) — apagados 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.
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. 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 |
| Marketplace 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 |
Para destravar:
- 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.
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 (Status = 0, Show = 0). Some 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. |
Anúncios (HubProduct) | 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. |
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 desabilitada na tela.
| Privilégio | Libera |
|---|---|
| Visualizar integrações | Acesso à tela, à listagem e à aba Integrações Disponíveis. |
| Criar parametrizações empresa | Ativar uma nova integração (botão + no catálogo) e duplicar parametrizações. |
| Editar parametrizações empresa | Configurar parâmetros, editar nome e status, fazer mapeamento de De-Paras, autenticar e verificar credenciais. |
| Deletar parametrizações empresa | Excluir integrações (botão Deletar na janela de edição). |