Uappi
A integração com o Uappi 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 26 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 na Configuração (ícone de engrenagem) da integração.
Categoria no catálogo do idworks: Canal de Venda.
Índice
Conceito
Cadastro e autenticação
Parâmetros por grupo
Erros mais comuns
- "O campo 'descricaoCurta' deve ter no máximo 250 caracteres"
- Por que aparece "Nenhuma característica com 'produto' no nome cadastrada na Uappi"?
- Por que o envio da nota fiscal, do status Enviado ou do status Entregue ao Uappi aparece com Erro no pedido?
Referência rápida
O que é a integração Uappi?
É a conexão entre o canal Uappi e o idworks. Ela controla como dados fluem entre os dois sistemas — depende do tipo da integração (a categoria neste caso é Canal de Venda), 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 → Uappi.
Como ativar a integração?
- Acesse Configurações → Integrações.
- Na aba Integrações Disponíveis, busque por Uappi 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 Validar 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
4 parâmetro(s).
| Parâmetro | Tipo | Para que serve |
|---|---|---|
| Token | Senha | Token de acesso à integração |
| Pass | Senha | Pass de acesso à integração |
| Validar credenciais | Botão | Clique para validar as credenciais informadas |
| Url da plataforma | Texto | Endereço Url utilizado para acessar o site |
Integração de Vendas
12 parâmetro(s).
| Parâmetro | Tipo | Para que serve |
|---|---|---|
| Importar pedidos | Sim/Não | Ative se quiser que a idworks integre os pedidos feitos no canal de vendas. |
| Lista de status para importar pedido | Texto | Informar os status que deve baixar pedidos. Informar separado por | . Exemplo: 1| 3, etc... Caso não esteja preenchido serão importados pedidos no status "Pago" |
| 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) |
| 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 |
| Data inicial para importação de pedidos | Data | Seleciona a data inicial da criação do pedido no canal para importar. Se não informar, sempre será importado pedidos dos últimos 14 dias |
| 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. |
| Enviar dados NF quando for declaração conteúdo | Sim/Não | Enviar nota fiscal fícticia no caso do pedido ter declaração de conteúdo |
| Excluir valor de voucher do pedido | Sim/Não | Ative se quiser excluir o valor do voucher do total do pedido |
| Excluir valor de cupon do pedido | Sim/Não | Ative se quiser excluir o valor do cupom do total do pedido |
| 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
9 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. |
| Atualizar produto | Sim/Não | Ative se quiser enviar a atualização de produto na integração |
| Utilizar título como nome SKU | Sim/Não | Utilizar o campo título como nome do SKU ao enviar para o canal |
| Atualizar preço | Sim/Não | Ative se quiser enviar a atualização de preço na integração |
| Atualizar Imagem | Sim/Não | Ative se quiser enviar a atualização de imagem na integração |
| Atualizar categoria | Sim/Não | Ative se quiser enviar a atualização de categoria na integração |
| Atualizar marca | Sim/Não | Ative se quiser enviar atualização de marca na integração |
| Baixar cadastro produto | Sim/Não | Ative se quiser baixar o cadastro do produto na integração |
| Incluir código de barras nas palavras substitutas | Sim/Não | Ative se quiser incluir código de barras nas palavras substitutas |
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 |
"O campo 'descricaoCurta' deve ter no máximo 250 caracteres"
Mensagem "O campo 'descricaoCurta' deve ter no máximo 250 caracteres", vista ao atualizar produto ou preço no Uappi. A plataforma limita a descrição curta do produto a 250 caracteres, e o texto enviado pelo idworks passou desse limite. O Uappi recusa a atualização inteira (o resto da chamada — preço, estoque, imagem — também não vai) até a descrição ser encurtada.
A descrição curta do Uappi sai do campo DESCRIÇÃO SIMPLES do cadastro do produto no idworks (no produto com variação, do produto-pai). Ele fica na aba Geral, no bloco Dados plataforma | marketplaces. Não confunda com a DESCRIÇÃO COMPLETA (que pode ter milhares de caracteres) — o limite de 250 vale só para a versão simples. O idworks envia o texto sem a formatação do editor, e é esse texto que conta para o limite. Ele não bate exatamente com o contador do editor: cada parágrafo entra com uma quebra de linha e cada apóstrofo (') conta como dois caracteres. Deixe uma folga abaixo de 250.
No idworks o campo aceita até 3000 caracteres: o limite de 250 é do Uappi e a tela não o aplica.
Como resolver:
- Em Produtos → Listar Produtos, abra o produto (no produto com variação, o produto-pai) → aba Geral, e localize o editor DESCRIÇÃO SIMPLES no bloco Dados plataforma | marketplaces.
- Reescreva o texto ficando dentro de 250 caracteres (espaços e pontuação contam). Use frases objetivas com os atributos essenciais do produto — material, função, indicação. A versão longa fica em DESCRIÇÃO COMPLETA.
- Salve o produto e refaça a sincronização do anúncio.
- Com muitos produtos, use Configurações → Ação em massa → Importar Arquivo → Tipo ação Item (sku, kit, produto) editar. A planilha atualiza o cadastro de itens já existentes, inclusive a descrição simples (no produto com variação, na linha do produto-pai). Baixe o modelo pela própria tela com Baixar Modelo e mantenha as demais colunas como estão. A planilha de Importar Anúncio não tem coluna de descrição, e a ação Atualizar Descrição da Ação em Massa (em Mais Ações, na lista de produtos) altera só a DESCRIÇÃO COMPLETA.
O Uappi também pode rejeitar atualização de preço ou estoque quando a descrição já passou do limite (mesmo que você só esteja atualizando o número). Por isso o erro costuma aparecer "do nada" — alguém editou a descrição em algum momento e estourou o limite, e desde então toda atualização cai. Encurte a descrição e os outros fluxos voltam.
Por que aparece "Nenhuma característica com 'produto' no nome cadastrada na Uappi"?
A mensagem aparece ao sincronizar um anúncio do Uappi, na etapa que envia as especificações do produto (a ficha técnica). Na sincronização completa do produto, ela aparece junto com os erros das outras etapas, se houver, assim: "Atualizar especificação produto: - Nenhuma característica com 'produto' no nome cadastrada na Uappi".
Cada etapa que falha entra na mensagem com o nome dela (como Atualizar sku, Atualizar imagem, Atualizar preço, Atualizar balance, que é o estoque, e Atualizar filtros do produto) e o motivo que o Uappi devolveu, separada das outras por |. Quando o Uappi recusa mais de um item da mesma etapa, os motivos vêm separados por ;. A exceção é a etapa Atualizar produto: se ela falha, a sincronização para ali e só essa mensagem aparece.
Como o envio das especificações funciona:
- O idworks procura, entre as características cadastradas no Uappi, aquela cujo nome contém produto, escrito em letras minúsculas. Uma característica chamada só Produto (com P maiúsculo) não é encontrada. Se mais de uma servir, vale a última da lista.
- Dentro dessa característica, cada valor cadastrado no Uappi é comparado com o nome das especificações do produto no idworks. Quando os nomes batem, o conteúdo da especificação é enviado. Maiúsculas e minúsculas sem acento não fazem diferença, mas letras acentuadas (Ç, Ã, É...) e espaços precisam ser iguais — "COMPOSIÇÃO" não bate com "Composição". Na dúvida, escreva o nome exatamente igual nos dois lados. Especificação sem valor com o mesmo nome no Uappi não é enviada.
- O idworks lê só as primeiras 100 características e os primeiros 100 valores dessa característica. Se a sua conta no Uappi tem mais de 100 características, a certa pode ficar de fora da leitura e o erro aparece mesmo com ela cadastrada; valores além do 100º nunca são enviados.
Sem essa característica no Uappi, o envio das especificações para com o erro — mesmo que o produto não tenha nenhuma especificação preenchida.
Como resolver:
- No painel do Uappi, cadastre uma característica cujo nome tenha a palavra produto em minúsculas (por exemplo, "Características do produto").
- Dentro dela, cadastre um valor para cada especificação que você quer enviar, com o mesmo nome da especificação no idworks.
- Sincronize o anúncio de novo.
Se a mensagem for "Erro HTTP ... da Uappi ao listar as características: ..." ou "Erro HTTP ... da Uappi ao listar os valores da característica ...", o problema é outro: o Uappi não devolveu a lista pedida. O número depois de "Erro HTTP" é o código de resposta do Uappi ("sem resposta" quando ele não respondeu). Confira as credenciais no grupo Credenciais de Acesso e tente de novo.
Por que o envio da nota fiscal, do status Enviado ou do status Entregue ao Uappi aparece com Erro no pedido?
Quando o idworks envia ao Uappi a nota fiscal ou a marcação de Enviado ou de Entregue de um pedido e o Uappi recusa ou não responde, o envio fica registrado com status Erro na aba Timeline (Logs) do pedido. O idworks não recebeu confirmação do Uappi: confira no painel do Uappi se o pedido mudou de status — quando o Uappi demora a responder, a atualização pode ter sido aceita lá mesmo assim.
O motivo registrado depende do envio.
Nota fiscal. A mensagem tem este formato: "Uappi: erro ao enviar a nota fiscal do pedido 12345 (HTTP 500): motivo". Nela vêm o número do pedido no Uappi, o código de resposta do Uappi (ou "sem resposta", quando ele não respondeu) e o motivo. O motivo é o texto de erro que o Uappi devolve, seguido dos detalhes, quando vierem. Sem texto de erro, vem o início da resposta do Uappi ou, quando ele não respondeu, o erro técnico de conexão (por exemplo, tempo esgotado). Se a resposta chega vazia, o texto é "resposta sem detalhe do erro".
Enviado e Entregue. O motivo é o texto de erro que o Uappi devolve, seguido dos detalhes, quando vierem. Se o Uappi não manda texto de erro, a mensagem começa assim:
- "Erro da Uappi (HTTP sem resposta)" — o Uappi não respondeu. Depois dos dois-pontos vem o erro técnico de conexão (por exemplo, tempo esgotado).
- "Erro da Uappi (HTTP 500)", com o número variando — o Uappi respondeu com esse código de erro, sem uma mensagem de erro própria. Depois dos dois-pontos pode vir o início da resposta que o Uappi mandou.
Quando o envio nem chega ao Uappi. Em alguns casos a ação mostra a mensagem e não grava um envio com Erro na Timeline (Logs):
- "Nota fiscal não emitida" — o pedido ainda não tem nota fiscal emitida. Vale para os três envios (nota fiscal, Enviado e Entregue). Emita a nota e envie de novo. Com o parâmetro Enviar dados NF quando for declaração conteúdo ligado, o envio segue mesmo sem nota emitida.
- "Uappi: pedido ... não vinculado a um pedido da Uappi (HubOrder não encontrado)" — só no envio da nota fiscal: o pedido do idworks não está ligado a nenhum pedido do Uappi, então não há onde receber a nota.
- "Uappi: credenciais não encontradas ou integração inativa ..." — só no envio da nota fiscal: confira o status da integração e o grupo Credenciais de Acesso.
- "canal de venda diferente de Uappi" e "Pedido não encontrado" — valem para os três envios: o pedido não é de um canal Uappi ou o pedido do Uappi não está ligado a um pedido do idworks.
Antes da correção de outubro de 2026, quando o Uappi não respondia, o envio era registrado com status Sucesso mesmo sem confirmação do Uappi. Se você tem pedidos antigos com NF, Enviado ou Entregue registrados como enviados que não aparecem no Uappi, pode ter sido isso.
Resolvida a causa (credenciais, nota fiscal, instabilidade do Uappi), envie a atualização de novo: na lista de Pedidos, selecione o pedido e use a ação correspondente:
- Nota fiscal → Enviar NF para canal de venda (veja Como enviar a NF para o canal de venda?).
- Enviado → Marcar Enviado canal de venda.
- Entregue → Marcar Entregue canal de venda.
Dependendo de como o canal está configurado, a rotina automática do idworks também pode tentar de novo o envio de Enviado e de Entregue enquanto não houver um envio com Sucesso. A nota fiscal não é reenviada sozinha: ela é enviada na emissão ou pela ação acima.
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 | Abrir a Configuração (engrenagem), editar nome e status e validar credenciais. |
| Deletar parametrizações empresa | Excluir a integração. |