Escopos de acesso

Os escopos definem quais grupos de endpoints uma chave de API pode acessar. Cada chave também está vinculada a uma loja e a um ambiente; ter um escopo não permite consultar dados de outra loja ou de outro ambiente.

Escopos disponíveis

Escopo	Recursos	Endpoints protegidos
store	Configuração da loja e cupons	GET /api/store/info/, GET /api/coupon/list, GET /api/coupon/details/
crm	Clientes, avaliações e campanhas	GET /api/customer/list, GET /api/review/list, GET /api/review/details/, GET /api/campaign/list, GET /api/campaign/details/
order	Pedidos	GET /api/order/list, GET /api/order/details/
menu	Cardápio, categorias, produtos e grupos de complementos	GET /api/menu/, GET /api/category/list, GET /api/category/details/, GET /api/product/list, GET /api/product/details/, GET /api/option-group/list

O endpoint GET /api/customer/order-list/ exige dois escopos: crm para identificar o cliente e order para retornar os pedidos.

Como os escopos são concedidos

Os escopos são configurados na chave de API no processo de criação ou gestão das chaves. A resposta de POST /api/auth/token/ inclui o campo scope, com os escopos concedidos ao token separados por espaço. A solicitação de token aceita um parâmetro scope opcional para pedir apenas parte dos escopos da chave; a integração não consegue ampliar as próprias permissões além do que a chave possui.

Conceda à chave apenas os escopos necessários para a integração. Se algum endpoint necessário estiver fora dos escopos da chave, solicite ao responsável pela gestão da chave que ajuste a configuração. Alterações nos escopos passam a valer imediatamente, inclusive para tokens já emitidos; um token, porém, nunca recebe escopos além dos que foram pedidos na sua emissão.

Endpoints sem escopo

• POST /api/auth/token/ usa client_id e client_secret para emitir o token; não exige um token bearer nem um escopo.
• GET /health informa a disponibilidade do serviço e não exige autenticação.

Todos os demais endpoints de dados publicados na Referência da API exigem autenticação e um ou mais escopos. Na referência, os endpoints estão agrupados pelo escopo exigido.

Erro por falta de escopo

Se o token não tiver todos os escopos exigidos por um endpoint, a resposta será 403 Forbidden, com code igual a insufficient_scope e o cabeçalho WWW-Authenticate: Bearer ..., error="insufficient_scope", scope="...". O campo detail informa os escopos ausentes. Se o token foi emitido com um scope restrito, emita outro incluindo o escopo necessário; se a chave não possui o escopo, é necessário ajustar os escopos associados a ela.