Integração Order API
Integração
Last updated
Integração
Last updated
1. Observações Iniciais
a. Pedidos agendados
Por padrão, a integração não aceita pedidos agendados. Caso deseje receber pedidos agendados, envie um e-mail para delivery@teknisa.com e faça a solicitação.
b. Funcionamento da integração
A integração funciona de forma autônoma, desde o recebimento do pedido no parceiro até o envio do mesmo a cozinha do restaurante. Ao finalizar a parametrização do Retail e testes da integração, a equipe do restaurante não deve receber os pedidos manualmente, nem utilizar ferramentas do parceiro que receba os pedidos. As ferramentas fornecidas pelos parceiros podem ser utilizadas se, e somente se, não interferirem no funcionamento da integração. Em caso de dúvidas, não utilize as ferramentas fornecidas e entre em contato com a equipe de suporte da Teknisa.
ATENÇÃO: A INTEGRAÇÃO DEPENDE DO PRODUTO ODHEN RETAIL CONFIGURADO. CONTATE COM SEU REPRESENTANTE COMERCIAL PARA MAIS INFORMAÇÕES.
2. Parametrização
Para que a integração com o Order API ocorra com sucesso, é necessário que sejam realizados os procedimentos abaixo. Se você utiliza outros produtos da Teknisa (Call Center, Delivery Aplicativo, etc), provavelmente terá estes itens parametrizados no Odhen Retail (Fig. 1). Para fins de demonstração, sempre utilizaremos a filial fictícia TEKNISA – 0005 em todos os exemplos. O usuário deve ficar atento ao selecionar uma filial.
Para iniciar a configuração, abra o Retail e clique no menu no canto superior esquerdo (Fig. 1).
Figura 1: Odhen Retail com o menu no canto superior esquerdo destacado. |
O menu principal será exibido com a árvore completa de itens do Retail e o campo de pesquisa de páginas (Fig. 2). Através da busca, você filtra a árvore de itens e acessa rapidamente qualquer página do Retail, bastando informar o nome da tela que deseja acessar.
O manual sempre informará o caminho completo de cada tela, sendo que o nome da tela estará em negrito. Recomendamos que o usuário utilize o campo de busca para acessá-las. Para isso, basta digitar no campo de busca o nome da tela.
Figura 2: Menu principal, com campo de busca destacado. |
3. Parametrização do Delivery
a. Cliente Padrão e Vendedor Padrão
Essa etapa realiza o vínculo do Cliente Padrão e Vendedor Padrão preexistentes no Retail. Cada filial precisa de um cliente e vendedor padrão cadastrado. O cliente padrão deverá ser o mesmo para todas as filiais, enquanto o vendedor padrão é exclusivo para cada filial. Este manual considera que o Cliente Padrão e o Vendedor Padrão foram criados anteriormente. Caso seja necessário criá-los, entre em contato com o responsável pelo projeto ou a equipe de suporte. Acesse a tela Parametrização > Vendas > Parâmetros de Gestão de Vendas > Delivery. Clique em Unidade e selecione a unidade a ser parametrizada. Clique na aba Parâmetros e, dentro dela, clique em Editar (Fig. 3).
Figura 3: Tela Delivery com aba parâmetros selecionada. |
Preencha os campos Cliente Padrão e Vendedor Padrão, selecionando o cliente e vendedor disponível. Após a configuração, clique em Salvar (Fig. 4). Os campos Tempo de Entrega Limite (minutos), Taxa de Entrega (R$), Preço Mínimo do Pedido (R$) e Distância da área de atendimento (Km) não são considerados pela integração e seu preenchimento não são obrigatórios.
Figura 4: Tela de Parâmetros com campos obrigatórios destacados. |
b. Centro de Custo de Cliente
Após configurar o Cliente Padrão, é necessário associar um centro de custo a ele. Abra a tela Parametrização > Vendas > Cliente > Centro de Custo por Cliente. Clique no campo Cliente, selecione o cliente e clique em Filtrar (Fig. 5).
Figura 5: Tela Centro de Custo e cliente padrão selecionado. |
Será exibido a lista de centros de custo do cliente. Para adicionar um centro de custo, clique em Adicionar, informe o código, o nome do centro de custo e clique em Salvar (Fig. 6).
Figura 6: Adicionando um centro de custo ao cliente selecionado. |
c. Cadastro Automático de Novos Clientes
É necessário configurar o Centro de Custo e Tipo de Consumidor para cadastrar novos clientes. Abra a tela Parametrização > Vendas > Parâmetros de Gestão de Vendas > Parâmetros da Unidade. Selecione a filial, clique em Frente de Caixa, Definições de Padrão e clique em Editar (Fig. 7).
Figura 7: Parâmetros da Unidade, com Frente de Caixa e Definições de Padrão destacados. |
Clique em Parâmetros utilizados na inclusão automática de consumidor, preencha o campo Centro de Custo e Tipo Consumidor e clique em Salvar (Fig. 8).
Figura 8: Centro de Custo e Tipo de Consumidor destacados. |
d. Caixa Associado ao Vendedor
Os caixas cadastrados com as modalidades relacionadas ao delivery devem ser devidamente associados a um vendedor para que a integração seja realizada com sucesso. Para fazer essa associação, abra a tela Parametrização > Vendas > Caixa > Cadastro de Caixa, selecione a Unidade e a Loja que receberá a associação e clique em Filtrar (Fig. 9).
Figura 9: Cadastro de Caixa, com Unidade e Loja destacados. |
Será exibido a lista de caixas cadastrados (Fig. 10). Para verificar se um caixa pode ser associado ao vendedor, verifique a coluna Modalidade Caixa de cada caixa cadastrado. Caso não exista um caixa cadastrado relacionado ao delivery, clique no botão Adicionar para criar um caixa (Fig. 10).
Figura 10: Cadastro de Caixa, destacando caixas delivery. |
Preencha os dados do novo caixa e certifique-se que ele tenha uma modalidade de caixa que permita associação (Fig. 11).
Figura 11: Tela Cadastro de Caixa, destacando o campo Modalidade de Caixa. |
As modalidades que permitem associação são:
Restaurante/Comanda/Delivery com venda Balcão
Delivery Venda Balcão
Call Center Delivery
Site Delivery
Após a criação de um caixa para o delivery, clique nele, navegue até a aba Parâmetros e clique em Vendedores Associados. Clique no botão Adicionar (Fig. 12).
Figura 12: Cadastro de Caixa, com Parâmetros e Vendedores Associados destacados. |
Clique no campo Vendedores. Será exibido uma lista com todos os vendedores já criados. Selecione o vendedor padrão criado anteriormente, clique em Ok e Cadastrar Vendedores para finalizar (Fig. 13).
Figura 13: Aba Vendedores Associados, com campo Adicionar Vendedores destacado. |
e. Consumidor Padrão
Será necessário criar um consumidor padrão para atrelar aos pedidos, nos casos em que os parceiros não enviem todas as informações do consumidor. Para criar um consumidor padrão, abra a tela Parametrização > Vendas > Consumidor > Cadastro de Consumidor. Selecione o cliente criado anteriormente e clique em Filtrar. Clique no botão Adicionar. Preencha os campos como se fosse um cliente real. Recomendamos o nome “Consumidor Padrão” para não ficar específico a uma integração. Para finalizar, clique em salvar (Fig. 14).
Figura 14: Cadastro do Consumidor Padrão |
Após finalizar o cadastro do consumidor, clique na aba Endereço. Clique em Editar na parte debaixo da tela e preencha o endereço. Recomendamos o endereço da matriz. Para finalizar, clique em Salvar (Fig. 15).
Figura 15: Cadastro de Endereço |
Para atrelar o Consumidor Padrão a uma Filial, abra a tela Parametrização > Vendas > Parâmetros de Gestão de Vendas > Parâmetros da Unidade. Escolha a Filial, clique na aba Frente de Caixa, clique na aba Definições de Consumidor e clique no botão Editar (Fig. 16).
Figura 16: Tela Parâmetros da Unidade, com Definições de Consumidor destacado. |
Clique na seção Consumidor Padrão Utilizado nos sistemas. Clique no campo novamente para selecionar o Consumidor Padrão criado e clique no botão Salvar (Fig. 17). É necessário atrelar este consumidor em todas as filiais.
Figura 17: Campo Consumidor Padrão Utilizado nos sistemas destacado. |
4. Parametrização do Cardápio
Para parametrizar o cardápio, será necessário criar uma relação de equivalência entre os produtos cadastrados no Retail e no parceiro. Todo produto cadastrado no Retail precisa ter um produto igual no parceiro.
Para realizar a parametrização, acesse o Retail para obter o código do produto que será oferecido no parceiro. Abra a tela Parametrização > Vendas > Produto > Tabela de Preço. Dentro da tela Tabela de Preço, escolha a filial desejada dentro de Unidade e clique em Filtrar (Fig. 14).
Figura 14:Tela Configuração Terminal de Caixa, com os códigos dos produtos destacados. |
Após aplicar o filtro de unidade, clique na tabela de produtos que utilizará. Em seguida, clique na aba Produtos e copie os códigos dos produtos que deseja cadastrar (Fig. 15). Encaminhe todos os códigos para o parceiro efetuar o cadastro dos produtos que serão disponibilizados na plataforma.
Figura 15: Tabela de Preço, aba Produtos e código destacado |
Com o código copiado, acesse seu site de parametrização do cardápio EatTake (link de exemplo: https://empresahipotetica.eattake.com/pedidos). Dentro do site, acesse a opção Menus, abra o menu desejado e clique no produto que deseja inserir o código, abrindo-o para alterações. Dentro da tela “Alterando Produto” insira o Código Externo da Integração do produto (sem pontos) e clique em SALVAR ALTERAÇÕES (Fig. 16.).
a. Acréscimos, retiradas e observações nos produtos
● Acréscimo de Produto: As alterações do tipo acréscimo possuem preço (mínimo R$0,01), pois são complementos adicionados no prato original e possuem custo significativo. Exemplo: Dobro de queijo em um sanduíche.
● Retirada de Produto: As alterações dentro da categoria retirada são utilizadas para retirar algum ingrediente do prato. Elas devem ser cadastradas com preço R$0,00 e devem seguir o formato Código Grupo de Observação|Código de Observação. Exemplo: Sem salada.
● Observação de Produto: Grupo criado para agrupar as alterações que não são cobradas do cliente, nem que retiram ingredientes do prato. Elas devem ser cadastradas com preço R$0,00 e devem ser cadastradas no formato Código Grupo de Observação|Código de Observação, igual a categoria Retirada. Exemplo: Mal passado.
ATENÇÃO: OS CÓDIGOS DE RETIRADA E OBSERVAÇÃO (XX|YY) DEVEM OBRIGATORIAMENTE ESTAR RELACIONADOS A PRODUTOS COM PREÇO E CÓDIGO NO FORMATO XX.XX.XX.XXX.XX.
O código de integração em extras e opcionais é inserido no EatTake/Pedidos na tela “Alterando Extra” > “Código de integração” > “Botão +” > “Adicionar” (Fig. 17):
5. Parametrização da Integração
a. Cadastro do Subprojeto
Para o Order API funcionar corretamente, é necessário cadastrar o Subprojeto. Este campo identifica o parceiro junto ao sistema. Para efetuar o cadastro, solicite ao parceiro que crie um código de 5 caracteres para identificá-lo. Além disso, o parceiro precisará enviar este código nos pedidos. Internamente, este campo se chama “origin” Em caso de dúvidas, o seu parceiro deve consultar a documentação técnica da integração. Com o código em mãos, acesse a tela Parametrização > Vendas > Parâmetros de Gestão de Vendas > Parâmetros de Integração e Aplicativos. Dentro da aba Projeto, verifique se o campo Subprojeto está marcado com SIM. Caso não esteja, clique em editar (Fig. 16).
Figura 16: Tela Parâmetros de Integração e Aplicativos, destacando a aba Projeto |
Altere o campo para SIM e clique em Salvar (Fig. 17).
Figura 17: Tela Parâmetros de Integração e Aplicativos, destacando o campo Subprojeto |
Após a alteração, a aba Subprojeto se tornará visível. Clique na aba e clique em Adicionar (Fig. 18).
Preencha os campos da tela e clique em Salvar (Fig. 19).
Descrição dos campos:
Nome: Informe o nome EATTAKE
Código de Origem do Subprojeto: Insira o código EATTK
b. Cadastro de E-mail do Responsável Técnico
Se acontecer algum imprevisto durante a integração de um pedido, a integração envia automaticamente um e-mail para os e-mails cadastrados, informando o que aconteceu. É possível cadastrar mais de um e-mail, porém cadastre um e-mail por vez.
Para cadastrar os e-mails que receberão as mensagens, abra a tela Parametrização > Vendas > Parâmetros de Gestão de Vendas > Parâmetros de Integração e Aplicativos. Acesse a integração do Order API e clique em E-mail do Responsável Técnico. Clique em Adicionar. Insira o e-mail e clique em Salvar para finalizar (Fig. 20).
c. Cadastrando a Integração com o Order API
O próximo passo é criar a integração com o Order API no Retail. Nesta tela será necessário inserir o Identificador e dar um nome para a Integração. Os outros campos devem ficar em branco ou com o valor padrão.
Para iniciar o cadastro, abra a tela Parametrização > Vendas > Integração > Cadastro de Integração e clique em Adicionar. Preencha todos os campos e clique em Salvar (Fig. 21).
Descrição dos campos:
Código: O Retail preenche este campo no momento que o usuário seleciona o Identificador.
Identificador: Este campo é que determina qual integração será criada. O código identificador do Order API é o “ORD”.
Nome: Nome da integração que será exibido na tela anterior. Através do nome que o usuário identifica as integrações existentes. Recomendamos “Order API”.
d. Configurando os Tipos de Recebimento
Após configurar a integração, é necessário vincular os tipos de recebimentos que serão utilizados. Ainda dentro da tela Cadastro de Integração, clique em Tipo de Recebimento. Será listado todos os tipos de recebimento já configurados, caso exista. Clique em Adicionar para inserir um novo tipo de recebimento (Fig. 22).
Preencha todos os campos e clique em Salvar (Fig. 23).
Descrição dos campos:
Código Interno: Este é o código interno da Teknisa do tipo de recebimento a ser cadastrado. Não é possível alterar este campo, pois ele é preenchido automaticamente em relação ao tipo de recebimento selecionado.
Tipo de Recebimento: Ao clicar neste campo, é exibido uma lista com todos os tipos de recebimentos disponíveis. Você deve selecionar todos os tipos de r
Código Externo: Este é o código identificador utilizado pelo EatTake. Ele é enviado junto com o pedido e é através dele que a forma de recebimento é identificada. Os códigos estarão em “Métodos de Pagamento” de sua loja no EatTake/Admin (exemplo: https://empresahipotetica.eattake.com/admin).
As configurações feitas até aqui relacionadas ao tipo de recebimento são globais. Isto é, são aplicadas a todas as filiais. Caso seja necessário cadastrar um tipo de recebimento para uma única filial, clique em Unidade, selecione a unidade desejada e clique em Tipo de Recebimento e clique em Adicionar (Fig. 24). As regras para criação de tipos de recebimento da unidade são iguais as regras globais. O tipo de recebimento da unidade sempre se sobrepõe ao tipo de recebimento global.
6. Problemas Frequentes
a. Erro “Caixa sincronizador não encontrado na filial xxxx, Habilite a flag de sincronização de caixa”.
Este erro acontece pois a sincronização com o Delivery não está habilitada. Para corrigi-lo, abra a página Parametrização > Vendas > Caixa > Cadastro de Caixa. Uma caixa com filtro de unidade e loja aparecerá. Selecione a unidade e a loja que deseja fazer a alteração, em seguida selecione uma loja, clique em Parâmetros, Frente de Caixa, Frente de Caixa 3 e clique em Editar. Clique em Sincronização com Delivery e altere o campo Realiza sincronização com Delivery Centralizado para Sim. Clique em Salvar para finalizar (Fig. 25).
b. “Ocorreu um erro de parametrização. Error: Não foi encontrado operador relacionado ao vendedor padrão (xxxx) da filial xxxx”.
Este erro ocorre quando o Operador Padrão não foi definido ao criar o vendedor padrão da filial. Para corrigi-lo, primeiro é necessário confirmar se existe um Operador Padrão para a unidade. Abra o Retail, clique em Controle de Acesso > Operador. Será exibida a lista de operadores cadastrados (Fig. 26). Verifique se o operador foi cadastrado corretamente. Caso contrário, crie um. Em caso de dúvidas, entre em contato com o suporte.
Em seguida, atrele o Operador Padrão ao Vendedor Padrão. Isso é feito acessando a tela Parametrização > Vendas > Mesa/Comanda > Cadastro de Vendedor (Garçom). Selecione o vendedor padrão da Filial e clique em Filtrar. Em seguida, selecione o vendedor novamente, clique em Editar e atrele o Operador Padrão a ele (Fig. 27).
c. “Código de observação com formato inválido (xxxxxxxxxxxxx). Observação: xxxxxxxx | Formato esperado: CDGRPOCOR|CDOCORR.
Este erro ocorre quando as observações do tipo “Observação” ou “Retirada” de um produto são cadastradas no formato das observações do tipo “Acréscimo”. Para corrigir este erro, existem duas opções:
Adicionar um valor simbólico (normalmente R$0,01) as observações.
Alterar o código da observação para o padrão “Grupo Observação | Código Observação”, sem espaço e separados pelo caractere pipe “|”. Os códigos são obtidos no ForSale, conforme os prints. No exemplo abaixo, a observação “Mal passado” terá o código “04|01” (Fig. 28e Fig. 28).
