CORS e versões

Esta página trata de dois assuntos que aparecem cedo em qualquer integração: o que o navegador permite (CORS) e qual versão da API usar.

CORS

CORS (Cross-Origin Resource Sharing) é a regra do navegador que impede uma página de um site de ler respostas de outro, a menos que o servidor autorize. Se o seu código roda no navegador, em um domínio que não é o da loja, a chamada pode ser bloqueada mesmo que o servidor tenha respondido 200.

O que a API autoriza

• Origens permitidas. O servidor mantém uma lista de origens autorizadas (os subdomínios da plataforma e os domínios personalizados cadastrados pelas lojas). Quando a origem da requisição está na lista, a resposta repete o valor em Access-Control-Allow-Origin. Quando não está, esse cabeçalho não vem e o navegador bloqueia a leitura.
• Credenciais. Access-Control-Allow-Credentials: true: cookies e cabeçalhos de autorização podem acompanhar a chamada.
• Métodos. GET, POST, PUT, PATCH, DELETE, OPTIONS.
• Cabeçalhos aceitos na requisição. Content-Type, Authorization, X-API-Key, X-Tenant-ID, X-Storefront-ID, X-Request-ID, X-Session-ID, X-Recaptcha-Token, X-Venddor-Locale, Idempotency-Key. Um cabeçalho personalizado fora desta lista faz o preflight falhar.
• Cache do preflight. Access-Control-Max-Age: 86400 (24 horas).

Preflight

Antes de uma chamada "não simples" (com Authorization ou Content-Type: application/json), o navegador envia sozinho um OPTIONS. A API responde 204 sem corpo com os cabeçalhos acima.

OPTIONS /api/v1/admin/products HTTP/1.1
Origin: https://minhaloja.io.venddor.com.br
Access-Control-Request-Method: GET
Access-Control-Request-Headers: authorization

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://minhaloja.io.venddor.com.br
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 86400

Cabeçalhos de segurança

Todas as respostas trazem X-Content-Type-Options: nosniff, X-Frame-Options: DENY e Referrer-Policy: strict-origin-when-cross-origin. Eles não afetam integrações de servidor.

Versões

Regras de convivência:

• A versão é o prefixo da URL. Não há Accept-Version nem cabeçalho equivalente.
• Mudanças compatíveis acontecem dentro da mesma versão: novos campos em respostas, novos parâmetros opcionais, novas rotas. Escreva clientes tolerantes, que ignorem campos desconhecidos e não dependam da ordem das chaves.
• Não dependa de campos não documentados. Respostas podem trazer campos auxiliares (por exemplo, order_id e total_str ao lado de id e total). Use os campos documentados na página da rota.

# Preflight manual, útil para depurar um bloqueio de CORS
curl -i -X OPTIONS "$BASE_URL/api/v1/storefront/products" \
  -H "Origin: https://loja.exemplo.com.br" \
  -H "Access-Control-Request-Method: GET" \
  -H "Access-Control-Request-Headers: authorization"

Erros comuns

• "No 'Access-Control-Allow-Origin' header" no console. A origem da página não está autorizada, ou a chamada saiu para um endereço que não é o da loja. Chame o host da loja e confira o domínio da página.
• O curl funciona e o navegador não. O curl não aplica CORS. Reproduza o preflight com curl -X OPTIONS e compare.
• Cabeçalho personalizado sem estar na lista. O preflight reprova e a chamada real nem sai.

Veja também