FAQ
Respostas para perguntas comuns sobre a OlaClick Public API, cada uma com link para a página que a documenta em detalhes.
Acesso e autenticação
Como eu obtenho uma API key?
As API keys são geradas no painel do estabelecimento em Integrações > API Keys. Veja Autenticação.
Como eu autentico minhas requisições?
Envie sua chave no header Authorization: Bearer olk_live_... ou no header X-API-Key: olk_live_.... Veja Autenticação.
Qual a diferença entre a Public API e o OlaClick Hub?
A Public API usa uma API key e dá acesso aos dados da sua própria empresa — é para uma única empresa integrar seus próprios sistemas. O OlaClick Hub usa OAuth 2.1 client credentials e dá acesso aos dados de qualquer empresa conectada — é para desenvolvedores que constroem produtos para várias empresas. Veja Escolha seu caminho de integração.
Limites de taxa e erros
O que acontece se eu exceder o limite de requisições?
As requisições têm limite de taxa por API key. Os headers de resposta (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset) mostram seu uso atual, e exceder o limite retorna 429 Too Many Requests com um header Retry-After. Veja Limitação de taxa.
Como são formatadas as respostas de erro?
Os erros usam RFC 7807 Problem Details — não encapsulados em data — com os campos type, title, status, detail e instance (o caminho da requisição). Veja Erros.
Pedidos e webhooks
Como eu evito criar um pedido duplicado se minha requisição expirar (timeout)?
POST /v1/orders exige o header Idempotency-Key, armazenado como a referência do pedido. Repita a chamada com a mesma chave e a API não criará um segundo pedido. Veja o changelog de Pedidos e o changelog de Infraestrutura.
Quais pedidos eu posso editar, alterar pagamentos, ou cancelar pela API?
Somente pedidos criados pela API podem ser editados, ter itens/descontos alterados, ou ser cancelados. Atualizar pagamentos e alterar o status são exceções que também funcionam em pedidos de outros canais (loja virtual, PDV). Veja o changelog de Pedidos.
Como eu calculo o preço de entrega antes de criar um pedido?
Chame GET /v1/delivery/pricing para saber o modo de precificação do estabelecimento, depois GET /v1/delivery/quote para os modos que precisam de cotação, e envie o resultado como delivery_price em POST /v1/orders. Veja o guia de cálculo de preços de entrega.
Como funcionam os webhooks, e como eu verifico que vieram da OlaClick?
A OlaClick envia um POST para sua URL registrada quando um evento ocorre, assinado com HMAC-SHA256 no header X-OlaClick-Signature. Verifique-o contra o corpo bruto da requisição usando o signing_secret do seu webhook. Veja Webhooks.
O que acontece se meu endpoint não confirmar o recebimento de um webhook?
A OlaClick tenta novamente até max_retry vezes com backoff exponencial (30s, 60s, 120s, ...) se seu endpoint não responder com um código de sucesso. Veja Tentativas.
MCP
O que eu posso fazer pelo servidor MCP?
O servidor MCP expõe a Public API como ferramentas para assistentes de IA: ler menus, pedidos e clientes, e operar toda a pilha de ponta a ponta — criar e avançar pedidos, gerenciar promoções, webhooks, o menu, logística, clientes e endereços. Veja Servidor MCP.
Como eu conecto um cliente MCP, e preciso de uma API key?
Para Claude.ai, Claude Desktop, Claude Code e ChatGPT você pode fazer login via OAuth — sem precisar de API key. Para configurações locais/stdio ou clientes sem suporte a OAuth, gere uma API key e a envie você mesmo. Veja Duas formas de autenticar.
Por que meu cliente MCP pede confirmação antes de algumas ações?
Toda ferramenta carrega anotações MCP (readOnlyHint, destructiveHint, idempotentHint) de acordo com o método HTTP subjacente. Clientes que respeitam essas anotações podem pedir confirmação antes de executar uma ferramenta destructive (baseada em DELETE). Veja Ferramentas de escrita: como se comportam.
Suporte
Para recomendações, relatos de bugs e perguntas, envie um email para api@olaclick.com.
Para nos ajudar a investigar mais rápido, inclua:
- O endpoint que você chamou (método e caminho, ex.:
POST /v1/orders). - O horário (timestamp) da requisição.
- Sua empresa (ou qual API key / integração, sem colar a chave em si).
- O corpo completo da resposta de erro, se houve um — ele carrega
type,detaileinstance(veja Erros).