OAuth

Apps da CW App Store autenticam-se via OAuth 2.0 Authorization Code com PKCE. Após o Proprietário autorizar no portal e a integradora concluir a troca de token no servidor, o app recebe credenciais para consumir a API aberta.

Entenda também a instalação e autorização do ponto de vista do estabelecimento e da integradora.

Somente usuários com perfil Proprietário podem autorizar a instalação de um app no portal. Ao redirecionar o cliente para a página de autorização do portal CW, confirme que ele está logado com a conta de Proprietário do estabelecimento. Outros perfis recebem access_denied.

Endpoints

O fluxo OAuth usa dois hosts distintos: o portal CW (frontend) para autorização e a API aberta para troca e renovação de tokens. Use sempre o par do mesmo ambiente (Sandbox ou Produção).

Autorização (portal CW)

Após o onboarding, redirecione o Proprietário para a página de autorização do portal no ambiente em que o app está cadastrado:

Ambiente	URL de autorização
Sandbox	`https://portal.sandbox.cardapioweb.com/cw-apps`
Produção	`https://portal.cardapioweb.com/cw-apps`

Troca e renovação de token (API)

Método	Path	Descrição
POST	`/api/partner/oauth/token`	Troca código ou refresh token por access token

Ambiente	Base URL da API
Sandbox	`https://integracao.sandbox.cardapioweb.com`
Produção	`https://integracao.cardapioweb.com`

Os exemplos abaixo usam o Sandbox; substitua os hosts ao integrar em Produção. Detalhes dos ambientes em Sobre a API. Referência interativa na aba Referência da API:

Obter token

Fluxo resumido

1. Gerar PKCE

