Kwai Shop
A integração com o Kwai Shop conecta a sua loja do canal ao idworks: publicação e manutenção de anúncios, atualização de preço e estoque, importação automática de pedidos, envio da nota fiscal e geração da etiqueta.
⚠️ Antes de integrar, leia a seção de comissão. O Kwai não devolve ao idworks o valor da comissão cobrada em cada pedido. A taxa que aparece no resultado do pedido é calculada pelo idworks a partir do percentual e do valor fixo que você preenche na parametrização — e, em pedido com mais de um item, ela fica menor que a taxa real. Isso afeta diretamente margem e conciliação. Veja Como a comissão do Kwai é calculada no pedido? e Por que a comissão fica subestimada em pedido com mais de um item?.
Índice
Conceito
Cadastro e autenticação
Comissão e resultado do pedido
- Como a comissão do Kwai é calculada no pedido?
- Por que a comissão fica subestimada em pedido com mais de um item?
Anúncios e produtos
- O que o Kwai exige para publicar um anúncio?
- Como funcionam a categoria e a ficha técnica do Kwai?
- Por que o preço "de" (riscado) não muda quando eu atualizo o preço?
- Como o estoque é enviado ao Kwai?
- Como ativar e inativar um anúncio no Kwai?
Pedidos
- Como os pedidos do Kwai entram no idworks?
- Como enviar a nota fiscal ao Kwai?
- Como gerar a etiqueta e despachar o pedido?
Referência rápida
O que é a integração Kwai Shop?
É a conexão entre a sua loja no Kwai Shop e o idworks. Depois de autorizada, ela cobre o ciclo completo do canal: você publica anúncios a partir do Hub, mantém preço e estoque sincronizados, recebe os pedidos automaticamente, envia a nota fiscal ao canal e imprime a etiqueta oficial do Kwai.
📍 Onde: menu lateral → Configurações → Integrações → aba Integrações Disponíveis → use o campo Buscar integração e procure por Kwai.
O agrupamento do catálogo (a categoria em que o canal aparece na lista) é definido pela idworks e pode mudar. Se não encontrar expandindo as categorias, use a busca pelo nome.
Como ativar e autorizar a integração?
- Acesse Configurações → Integrações.
- Na aba Integrações Disponíveis, busque por Kwai 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 do mesmo canal.
- Clique em Salvar. A integração aparece em Minhas Integrações com status Não Autenticado.
- Na linha da integração, clique em Autenticar Integração (ícone de cadeado). Uma nova aba abre a tela de login do Kwai.
- Entre com a conta da loja no Kwai (não com o usuário do idworks) e autorize o acesso.
- O canal redireciona de volta com a mensagem de sucesso e o status passa para Ativo.
Não existe chave manual para digitar: toda a credencial do Kwai é obtida nesse fluxo de autorização e guardada pelo idworks.
Uma loja do Kwai só pode estar ligada a uma integração. Se você tentar autorizar a mesma loja em uma segunda integração, o idworks recusa avisando que aquela loja já está vinculada a outra integração — apague ou reaproveite a integração existente em vez de criar uma nova.
Depois de autorizar, use Validar credenciais para confirmar que o canal responde. O status na listagem reflete o resultado: Ativo = OK, Erro = autorização inválida ou revogada.
Pré-requisitos: privilégio Criar parametrizações empresa para ativar e Editar parametrizações empresa para autenticar e configurar.
A autorização caiu: como reconectar?
O idworks renova sozinho o acesso ao Kwai — você não precisa reautorizar de tempos em tempos. Mas, se a autorização for revogada no painel do Kwai (ou a loja ficar com pendências no canal), a renovação falha e o status da integração vai para Erro. A partir daí os anúncios param de sincronizar e os pedidos deixam de entrar.
Como resolver: repita o cadeado — Autenticar Integração na linha da integração, login na tela do Kwai, autorizar o acesso. Os De-Paras e os anúncios já cadastrados continuam preservados; não é preciso recadastrar nada.
Veja também Minha integração parou de funcionar: como reautenticar? na tela de Integrações.
Como a comissão do Kwai é calculada no pedido?
O Kwai não informa ao idworks quanto cobrou de comissão em cada pedido. Diferente da maioria dos marketplaces — em que a taxa chega junto com o pedido e é só registrar —, aqui o idworks calcula a taxa a partir dos valores que você preenche na parametrização da integração:
| Campo na parametrização | O que faz no cálculo |
|---|---|
| Percentual da taxa do marketplace | Percentual aplicado sobre o valor dos itens do pedido. É a base do cálculo. |
| Incluir frete no valor da comissão | Quando ativo, o frete entra na base sobre a qual o percentual é aplicado. |
| Valor adicional da taxa do marketplace | Valor fixo somado uma vez por pedido, depois do percentual. |
| Valor máximo incluir taxa adicional | Teto: o valor adicional só é somado quando o valor dos itens do pedido fica abaixo desse limite. |
Preencha esses campos com a tabela de comissão vigente da sua loja no Kwai (confirme os números no painel do próprio canal — a tabela é comercial e muda).
Duas armadilhas de preenchimento:
- Percentual em branco = pedido sem nenhuma taxa. Se o Percentual da taxa do marketplace ficar vazio, o idworks não grava comissão alguma no pedido, e o resultado sai com margem cheia — errada para mais.
- Valor máximo em branco = valor fixo ignorado. O Valor adicional da taxa do marketplace só entra no cálculo se o Valor máximo incluir taxa adicional também estiver preenchido. Deixando o teto vazio, a parte fixa nunca é somada.
Trate a comissão calculada como estimativa. O valor real é o que aparece no extrato do Kwai — e é por ele que a conciliação financeira deve ser fechada.
Por que a comissão fica subestimada em pedido com mais de um item?
Porque as duas taxas contam de formas diferentes: o Kwai cobra a parte fixa por item do pedido, enquanto o campo Valor adicional da taxa do marketplace do idworks é somado uma única vez por pedido. Em pedido com um item só, os dois coincidem. Em pedido com vários itens, a comissão que o idworks grava fica menor que a cobrada de verdade.
Exemplo (números apenas ilustrativos — use os da sua tabela):
Suponha percentual de 20% e valor adicional de R$ 4,00.
| Pedido | O Kwai cobra | O idworks calcula | Diferença |
|---|---|---|---|
| 1 item de R$ 100,00 | R$ 20,00 + R$ 4,00 = R$ 24,00 | R$ 20,00 + R$ 4,00 = R$ 24,00 | — |
| 3 itens de R$ 100,00 | R$ 60,00 + 3 × R$ 4,00 = R$ 72,00 | R$ 60,00 + R$ 4,00 = R$ 64,00 | R$ 8,00 a menos |
Quanto mais itens no pedido, maior o buraco — e ele aparece como margem otimista no resultado do pedido e nos relatórios de resultado.
O que fazer:
- Não feche margem só pelo resultado do pedido em vendas do Kwai com mais de um item. Confira a taxa real no extrato do canal.
- Na conciliação, espere diferença para maior no valor da taxa em pedidos multi-item — ela é esperada, não é erro de importação.
- Se a maior parte dos seus pedidos do Kwai tem vários itens, considere calibrar o Percentual da taxa do marketplace um pouco acima da tabela para compensar a parte fixa que não é multiplicada, e reavalie periodicamente contra o extrato.
O que o Kwai exige para publicar um anúncio?
Antes de sincronizar o anúncio, o produto precisa estar completo no cadastro, senão o idworks barra o envio:
- Peso e dimensões — altura, largura e comprimento, além do peso. Faltando qualquer um, o envio para com a mensagem "Produto precisa ter peso e dimensões (altura, largura e comprimento) cadastrados."
- Pelo menos uma imagem — o anúncio não sobe sem imagem. São enviadas até 9 imagens do produto.
- Categoria do canal preenchida na ficha do anúncio.
- Título (até 100 caracteres) e descrição (até 10.000 caracteres). Sem descrição preenchida na ficha do anúncio, o idworks usa a descrição do cadastro do produto.
As parametrizações de envio também precisam estar ligadas: com Atualizar produto desativado, a sincronização para com o aviso de que a atualização do produto está desativada nas configurações.
Anúncio com variações: o Kwai aceita até 3 características por variação (cor, tamanho, voltagem etc.). Quando o anúncio não tem variação nenhuma, o idworks cria uma variação Padrão identificada pelo código do SKU — é normal ver isso no canal.
Se um dos SKUs falhar, nada é publicado. Quando o idworks não consegue montar um SKU do anúncio, ele interrompe o envio inteiro em vez de publicar o anúncio sem aquele SKU — publicar pela metade faria o item que ficou de fora sumir do canal. Corrija o SKU apontado na mensagem e sincronize de novo.
Como funcionam a categoria e a ficha técnica do Kwai?
A árvore de categorias e os atributos da ficha técnica vêm do próprio Kwai — você não cadastra nada à mão:
- Na ficha do anúncio, escolha a categoria navegando pela árvore do canal. É preciso descer até a categoria final (a que não tem mais subcategorias).
- Com a categoria escolhida, o idworks busca no Kwai a lista de atributos daquela categoria e monta a ficha técnica com eles.
- Preencha os atributos na ficha do anúncio. Eles vão junto com o anúncio na sincronização.
A lista de categorias fica guardada por alguns dias para não precisar consultar o canal a cada anúncio; categorias novas do Kwai podem demorar um pouco a aparecer.
Por que o preço "de" (riscado) não muda quando eu atualizo o preço?
Porque a rotina de preço do Hub atualiza apenas o preço de venda. O preço "de" (o valor riscado, que o Kwai chama de preço de mercado) não é enviado por ela — o canal aceita a atualização de preço e simplesmente ignora o campo em silêncio, sem devolver erro. Ou seja: você altera o preço "de" no idworks, o log da sincronização mostra sucesso, e no anúncio o riscado continua o antigo.
O preço "de" só sobe quando o anúncio é reenviado (publicação ou nova sincronização do anúncio, não a rotina de preço). E, mesmo aí, o Kwai só aceita quando:
- o valor é o mesmo em todos os SKUs do anúncio; e
- é maior que o preço de venda.
Se os SKUs do anúncio tiverem preços "de" diferentes entre si, ou se o riscado não for maior que o preço por, o Kwai não recebe o campo e o anúncio sobe sem o riscado.
Como resolver: depois de mudar o preço "de", sincronize o anúncio (não só o preço) e confira se a política comercial gera o mesmo valor riscado para todos os SKUs do anúncio.
Como o estoque é enviado ao Kwai?
A rotina de estoque do Hub envia o saldo disponível de cada SKU, desde que Atualizar saldo estoque esteja ativo na parametrização.
Duas particularidades do Kwai:
- O canal não aceita receber saldo sem preço. Por isso, quando Atualizar preço está desativado, o idworks primeiro lê o preço atual no Kwai e devolve esse mesmo valor junto com o saldo — assim a sincronização de estoque não altera o preço do canal, que é exatamente o que a parametrização desligada pede.
- Se o idworks não conseguir ler o preço atual do canal (com Atualizar preço desativado), ele não envia o saldo e registra o erro no log do anúncio. É proposital: enviar o saldo nesse cenário mudaria o preço publicado. Nesse caso, verifique a integração e tente de novo, ou ative Atualizar preço se quiser que o Hub passe a mandar o preço.
Ao reenviar o anúncio, a mudança de saldo vai como diferença sobre o saldo atual do canal, não como substituição — o idworks consulta o saldo publicado antes de calcular quanto somar ou subtrair.
Como ativar e inativar um anúncio no Kwai?
Use a ação de ativar/inativar do anúncio no Hub, com Atualizar status (ativo/inativo) ligado na parametrização. O idworks consulta primeiro o estado atual no canal e, se o anúncio já estiver no estado que você pediu, avisa "Produto já está ativo no canal" (ou inativo) e não faz nada — não é erro, é só confirmação de que canal e idworks já estão iguais.
Como os pedidos do Kwai entram no idworks?
Com Importar pedidos ativo, o idworks busca os pedidos do Kwai sozinho, em ciclos, e cria o pedido automaticamente.
O que a busca alcança. A rotina olha para os pedidos movimentados nas últimas ~37 horas (cerca de um dia e meio), pela data de atualização no canal. Pedido muito antigo que nunca entrou não é recuperado por ela — fale com o suporte.
O que é importado. Entram os pedidos aguardando nota fiscal, os prontos para despacho e os já despachados. O pedido de venda no idworks é criado quando o pedido ainda está em aberto no canal (aguardando nota ou pronto para despacho).
O que vem no pedido:
- Dados do comprador e endereço de entrega, com o CEP completado pela base do idworks quando o canal não manda bairro/cidade/UF.
- Descontos — o desconto da plataforma e o desconto do vendedor são somados e rateados entre os itens proporcionalmente ao valor de cada um.
- Frete — só entra no valor do pedido quando Incluir valor do frete está ativo na parametrização.
- Prazos do canal — o idworks grava duas datas:
| Campo no idworks | O que significa |
|---|---|
| Data estimada envio | Prazo de entrega/envio que o canal comunica ao comprador. |
| Data estimada expedição | Prazo que o Kwai dá para você despachar (deixar o pedido pronto para a coleta). |
Use a Data estimada expedição para ordenar a fila do dia — pedidos com prazo mais curto primeiro.
Comissão: lembre que a taxa do pedido é calculada pelo idworks, não informada pelo Kwai. Veja Como a comissão do Kwai é calculada no pedido?.
Como enviar a nota fiscal ao Kwai?
O Kwai exige a nota fiscal antes de liberar o despacho e a etiqueta.
- Emita a nota fiscal do pedido normalmente no idworks.
- Com a nota emitida, o idworks envia o arquivo da NF ao canal.
- Assim que o canal aceita a nota, o idworks já tenta gerar a etiqueta na sequência.
Mensagens que podem aparecer:
| Aviso | O que significa |
|---|---|
| "Nota fiscal não emitida" | A NF ainda não foi emitida no idworks. Emita primeiro. |
| "Arquivo XML da nota fiscal não encontrado" | A nota consta como emitida, mas o arquivo não está disponível. Verifique a emissão antes de tentar de novo. |
| Pedido em outro status no Kwai | O pedido não está mais aguardando nota no canal — ou a nota já foi enviada, ou o Kwai não exige nota para aquele pedido. Nesse caso, siga direto para a etiqueta. |
Como gerar a etiqueta e despachar o pedido?
No Kwai não existe um passo separado de "despachar": o envio é criado no canal na hora em que você gera a etiqueta. Ao pedir a Etiqueta canal do pedido (a mesma ação também está disponível em Logística → Romaneio), o idworks, se ainda não houver envio criado, agenda a coleta no Kwai e só então busca a etiqueta.
O que precisa estar pronto:
- Nota fiscal enviada ao canal. Sem ela, o pedido continua aguardando nota e o idworks avisa: "Nota fiscal ainda não enviada ao canal de vendas. Envie a nota fiscal para liberar o despacho e a etiqueta".
- Endereço de coleta cadastrado no Kwai. O idworks usa o endereço marcado como padrão na sua loja do Kwai. Sem nenhum endereço cadastrado, aparece "Nenhum endereço de coleta cadastrado no Kwai" — cadastre no painel do canal e tente de novo.
Janela de coleta. O idworks escolhe o horário a partir das janelas que o próprio Kwai oferece. Se a janela do dia já tiver passado quando você gerar a etiqueta, a coleta é agendada para o dia seguinte.
Outras mensagens:
| Aviso | O que fazer |
|---|---|
| "Etiqueta em processamento no canal de vendas, tente novamente em instantes" | O envio foi criado, mas o Kwai ainda está produzindo a etiqueta. Aguarde alguns instantes e peça de novo. |
| "Pedido já enviado e sem etiqueta disponível no canal de vendas" | O pedido já foi despachado no canal; não há etiqueta a gerar. |
| "Pedido cancelado no canal de vendas, etiqueta não disponível" | O pedido foi cancelado no Kwai. O idworks atualiza o status do pedido. |
Quando a etiqueta sai, o idworks também grava o código de rastreio devolvido pelo canal no pedido.
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. |