Fluxo completo, etapa por etapa
O fluxo envolve o portal da Cardápio Web, a URL de instalação (link do botão Instalar) e a Redirect URI (callback OAuth) do app. Em cada etapa, o estabelecimento e a integradora têm papéis distintos.1
1. Instalar no marketplace
Estabelecimento: No menu CW App Store, o Proprietário navega pelo catálogo (ou abre o link de um app privado), abre a página do app e clica em Instalar.Integradora: O app precisa estar aprovado no ambiente em que a instalação ocorre (Sandbox ou Produção). Campos de catálogo, URLs e permissões devem estar corretos antes de o cliente tentar instalar. Detalhes em Cadastro e publicação.
2
2. Onboarding do parceiro
Estabelecimento: Ao clicar em Instalar, o navegador abre a URL de instalação do app, ou seja, a página do sistema da integradora para onde o botão Instalar aponta. O Proprietário já está logado na Cardápio Web.Integradora: Essa URL é informada ao suporte no cadastro do app (veja Cadastro e publicação). Recomendamos que seja uma página de onboarding ou cadastro no seu sistema, onde o Proprietário cria conta ou vincula o estabelecimento antes da autorização OAuth.A Cardápio Web abre essa URL sem enviar parâmetros na query string (sem
client_id, company_id, state, etc.). Conduza o onboarding necessário no seu sistema.3
3. Consentimento e escolha da loja
Integradora: Com o Proprietário já cadastrado no seu sistema, inicie a integração com a Cardápio Web redirecionando-o para a página de autorização do portal CW (
https://portal.cardapioweb.com/cw-apps) com os parâmetros PKCE (client_id, state, redirect_uri, code_challenge, code_challenge_method). O redirect_uri deve ser idêntico à Redirect URI (redirect_url) informada ao suporte no cadastro. A implementação técnica e os hosts por ambiente estão em OAuth.Estabelecimento: No portal, o Proprietário vê a tela Autorizar aplicativo. Nela constam o nome do app, um seletor de loja para escolher qual estabelecimento será autorizado e a lista de permissões que o app solicita. O Proprietário seleciona a loja desejada e confirma ou cancela.4
4. Retorno ao app parceiro
Estabelecimento: Após confirmar, o Proprietário é redirecionado para a Redirect URI do app (pode ver brevemente a URL do parceiro no navegador).Integradora: A Redirect URI recebe
code e state na query string. Neste momento a autorização foi concedida, mas a integração ainda não está ativa: a Partner API e os webhooks só passam a funcionar após a troca de token.Valide o state e, no servidor, troque o code por access_token e refresh_token via POST /api/partner/oauth/token. Persista as credenciais vinculadas à instalação. Consulte OAuth.5
5. App instalado no portal
Estabelecimento: Após a troca de token bem-sucedida, o app passa a constar em CW App Store → Instalados, com status Instalado. Os botões Acessar e Desinstalar ficam disponíveis na página do app.Se a integradora informou uma URL de webhook no cadastro, o webhook da instalação é criado ou atualizado automaticamente, sem ação adicional do restaurante.Integradora: Com o
POST /api/partner/oauth/token concluído, a instalação está ativa. A partir deste momento, use os tokens para chamar a API aberta. O contexto do estabelecimento é resolvido automaticamente pelo token. Cada instalação deve ser tratada como um contexto isolado no seu sistema (credenciais, filas, webhooks).6
6. Uso contínuo
Estabelecimento: O botão Acessar abre a URL de login do app, que leva ao sistema da integradora. Enquanto a instalação estiver ativa, o restaurante não precisa repetir o fluxo de autorização para o app continuar consumindo a API.Integradora: Renove tokens com
refresh_token antes da expiração. Trate cada estabelecimento instalado como um tenant separado no seu backend.Várias lojas
Uma conta na Cardápio Web pode operar mais de um estabelecimento. Nesse caso, cada loja é um contexto independente para o app: instalar em uma unidade não autoriza o acesso às outras. O Proprietário repete o fluxo completo (Instalar, onboarding, consentimento) para cada loja que deve usar a integração. Na tela de consentimento, a loja de instalação indica qual unidade está sendo autorizada. Vale conferir esse dado antes de confirmar: se a loja estiver errada, é preciso desinstalar e repetir o fluxo na unidade correta. Do lado da integradora, cada loja gera uma instalação com tokens próprios. Armazene credenciais separadas por estabelecimento. Um token emitido para uma loja não acessa dados de outra, mesmo quando ambas pertencem à mesma conta. Desinstalar o app em uma loja encerra a integração apenas naquela unidade. Instalações do mesmo app em outras lojas continuam ativas.Revogação e gestão pós-instalação
Com o app instalado, o Proprietário gerencia a integração pela página do app em CW App Store → Instalados. A integradora acompanha o estado das instalações no backend e reage a revogações ou expiração de tokens.Acessar
O botão Acessar redireciona o Proprietário para a URL de login do app, ou seja, o endereço do sistema da integradora informado ao suporte no cadastro. Essa ação não altera tokens, permissões nem o status da instalação.Desinstalar
Quando o Proprietário clica em Desinstalar, a integração é encerrada naquela loja. O app deixa de aparecer como instalado para aquela unidade. Na sequência, os tokens da instalação são revogados. Chamadas à API com credenciais daquela instalação passam a retornar HTTP 401, e a entrega de webhooks para ela é interrompida. A desinstalação afeta somente a loja em questão: outras unidades, outros apps da mesma conta e outras instalações do mesmo app permanecem inalteradas. A integradora deve tratar a desinstalação como fim do vínculo com aquele estabelecimento. Pare de consumir a API e de processar eventos com os tokens revogados.Reinstalar
Se o Proprietário instalar o app novamente na mesma loja, o fluxo de autorização é repetido do início. A instalação é reativada e novos tokens substituem os anteriores, com os escopos vigentes cadastrados no app no momento da reinstalação.Revogação pela integradora
Além da desinstalação pelo portal, a integradora pode revogar tokens programaticamente viaPOST /api/partner/oauth/revoke. Consulte Revogar token.
Use essa opção quando o cliente encerra o contrato no seu sistema antes de desinstalar no portal, ou quando precisa invalidar credenciais comprometidas. A desinstalação feita pelo Proprietário no portal também revoga os tokens ativos da instalação.
Próximos passos
OAuth
Implementação técnica de autorização, tokens e escopos.
Primeiros passos
Trilha hands-on: Sandbox, OAuth e primeira chamada à API.
Cadastro e publicação
Campos de cadastro, aprovação e manutenção do app.
Fluxos de integração
Módulos Loja, Catálogo e Pedidos após a autorização.