Integração de loja
Se você precisa obter informações sobre um estabelecimento, como seu endereço, horários de funcionamento, formas de pagamento aceitas, configurações de agendamento e outras informações básicas, como o perfil do Instagram e logomarca, você pode utilizar o endpoint Consultar loja. Esse endpoint retorna todas essas informações, além de outras relacionadas ao estabelecimento. Para listar os métodos de pagamento disponíveis na criação de pedidos, utilize Listar métodos de pagamento. Atualmente, não oferecemos um webhook para esse módulo. Portanto, se você deseja ter as informações atualizadas, recomendamos fazer requisições periódicas para o endpoint mencionado e verificar se houve alguma alteração. As informações da loja não costumam mudar com frequência, portanto, o intervalo entre as requisições pode ser de algumas dezenas de minutos ou algumas horas, dependendo das suas necessidades.Integração de catálogo
Caso seja necessário obter informações sobre as categorias, produtos e complementos de um estabelecimento, utilize o endpoint Consultar catálogo. Esse endpoint retorna o catálogo completo, contendo todas as informações disponíveis. Para entender melhor a estrutura dos dados retornados, recomendamos consultar a documentação da Estrutura do catálogo, bem como a subseção abaixo relacionada a esse tema. Isso ajudará a compreender a organização do catálogo e a utilizar as informações de forma mais eficiente. Além desse endpoint, também disponibilizamos outros endpoints para a gestão completa do cardápio, que podem ser consultados na documentação da API Catálogo. No momento, não disponibilizamos um webhook para esse módulo específico. Portanto, se você deseja ter acesso às informações atualizadas, recomendamos fazer requisições periódicas para o endpoint mencionado e verificar se houve alguma alteração. É importante destacar que as informações do catálogo geralmente não sofrem alterações com muita frequência. Assim, um intervalo de algumas horas entre as requisições pode ser adequado para acompanhar eventuais atualizações.Estrutura do catálogo
Um catálogo é composto de Categorias, que nada mais são do que um grupo de produtos. Os produtos podem ser de dois tipos:
Item normal
É um produto comum, que pode ter ou não complementos. Para ter complementos, ele deve estar associado a pelo menos um Grupo de complementos e esse grupo deve ter pelo menos uma Opção disponível. Uma opção é uma entidade distinta do produto, com suas próprias características, como preço, imagem, descrição e controle de estoque. A principal diferença em relação a um produto é que uma opção só pode ser utilizada associada a um grupo de complementos. No grupo de complementos é estabelecido um conjunto de opções disponíveis, além de regras que determinam quantas opções podem ser escolhidas entre as disponíveis. Também são definidas as regras de cálculo do preço final do grupo, com base nas opções selecionadas (por exemplo, média, soma, maior valor ou menor valor). Além disso, o preço de uma opção é determinado na relação dela com o grupo de complementos, permitindo que uma opção tenha preços diferentes para cada grupo ao qual está associada. No nosso caso, tanto os grupos de complementos quanto as opções existem independentemente de estarem associados a um item ou a um grupo de complementos, respectivamente. Além disso, o mesmo grupo de complementos pode estar associado a vários itens e uma mesma opção pode estar associada a vários grupos de complementos. O valor final do produto é determinado pela soma do seu preço base com a combinação dos preços de todas as opções escolhidas. Cada opção respeita a regra de cálculo do preço do grupo de complementos ao qual estava associada quando foi escolhida.Combo
Um Combo é um produto que permite a venda de uma combinação específica de outros produtos por um preço diferente da soma dos preços individuais desses produtos. Diferentemente dos produtos tradicionais, os combos não possuem grupos de complementos, mas sim em etapas do combo. Cada etapa é composta por um conjunto de produtos possíveis que podem ser selecionados e em cada etapa, apenas um produto pode ser escolhido dentre as opções. Uma etapa do combo faz referência a produtos previamente cadastrados, e o cliente pode escolher os complementos do produto normalmente. A única diferença é que o preço de venda do produto é ignorado, sendo utilizado o preço definido na etapa do combo. Caso o produto escolhido tenha complementos pagos, é possível determinar na etapa do combo se o valor dos complementos será somado ao valor da etapa ou ignorado. Além disso, alguns itens da etapa do combo podem ter um valor adicional caso sejam selecionados. Esse valor será somado ao valor da etapa e, se configurado dessa forma, aos possíveis complementos.Integração de pedidos
No módulo de pedidos, além de receber informações sobre os pedidos feitos por meio do nosso sistema, também é possível alterar o status desses pedidos. Integradoras que enviam pedidos para a Cardápio Web podem utilizar o endpoint Criar pedido, que exige autenticação dupla viaX-API-KEY e X-PARTNER-KEY (consulte Sobre a API).
Existem duas formas de acompanhar os novos pedidos e as alterações de status. A primeira é através do polling, em que você faz uma verificação periódica para obter as atualizações. A segunda forma é por meio de webhook, que envia notificações em tempo real para informar sobre os novos pedidos e as mudanças de status.
Independentemente do tipo de integração, para obter mais detalhes sobre um pedido, utilize o endpoint Consultar detalhes do pedido. Esse endpoint retorna todas as informações relacionadas a um pedido com base no seu ID. Para mais informações sobre a estrutura do pedido — e, consequentemente, o retorno desse endpoint — consulte a documentação do endpoint ou acesse diretamente a documentação sobre a Estrutura do pedido.
Integração via polling
Se você optar por realizar a integração através de polling, utilize o endpoint Consultar pedidos. Esse endpoint retorna, por padrão, os pedidos que sofreram modificações nas últimas 24 horas. No entanto, é possível filtrar os pedidos com base no seu status ou na data em que foram modificados pela última vez. A documentação do endpoint fornece mais detalhes sobre esses filtros e explica como utilizá-los para simplificar a gestão da integração. O retorno desse endpoint fornece informações básicas sobre os pedidos. A partir dessas informações, você pode obter mais detalhes sobre um pedido específico utilizando o endpoint mencionado anteriormente. Ao fazer uma requisição para esse endpoint, percorra a lista de pedidos retornados e identifique dois tipos: aqueles que ainda não foram integrados e aqueles que tiveram uma mudança de status. Ao identificar esses pedidos, você pode executar as ações necessárias, como realizar a integração dos pedidos pendentes ou atualizar os registros dos pedidos que tiveram mudança de status. Por fim, é recomendado que as requisições para esse endpoint sejam feitas a cada 30 segundos.Integração via webhook
Uma outra opção de integração é via webhook. Nesse método, o nosso servidor notifica o seu servidor através de um endpoint previamente configurado. A notificação ocorre toda vez que um novo pedido é recebido ou quando há uma modificação no status de um pedido. Isso permite uma comunicação em tempo real entre os sistemas, garantindo uma sincronização eficiente das informações. As informações enviadas pelo webhook incluem dados básicos sobre os pedidos. No entanto, você pode utilizar o endpoint mencionado anteriormente para obter informações mais detalhadas sobre um pedido específico. Para obter mais detalhes sobre a integração via webhook, temos uma seção completa dedicada ao funcionamento dos webhooks. Nessa seção, você encontrará informações sobre como configurá-los adequadamente e quais eventos específicos são notificados através deles.Alterar status dos pedidos
Conforme mencionado anteriormente, no módulo de pedidos, também é possível modificar o status dos pedidos. A documentação do módulo de pedidos apresenta detalhes sobre os endpoints que viabilizam a alteração do status. Recomendamos consultar diretamente a documentação de cada endpoint para obter informações adicionais, pois cada um deles possui particularidades específicas. Para utilizar corretamente os endpoints de mudança de status, é fundamental ter uma visão geral dos possíveis status. Você precisa compreender seus significados, entender o contexto em que são utilizados e conhecer as possíveis transições entre eles. Essas informações podem ser encontradas na documentação da Estrutura do pedido, juntamente com a imagem abaixo, que fornece uma representação visual desses status e suas interações.