~~NOTOC~~ ====== Módulo aiqFome — Guia de Onboarding (Suporte) ====== Este guia explica, passo a passo, como colocar um cliente para operar com a integração aiqFome do Ello: o que precisa estar contratado, o que configurar, como autorizar a loja, como o cardápio é enviado e como os pedidos chegam. Público-alvo: **atendentes de suporte**. ===== Visão geral ===== A integração aiqFome do Ello faz duas coisas, **automaticamente**, através do serviço **Gollum**: * **Envia o cardápio** do Ello para o aiqFome (produtos, categorias e complementos). Qualquer alteração feita no Ello (preço, nome, complemento novo...) é enviada ao aiqFome em segundos, sem ação do usuário. * **Recebe os pedidos** feitos no aplicativo aiqFome e os registra no Ello Retaguarda (consulta a cada 30 segundos), acompanhando o ciclo: novo pedido → confirmação → despacho → conclusão/cancelamento. O vínculo entre o produto do Ello e o do aiqFome é criado e mantido sozinho pela sincronização. > **Diferença importante em relação ao iFood:** o aiqFome exige uma etapa extra de > **autorização** (o lojista precisa liberar o Ello no portal do aiqFome/ID Magalu e > colar um código no Ello — ver passo 3). Sem essa autorização, nada sincroniza. ===== Pré-requisitos ===== ^ Item ^ Quem providencia ^ Observação ^ | Módulo **aiqFome** liberado na licença | Comercial/Ello | Sem o módulo, a integração não inicia | | Módulo **Foods** em uso | Cliente já operando | A integração faz parte do segmento Foods | | **Loja ativa no aiqFome** | Cliente, junto ao aiqFome | Cadastro aprovado no aiqFome | | **Id da Loja** | Cliente obtém no portal do aiqFome | Identificador da loja no aiqFome | | **Autorização (código) do aiqFome** | Cliente, no portal do aiqFome/ID Magalu | O lojista libera o acesso do Ello e recebe um código de uso único (ver passo 3) | | Serviço **Gollum** instalado e rodando | Suporte | É ele quem conversa com o aiqFome; sem Gollum não há sincronização nem pedidos | | Banco de dados atualizado | Suporte | Atualização normal do Ello (os patches criam as tabelas de vínculo) | \\ ===== Passo a passo de ativação ===== ==== 1. Conferir a licença ==== Confirme que o módulo aiqFome está liberado para o cliente. Se não estiver, encaminhe ao comercial antes de qualquer configuração. ==== 2. Configurar os parâmetros (Ello Retaguarda) ==== Abra a tela de parâmetros **Foods – Integrações**, seção **AiqFome**, e preencha: ^ Campo ^ O que informar ^ | **Id Loja** | O identificador da loja no aiqFome | | **Cliente** | Cliente do cadastro usado para registrar o contas a receber dos pagamentos online do aiqFome (crie um cliente "AIQFOME" se necessário) | | **Cardápio** | O **catálogo de produtos** do Ello que será espelhado no aiqFome (ver passo 4) | | **Código** | O código de autorização obtido no portal do aiqFome (ver passo 3) | //Os parâmetros são por empresa. Depois de autorizado, o acesso é renovado sozinho — não há campo de senha do aiqFome no Ello.// ==== 3. Autorizar a integração (etapa exclusiva do aiqFome) ==== Diferente do iFood, o aiqFome só passa a funcionar depois que o **lojista autoriza o Ello a acessar a loja**. O passo é feito uma única vez: - O lojista acessa o portal do aiqFome / ID Magalu e autoriza a aplicação **"Ello Delivery"**. - Ao autorizar, ele recebe um **código** (de **uso único** — vale por pouco tempo). - Copie esse código e cole no campo **Código** dos parâmetros (passo 2). - **Salve** a tela. O Ello troca o código por um acesso permanente, exibe a mensagem //"aiqFome: integração autorizada com sucesso"// e **limpa o campo Código** (ele não é mais necessário). Se aparecer //"falha ao autorizar (código inválido ou expirado)"//, o código provavelmente expirou ou foi colado incompleto. Peça ao lojista para **gerar um novo código** no portal e repita. Depois de autorizado, use o botão **Testar comunicação** para confirmar que a loja responde. ==== 4. Montar o cardápio (catálogo de produtos) ==== O que vai para o aiqFome é o conteúdo de um **Catálogo de Produtos** do Ello (tela **Lista de Produtos**): - Crie um catálogo específico para o aiqFome (ex.: "CARDÁPIO AIQFOME") — não use o catálogo do balcão se os preços/itens forem diferentes. - Adicione ao catálogo apenas os produtos que devem aparecer no aplicativo. - Selecione esse catálogo no parâmetro **Cardápio** (passo 2). Sobre os itens: * **Categoria no aiqFome** = **Grupo do produto** no Ello (ex.: grupo "BEBIDAS" vira a categoria "BEBIDAS" no app). A categoria é criada sozinha quando o primeiro produto do grupo é enviado. * **Tipo de culinária (exclusivo do aiqFome):** além da categoria, o aiqFome exige classificar cada grupo por um **tipo de culinária** (ex.: Lanche, Pizza, Bebidas, Sobremesas). O Ello sugere automaticamente um tipo com base no nome do grupo e confirma com a lista oficial do aiqFome. Se um grupo tiver um nome fora do comum, pode ser necessário conferir/ajustar a culinária. * **Complementos**: os **grupos de complementos** do produto (ex.: "ADICIONAIS: Bacon, Cheddar") viram grupos de opções no aiqFome, com preços. Complementos **avulsos** (fora de grupo) **não** são enviados — oriente o cliente a organizar complementos em grupos. * **Pizza**: produtos do tipo pizza **não são enviados ao cardápio** (limitação atual, igual ao iFood). ==== 5. Primeira carga ==== Com os parâmetros salvos, a integração **autorizada** (passo 3) e o **Gollum em execução**, **salve o catálogo** (abra o catálogo na Lista de Produtos e confirme). Isso dispara o envio de todos os produtos. Os itens são enviados **um a um**, então um cardápio grande pode levar alguns minutos para aparecer completo no aiqFome. A partir daí **tudo é automático**: alterou produto, preço, grupo ou complemento no Ello → atualiza no aiqFome. Removeu o produto do catálogo → sai do aiqFome. //Se algum produto falhar no envio, ele não trava os demais: o Ello continua enviando o restante e tenta reenviar os que falharam sozinho. Produtos que já foram enviados não são duplicados no reenvio.// ==== 6. Abrir a loja ==== No painel do **Foods** (tela principal), localize o cartão **aiqFome** e ligue a chave para **abrir a loja**. Com a loja fechada, os pedidos não são consultados. O Ello também acompanha, sozinho, se a loja está aberta ou fechada no aiqFome. ==== 7. Validar com um pedido real ==== - Faça (ou peça ao cliente para fazer) um pedido de teste pelo aplicativo aiqFome. - O pedido deve aparecer no Ello Retaguarda em até ~30 segundos. - Confirme o pedido no Ello e acompanhe: o status deve refletir no acompanhamento do pedido (confirmado → despachado). - Confira itens, complementos e valores do pedido importado. **Onboarding concluído** quando: cardápio visível no aiqFome, pedido de teste importado corretamente e mudança de status refletida. > **Cancelamento — atenção:** no aiqFome, o **lojista não cancela** o pedido pelo Ello > (o aiqFome não oferece esse recurso para o lojista). Apenas o **cancelamento feito pelo > cliente/pelo aiqFome** é reconhecido — quando isso acontece, o Ello recebe o > cancelamento sozinho e atualiza o pedido. Por isso, o botão de cancelar pedido junto ao > parceiro fica **indisponível** para pedidos do aiqFome (isso é proposital). \\ ===== Problemas comuns ===== ^ Sintoma ^ O que verificar ^ | "Testar comunicação" / nada sincroniza | A integração foi **autorizada** (passo 3)? Se o código expirou, gere um novo e reautorize. Gollum está rodando? Id da Loja correto? | | "Falha ao autorizar (código inválido ou expirado)" | O código é de uso único e vale por pouco tempo — peça um novo no portal do aiqFome e cole novamente, sem espaços | | Cardápio não aparece no aiqFome | Gollum está rodando? Parâmetro **Cardápio** preenchido com o catálogo certo? Produto está DENTRO do catálogo? Integração autorizada? | | Produto alterado não atualiza no app | Gollum rodando? O produto pertence ao catálogo do parâmetro? Se houve falha de internet, a alteração fica na fila e é reenviada sozinha quando a comunicação volta — aguarde alguns minutos | | Cardápio grande demora a aparecer | Normal na primeira carga — os itens são enviados um a um; aguarde alguns minutos | | Pedidos não chegam | Loja **aberta** no painel Foods? Gollum rodando? Integração autorizada? | | Pedido chega sem complemento | O complemento estava em **grupo de complementos** e **ativo**? Complemento avulso não sincroniza | | Categoria de um grupo saiu com culinária "errada" | O tipo de culinária é sugerido pelo nome do grupo; para nomes fora do comum pode ser preciso ajustar | | Produto "pizza" não aparece no app | Comportamento esperado — pizza não é enviada ao cardápio nesta versão | | Não consigo cancelar um pedido do aiqFome pelo Ello | Comportamento esperado — o aiqFome não permite cancelamento pelo lojista; só o cancelamento feito pelo cliente é reconhecido | \\ ===== Resumo dos parâmetros (referência rápida) ===== ^ Parâmetro ^ Tela ^ Conteúdo ^ | Id Loja | Foods – Integrações → AiqFome | Identificador da loja no aiqFome | | Cliente | Foods – Integrações → AiqFome | Cliente p/ contas a receber dos pagamentos online | | Cardápio | Foods – Integrações → AiqFome | Catálogo de produtos espelhado no aiqFome | | Código | Foods – Integrações → AiqFome | Código de autorização (uso único; limpo após autorizar) | \\ ===== Como o aiqFome difere do iFood (resumo) ===== * **Autorização**: o aiqFome exige o passo do **código de autorização** (portal do aiqFome/ID Magalu); o iFood não. * **Culinária**: o aiqFome exige um **tipo de culinária** por grupo (sugerido automaticamente); o iFood não. * **Cancelamento**: no aiqFome o **lojista não cancela** pelo Ello (só o cliente); no iFood o lojista pode cancelar. * **Pizza**: em ambos, pizza **não vai** para o cardápio nesta versão. \\ ===== Escalonar para o desenvolvimento quando... ===== * Integração autorizada, Gollum rodando, mas nada sincroniza (ver log do Gollum); * Pedidos duplicados no PDV; * Produto certo no Ello, mas pedido importa item errado; * Erros repetidos no log do Gollum mencionando "aiqFome". Ao escalonar, informe: versão do Ello, print da seção aiqFome dos parâmetros, log do Gollum do período e o número/horário do pedido afetado.