Fluxos de integração

Novas integrações devem autenticar com OAuth e os escopos necessários. Integrações legadas podem continuar com API Key, mas recomendamos migrar para OAuth. Para entender as diferenças entre os modelos, consulte Modelos de autenticação. A API aberta tem três módulos. Dependendo da integração, você pode precisar de um, dois ou todos:

​

Integração de loja

Para obter informações sobre um estabelecimento, use o endpoint Consultar loja. Ele retorna dados como endereço, horários de funcionamento, formas de pagamento aceitas, configurações de agendamento, perfil do Instagram, logomarca e outras informações básicas. Autenticação: com OAuth, exige o escopo store. No modelo legado, exige X-API-KEY. Para listar os métodos de pagamento usados na criação de pedidos, use Listar métodos de pagamento. No modelo legado, esse endpoint também exige X-PARTNER-KEY.

​

Integração de catálogo

Para obter categorias, produtos e complementos de um estabelecimento, use o endpoint Consultar catálogo. Ele retorna o catálogo completo com todas as informações disponíveis. Autenticação: com OAuth, exige o escopo catalog. No modelo legado, os endpoints do catálogo exigem X-API-KEY e X-PARTNER-KEY. Para entender a estrutura dos dados retornados, consulte a subseção Estrutura do catálogo abaixo e o schema na referência do endpoint. Além da consulta, a API Catálogo oferece endpoints para gestão do cardápio (criar, editar e excluir categorias, itens, grupos de complementos e opções). Atualmente, não é possível cadastrar produtos do tipo combo pela API aberta.

​

Estrutura do catálogo

Um catálogo é composto de categorias, que agrupam 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 com pelo menos uma opção disponível. Opção: entidade distinta do produto, com preço, imagem, descrição e controle de estoque próprios. Uma opção só pode ser usada dentro de um grupo de complementos. Grupo de complementos: define:

• quais opções estão disponíveis;
• quantas opções o cliente pode escolher;
• como calcular o preço do grupo (média, soma, maior valor ou menor valor);
• o preço de cada opção naquele grupo (a mesma opção pode ter preços diferentes em grupos distintos).

Grupos e opções existem de forma independente no catálogo e podem ser reutilizados: um grupo pode estar associado a vários itens, e uma opção pode pertencer a vários grupos. O valor final do produto é a soma do preço base com os preços das opções escolhidas, respeitando a regra de cálculo de cada grupo.

​

Combo

Um combo vende uma combinação específica de produtos por um preço diferente da soma dos preços individuais. Combos não usam grupos de complementos. Eles usam etapas do combo: cada etapa lista produtos possíveis, e o cliente escolhe um por etapa. Cada etapa referencia produtos já cadastrados. O cliente escolhe os complementos do produto normalmente, mas a etapa ignora o preço de venda original e aplica o preço definido nela. Se o produto escolhido tiver complementos pagos, você define na etapa se o valor desses complementos soma ao valor da etapa ou é ignorado. Itens da etapa também podem ter um valor adicional quando o cliente os seleciona. Esse adicional soma ao valor da etapa e, quando configurado assim, também aos complementos.

​

Integração de pedidos

O módulo de pedidos permite receber pedidos feitos na Cardápio Web e alterar o status deles. Integradoras que enviam pedidos para a plataforma podem usar o endpoint Criar pedido. Autenticação: com OAuth, exige o escopo orders. No modelo legado, a maioria dos endpoints exige apenas X-API-KEY; a criação de pedidos também exige X-PARTNER-KEY (consulte API Key (legado)). Para consultar pedidos concluídos ou cancelados em um período, use o endpoint Histórico de pedidos.

​

Receber novos pedidos e alterações de status

Há duas formas de acompanhar novos pedidos e mudanças de status:

• Webhook (recomendado): a Cardápio Web envia notificações em tempo real.
• Polling: você faz verificações periódicas para obter as atualizações.

Em qualquer um dos modelos, o retorno inicial traz dados resumidos do pedido. Use o endpoint Consultar detalhes do pedido para obter o pedido completo a partir do order_id. O schema do retorno está documentado na referência desse endpoint.

​

Integração via webhook

Para receber notificações em tempo real, configure webhooks. Valide o token e responda HTTP 200 em até 5 segundos. Consulte Consultar detalhes do pedido para obter o pedido completo a partir do order_id. A Visão geral dos webhooks traz sugestões de processamento assíncrono, além de detalhes sobre configuração, autenticação e retentativas.

​

Integração via polling

Use o endpoint Consultar pedidos quando webhook não for viável. Por padrão, ele retorna pedidos modificados nas últimas 8 horas. Você também pode filtrar por status ou pela data da última modificação. Para otimizar o fluxo, registre o horário da última requisição bem-sucedida e envie esse valor no parâmetro updated_since na consulta seguinte. Assim, você recebe apenas as alterações desde a última sincronização. Por segurança, aplique uma pequena margem de tempo ao valor enviado para compensar diferenças de relógio entre os servidores. O retorno traz dados resumidos dos pedidos. Para cada item relevante, obtenha os detalhes completos em Consultar detalhes do pedido. A cada requisição, percorra a lista e identifique:

• pedidos que ainda não foram integrados;
• pedidos que tiveram mudança de status ou outras alterações.

Em seguida, integre os pendentes ou atualize os registros existentes. Se optar por polling, o intervalo recomendado é de 30 segundos. Mesmo assim, prefira webhook sempre que possível.

​

Alterar status dos pedidos

O módulo de pedidos também permite alterar o status pelos endpoints de edição. Os principais são: Consulte a documentação de cada endpoint para entender regras e parâmetros específicos. Para usar esses endpoints corretamente, conheça os status possíveis, o contexto de cada um e as transições válidas entre eles. O schema completo está em Consultar detalhes do pedido. O diagrama abaixo representa visualmente os status e suas transições.

​

Próximos passos