Kabum
A integração com o Kabum conecta a sua conta ao idworks e sincroniza os fluxos correspondentes ao canal — credenciais, regras de sincronização de produtos, importação de pedidos, conciliação financeira e demais ações específicas dele. A configuração reúne 22 parâmetros distribuídos em 4 grupo(s).
Antes de configurar, ative a integração em Configurações → Integrações (aba Integrações Disponíveis), preencha o nome interno e (quando o tipo exigir) passe pelo fluxo de autenticação. A partir daí, os parâmetros abaixo ficam disponíveis em Configurar parâmetros.
Categoria no catálogo do idworks: Marketplace.
Índice
Conceito
Cadastro e autenticação
Parâmetros por grupo
Pedidos e expedição
- Como funcionam os pedidos Kabum Entregas?
- O XML da nota fiscal é enviado para a Kabum?
- Erros ao marcar o pedido como enviado ou ao buscar a etiqueta
Referência rápida
O que é a integração Kabum?
É a conexão entre o canal Kabum e o idworks. Ela controla como dados fluem entre os dois sistemas — depende do tipo da integração (a categoria neste caso é Marketplace), mas em geral cobre uma combinação de credenciais, regras de sincronização, gatilhos automáticos e parâmetros de conciliação.
📍 Onde: menu lateral → Configurações → Integrações → aba Integrações Disponíveis → Kabum.
Como ativar a integração?
- Acesse Configurações → Integrações.
- Na aba Integrações Disponíveis, busque por Kabum e clique no botão +.
- Preencha:
- Conta (apenas multi-conta) — empresa dona da integração.
- Nome da Integração — texto livre. Útil para distinguir várias instâncias do mesmo tipo.
- Clique em Salvar.
A integração aparece imediatamente em Minhas Integrações. Dependendo do tipo, o status inicial é Ativo (quando só requer credencial fixa) ou Não Autenticado (quando depende de autenticação externa).
Pré-requisito: privilégio Criar parametrizações empresa.
Como autenticar e validar as credenciais?
Preencha o grupo Credenciais de Acesso (ver tabela abaixo). Quando a integração pede uma autorização externa (o canal abre a tela de login dele para você liberar o acesso), clique em Autenticar Integração na linha da integração (ícone de cadeado) — uma nova aba abre o login do canal e, ao confirmar, a conexão fica liberada. Para integrações com credencial fixa (usuário/senha/chave), basta preencher os campos e salvar.
Depois de salvar, use a ação Verificar credenciais (quando disponível) para confirmar que o canal responde. O status na listagem reflete o resultado: Ativo = OK, Erro = credencial inválida ou revogada, Não Autenticado = falta concluir o fluxo de autorização.
Pré-requisito: privilégio Editar parametrizações empresa.
Credenciais de Acesso
3 parâmetro(s).
| Parâmetro | Tipo | Para que serve |
|---|---|---|
| Authorization | Senha | Token de acesso à integração |
| Shop Id | Inteiro | ID da loja enviado pelo canal |
| Validar credenciais | Botão | Clique para validar as credenciais informadas |
Integração de Vendas
7 parâmetro(s).
| Parâmetro | Tipo | Para que serve |
|---|---|---|
| Empresa Faturadora | Lista | Empresa responsável pelo faturamento dos pedidos, caso seja diferente da principal. |
| Excluir valor frete na NF para PF | Sim/Não | Ative se quiser excluir o valor do frete na Nota Fiscal quando a venda por para pessoa física (PF) |
| Importar pedidos | Sim/Não | Ative se quiser que a idworks integre os pedidos feitos no canal de vendas. |
| Detalhar forma de pagamento | Sim/Não | Importar o detalhe da forma de pagamento utilizado pelo cliente, como cartão de crédito, boleto e etc. Exige realizar o DE/PARA de todas as formas |
| Fechar pedido automaticamente | Sim/Não | Quando marcado, o idworks fecha o pedido integrado do canal de vendas através do hub. Se desmarcado, o pedido quando integrado permanece com o status de aberto para atualização manual. |
| Margem mínima desejável | % | Percentual mínimo de margem de contribuição para os pedidos desta integração. Quando a margem do pedido fica abaixo do valor configurado, o pedido é enviado para aprovação de margem em vez de seguir o fluxo automático. |
| Checar taxa/imposto efetivo do pedido | Sim/Não | Ao ativar, o sistema valida a margem de contribuição no fechamento do pedido. Exige que a Margem mínima desejável (ou a taxa efetiva) esteja preenchida. |
Integração de Produtos
11 parâmetro(s).
| Parâmetro | Tipo | Para que serve |
|---|---|---|
| Atualizar saldo estoque | Sim/Não | Ative se quiser que a idworks atualize o saldo de estoque na integração. |
| Valor de ajuste no preço | Decimal | Valor em R$ fixo a ser somado ao preço por (base) para compor o preço de venda, se existir cobrança de frete |
| Valor de ajuste no preço frete grátis | Decimal | Valor em R$ fixo a ser somado ao preço por (base) para compor o preço de venda, se houver frete grátis e se o preço base for maior que a regra de frete grátis |
| Percentual de ajuste no preço | % | Valor percentual a ser somado ao preço por (base) para compor o preço de venda, se existir cobrança de frete |
| Percentual de ajuste no preço frete grátis | % | Valor percentual a ser somado ao preço por (base) para compor o preço de venda, se houver frete grátis e se o preço base for maior que a regra de frete grátis |
| Frete grátis? | Sim/Não | Ative se quiser oferecer Frete Grátis acima de algum valor no marketplace |
| Valor frete grátis | Decimal | Qual o valor mínimo para conceder Frete Grátis no marketplace? |
| Arredondamento dos centavos do preço | Decimal | Valor em centavos para arredondar o preço de venda. Preencha entre 0,01 e 0,99. |
| Utilizar título como nome SKU | Sim/Não | Utilizar o campo título como nome do SKU ao enviar para o canal |
| Armazéns para somar quantidade | Lista múltipla | Selecionar os armazéns que deve somar a quantidade para enviar aos canais de venda. Caso não seja preenchido, será enviado a quantidade do armazém que esta no de/para |
| Percentual disponibilidade de estoque | % | Valor base para utilizar do estoque em percentual. Ex. se tiver 100 unidades disponíveis e o percentual for 80% será enviado 80 para o canal |
Configurações Gerais
1 parâmetro(s).
| Parâmetro | Tipo | Para que serve |
|---|---|---|
| Url para cotação de frete | Cópia | URL para enviar ao canal de vendas para cotação de frete com as regras e tabelas na idworks |
Como funcionam os pedidos Kabum Entregas?
No Kabum Entregas quem organiza a coleta é o canal: você fatura e embala, e a Kabum manda o parceiro logístico buscar. O idworks reconhece esses pedidos pelo código de transportadora que a Kabum envia — CLT_OPERATOR, PTG_LOJA ou AGC_OPERADOR — e usa um fluxo de expedição diferente do envio por conta da loja.
Antes de importar o primeiro pedido, cadastre o De-Para de Transportadora da integração para esses três códigos. Sem o mapeamento, o pedido não é criado e a integração acusa que falta o De-Para informando o código que veio do canal.
Como fica o fluxo depois disso:
- Faturamento — você emite a nota normalmente. O idworks envia à Kabum os dados da NF-e (número, série, data de emissão e chave de acesso) e, em seguida, o arquivo XML da nota.
- Marcar como enviado — o idworks consulta o pedido na Kabum, confere se a nota foi aceita, localiza a coleta gerada pelo canal, grava no pedido a transportadora que a Kabum designou e sinaliza a coleta como pronta para retirada. Nesse fluxo você não informa código de rastreio: quem gera é o canal.
- Etiqueta — depois que a coleta fica pronta para retirada, a Kabum disponibiliza a etiqueta. Use a ação Etiqueta canal do pedido para imprimir: o idworks busca primeiro a versão térmica publicada pela Kabum e, se o canal só tiver a versão em PDF, entrega essa. A etiqueta da Kabum é a válida para a coleta — não use a etiqueta de embarque padrão do idworks.
A etiqueta baixada fica guardada por 3 dias: reimpressões nesse período saem na hora e sempre com o mesmo arquivo. Se a Kabum reemitir a etiqueta do pedido dentro desse prazo, a versão nova só passa a ser buscada depois que o prazo vence.
Nos pedidos que não são Kabum Entregas (frete por conta da loja), o fluxo antigo continua igual: o idworks envia à Kabum a transportadora, o código e o link de rastreio do pedido, e a etiqueta é a do seu próprio embarque.
O XML da nota fiscal é enviado para a Kabum?
Sim. Desde a atualização do canal, o faturamento envia duas coisas em sequência: primeiro os dados da nota (número, série, data de emissão e chave de acesso) e depois o arquivo XML da NF-e.
Se a Kabum recusar o arquivo, o pedido registra "Falha no envio do XML" seguido do motivo devolvido pelo canal. Enquanto a Kabum não validar a nota, a expedição do pedido fica travada — ao tentar marcar como enviado, o idworks devolve o motivo apontado pelo canal. Nesses casos:
- Leia o motivo no histórico do pedido — costuma apontar divergência entre a nota e o pedido (CNPJ/CPF do destinatário, valor total, itens ou chave de acesso).
- Corrija a nota (cancelamento e reemissão, quando for o caso).
- Refaça o envio da nota ao canal pelo pedido.
Erros ao marcar o pedido como enviado ou ao buscar a etiqueta
| Mensagem | O que significa | O que fazer |
|---|---|---|
| "Erro ao atualizar status no canal, motivo: ... - Validar NFe e reenviar ao canal." | A Kabum marcou a nota do pedido como inválida e informou o motivo. | Corrija a nota conforme o motivo e reenvie a nota ao canal antes de tentar expedir de novo. |
| "Não foi possível consultar o pedido na Kabum para validar a NF" | O canal não respondeu à consulta do pedido. | Tente de novo em alguns minutos; se persistir, valide as credenciais da integração. |
| "Shipment ainda não gerado para o pedido na Kabum" | A Kabum ainda não criou a coleta desse pedido. | Aguarde o canal gerar a coleta e repita a ação. |
| "Pedido já processado na Kabum, status atual: ..." | O pedido já passou da etapa de expedição no canal. | Nenhuma ação — é apenas informativo, o pedido segue no idworks. |
| "Etiqueta ainda não disponível, pedido precisa estar marcado como ready for pick up" | A etiqueta só existe depois que a coleta é sinalizada como pronta para retirada. | Marque o pedido como enviado primeiro; depois imprima a Etiqueta canal. |
| "Pedido não é Kabum Entregas, verificar de/para de transportadora" | O pedido não veio com um dos códigos do Kabum Entregas. | Confirme a modalidade no painel da Kabum e revise o De-Para de Transportadora da integração. |
| "Nota fiscal não emitida" | A etiqueta do canal só é liberada com o pedido faturado. | Emita a nota fiscal e tente novamente. |
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 de Integrações e a esta página de configuração. |
| Criar parametrizações empresa | Ativar a integração (botão + no catálogo). |
| Editar parametrizações empresa | Configurar parâmetros, editar nome e status, autenticar e validar credenciais. |
| Deletar parametrizações empresa | Excluir a integração. |