API Key (legado)

Este é o modelo de autenticação legado da API aberta. Integrações existentes podem continuar usando-o por enquanto, mas novas integrações devem usar OAuth.

O modelo por API Key será descontinuado no futuro. Recomendamos migrar integrações legadas para OAuth o quanto antes.

Para entender quando cada modelo se aplica, consulte Modelos de autenticação.

No legado, dois tokens podem estar envolvidos:

X-API-KEY: token do estabelecimento, gerado no Portal. Identifica qual loja está sendo acessada.
X-PARTNER-KEY: token da integradora, emitido após o cadastro da integradora. Identifica qual parceiro está fazendo a chamada.

X-API-KEY

Gere o token no Portal: Configurações → Integrações → API. Inclua em todas as requisições:

X-API-KEY: seu_token_do_estabelecimento

Se o token for inválido ou ausente, a API retorna HTTP 401 Unauthorized.

Exemplo (Sandbox):

curl https://integracao.sandbox.cardapioweb.com/api/partner/v1/merchant \
  -H "X-API-KEY: SEU_TOKEN_DO_ESTABELECIMENTO"

Sandbox

Para testes no ambiente Sandbox, existe um estabelecimento padrão. Consulte o token e o link do cardápio de teste em Sobre a API — Ambientes.

X-PARTNER-KEY

Além do X-API-KEY, alguns endpoints exigem o token da integradora:

X-PARTNER-KEY: token_da_integradora

Solicite o token pelo e-mail integracao@cardapioweb.com após o cadastro da integradora.

Requisitos por módulo

Módulo	Endpoints	Headers exigidos
Loja	Consulta de loja (`GET /merchant`)	`X-API-KEY`
Loja	Listar métodos de pagamento	`X-API-KEY` + `X-PARTNER-KEY`
Catálogo	Consulta e gestão do cardápio (`/catalog` e `/catalog/*`, exceto insumos)	`X-API-KEY` + `X-PARTNER-KEY`
Pedidos	Consulta, polling, alteração de status	`X-API-KEY`
Pedidos	Criar pedido (`POST /orders`)	`X-API-KEY` + `X-PARTNER-KEY`

Os endpoints de insumos, de resumo de pedidos, de atualização da loja, de rankings de vendas e de entregadores exigem OAuth e não aceitam API Key. A consulta da loja continua disponível com API Key. A associação e a remoção de um entregador do pedido exigem os escopos orders e drivers. Exemplo com autenticação dupla (Sandbox):

curl https://integracao.sandbox.cardapioweb.com/api/partner/v1/catalog \
  -H "X-API-KEY: SEU_TOKEN_DO_ESTABELECIMENTO" \
  -H "X-PARTNER-KEY: SEU_TOKEN_DA_INTEGRADORA"

Limitações do modelo legado

Um token por estabelecimento, compartilhado manualmente
Sem controle granular por app: revogar um sistema pode exigir trocar o token e desconectar outros
Sem escopos: o token concede acesso amplo
Não elegível para publicação na CW App Store

Migração para OAuth

Para participar da CW App Store e oferecer instalação controlada por estabelecimento, migre para OAuth. O fluxo envolve cadastro do app, implementação do authorization code com PKCE e substituição do X-API-KEY por Authorization: Bearer. Entre em contato com integracao@cardapioweb.com para orientação sobre migração.

Visão geral

CW App Store

Uso da API

X-API-KEY

Sandbox

X-PARTNER-KEY

Requisitos por módulo

Limitações do modelo legado

Migração para OAuth

​X-API-KEY

​Sandbox

​X-PARTNER-KEY

​Requisitos por módulo

​Limitações do modelo legado

​Migração para OAuth

X-API-KEY

Sandbox

X-PARTNER-KEY

Requisitos por módulo

Limitações do modelo legado

Migração para OAuth