Antes de redirecionar o Proprietário para a página de autorização do portal CW (https://portal.cardapioweb.com/cw-apps), gere:

code_verifier: string aleatória (43–128 caracteres)
code_challenge: Base64 URL-safe do SHA-256 do code_verifier
code_challenge_method: S256

Guarde o code_verifier para a troca de token. Exemplo com OpenSSL:

CODE_VERIFIER=$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=')

2. Autorização

Após o onboarding na URL de instalação do app, redirecione o Proprietário para a página de autorização do portal CW (https://portal.cardapioweb.com/cw-apps) com:

Parâmetro	Quem gera	Descrição
`client_id`	CW	Identificador público do app na CW App Store.
`state`	Integradora	Parâmetro de correlação; o portal devolve o mesmo valor no callback.
`redirect_uri`	Integradora	Deve ser idêntica à Redirect URI informada ao suporte no cadastro do app.
`code_challenge`	Integradora	Derivado do `code_verifier` (SHA-256 + Base64 URL-safe).
`code_challenge_method`	Fixo	Sempre `S256`.

Exemplo de URL (Sandbox):

https://portal.sandbox.cardapioweb.com/cw-apps
  ?client_id=SEU_CLIENT_ID
  &state=usr_abc123
  &redirect_uri=https://seuapp.com/oauth/callback
  &code_challenge=CHALLENGE
  &code_challenge_method=S256

Sobre o `state`

O state é um parâmetro de correlação que você envia no início do fluxo e recebe de volta no redirect para a redirect_uri (?code=...&state=...). Serve para retomar o contexto daquela autorização no seu sistema. Exemplo: durante o onboarding, o Proprietário está vinculado ao usuário interno usr_abc123 no seu sistema. Ao redirecionar para https://portal.cardapioweb.com/cw-apps, envie state=usr_abc123 (ou um token opaco que mapeie para esse usuário). Quando o portal redirecionar de volta para a Redirect URI com o mesmo state, você saberá para qual usuário aquela autorização foi concluída. Recomendações:

Gere e persista o state no backend antes do redirect (não confie apenas em estado no frontend).
No callback, valide que o state retornado é um valor que você emitiu e que ainda está válido (expiração, uso único, etc.).
Pode ser um ID interno, um UUID ou um valor opaco assinado. O importante é permitir identificar o contexto da instalação no seu lado.

Não envie code_verifier na URL. Ele permanece somente no servidor da integradora até o POST /api/partner/oauth/token. Valide o state recebido no callback antes de trocar o código por tokens.

O que o portal faz

O portal CW conduz a autorização e redireciona para sua Redirect URI. Você não implementa estas etapas:

Verifica o login do Proprietário; se necessário, redireciona ao login e retorna à página de autorização com os mesmos parâmetros.
Exibe o consentimento (app, loja, permissões).
Redireciona o navegador para a redirect_uri com ?code=...&state=....

3. Troca de token

Apps de integradoras são clientes públicos: não há segredo no fluxo de instalação. A segurança vem do PKCE e da troca de token feita no servidor da integradora. Os passos de PKCE e redirect ao portal estão nas seções Gerar PKCE e Autorização. A partir do callback na Redirect URI:

1. Receber o callback

A Redirect URI recebe code e state na query string. A autorização foi concedida, mas a integração ainda não está ativa.

2. Validar o state

Confirme que o state retornado é um valor que você emitiu e que ainda está válido.

3. Trocar o código no servidor

No servidor, chame POST /api/partner/oauth/token com grant_type=authorization_code, o code, o mesmo redirect_uri, o client_id e o code_verifier.

4. Persistir por loja

Armazene access_token e refresh_token vinculados à instalação (contexto da loja autorizada). Cada loja gera tokens próprios.

Exemplo de requisição (Sandbox):

curl -X POST https://integracao.sandbox.cardapioweb.com/api/partner/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=CODIGO_RECEBIDO" \
  -d "redirect_uri=https://seuapp.com/oauth/callback" \
  -d "client_id=SEU_CLIENT_ID" \
  -d "code_verifier=SEU_CODE_VERIFIER"

Resposta esperada:

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "...",
  "scope": "store orders"
}

O access_token expira em 2 horas (expires_in: 7200 segundos). Com a troca bem-sucedida, a instalação fica ativa e a Partner API e os webhooks passam a operar para aquela loja.

4. Escopos e permissões

Com OAuth, as permissões do app vêm inteiramente do cadastro informado ao suporte. A integradora não escolhe nem envia escopos na URL de autorização: o portal concede todas as permissões cadastradas no consentimento. Tokens só acessam endpoints cujo escopo está presente no token e na instalação ativa.

Escopos disponíveis

Escopo	Recursos	Módulo da API
`store`	Dados da loja e formas de pagamento	Consultar loja
`orders`	Consulta, criação e alteração de pedidos	API Pedidos
`catalog`	Consulta e gestão do catálogo	API Catálogo
`customers`	Clientes do estabelecimento	Listar clientes
`coupons`	Cupons de desconto	Listar cupons
`reviews`	Avaliações	Listar avaliações

Como funcionam

No cadastro do app, informe ao suporte as permissões necessárias.
Na instalação, o Proprietário autoriza todas as permissões cadastradas no portal.
O token OAuth recebe os escopos concedidos naquela instalação.
A API aberta valida o escopo do token e o estado atual da instalação.

Solicite apenas os escopos que seu app realmente usa. Permissões excedidas dificultam aprovação e reduzem a confiança do restaurante.

Se precisar de novas permissões após o app já estar publicado, solicite a alteração ao suporte. Lojas já instaladas precisam reinstalar o app para que os novos escopos passem a valer. Se o token não possui o escopo exigido pelo endpoint, a API retorna HTTP 403. Autenticação por X-API-KEY não aplica escopos. Veja API Key (legado).

5. Usar o Bearer na API aberta

curl https://integracao.sandbox.cardapioweb.com/api/partner/v1/merchant \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

O contexto do estabelecimento é resolvido automaticamente pela instalação vinculada ao token.

6. Renovar token

curl -X POST https://integracao.sandbox.cardapioweb.com/api/partner/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=SEU_REFRESH_TOKEN" \
  -d "client_id=SEU_CLIENT_ID"

7. Revogar token

curl -X POST https://integracao.sandbox.cardapioweb.com/api/partner/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=SEU_ACCESS_TOKEN_OU_REFRESH_TOKEN" \
  -d "client_id=SEU_CLIENT_ID"

A desinstalação do app pelo estabelecimento também revoga tokens ativos.

Erros comuns

Situação	Causa provável
`invalid_request` — `state is required`	Parâmetro `state` ausente no redirect para o portal
`access_denied` — somente Proprietário	Usuário sem perfil Proprietário
`invalid_client`	`client_id` inválido ou app não aprovado
Redirect URI inválida	`redirect_uri` não corresponde ao cadastro no redirect ou na troca de token
PKCE inválido	`code_verifier` não corresponde ao `code_challenge`
HTTP 401 na API aberta	Token expirado, revogado ou instalação inativa
HTTP 403 — escopo insuficiente	Token ou instalação sem o escopo exigido pelo endpoint

Não registre em logs valores de access_token, refresh_token, code ou code_verifier.

Visão geral

CW App Store

Uso da API

Endpoints

Autorização (portal CW)

Troca e renovação de token (API)

Fluxo resumido

1. Gerar PKCE

2. Autorização

Sobre o `state`

O que o portal faz

3. Troca de token

4. Escopos e permissões

Escopos disponíveis

Como funcionam

5. Usar o Bearer na API aberta

6. Renovar token

7. Revogar token

Erros comuns

Próximos passos

​Endpoints

​Autorização (portal CW)

​Troca e renovação de token (API)

​Fluxo resumido

​1. Gerar PKCE

​2. Autorização

​Sobre o state

​O que o portal faz

​3. Troca de token

​4. Escopos e permissões

​Escopos disponíveis

​Como funcionam

​5. Usar o Bearer na API aberta

​6. Renovar token

​7. Revogar token

​Erros comuns

​Próximos passos

Endpoints

Autorização (portal CW)

Troca e renovação de token (API)

Fluxo resumido

1. Gerar PKCE

2. Autorização

Sobre o `state`

O que o portal faz

3. Troca de token

4. Escopos e permissões

Escopos disponíveis

Como funcionam

5. Usar o Bearer na API aberta

6. Renovar token

7. Revogar token

Erros comuns

Próximos passos