Autenticação
Autenticação por chave de API e limites de requisições
Autenticação
Todas as requisições à API do Umbrella exigem autenticação. Há dois métodos, dependendo do endpoint.
Autenticação por cabeçalhos da Shopify
Os endpoints públicos (dados do widget, sinistros, consultas de apólices) se autenticam com cabeçalhos de domínio da loja Shopify:
X-Shopify-Shop-Domain: your-store.myshopify.com
X-Shopify-Customer-Id: 1234567890Quando você instala o app do Umbrella na Shopify, o domínio da sua loja é registrado automaticamente. Não é necessária nenhuma configuração manual para os endpoints da loja virtual.
Autenticação por chave de API interna
Os endpoints do lado do servidor (avaliação de elegibilidade, sincronização de produtos) se autenticam com uma chave de API no corpo da requisição:
{
"internalApiKey": "your-internal-api-key",
"orgId": "your-org-id"
}Para gerar ou rotacionar uma chave de API interna:
- Acesse Painel > Configurações > Integrações
- Localize a seção Chaves de API
- Clique em Gerar nova chave ou Rotacionar chave
Rotacionar uma chave invalida a anterior imediatamente. Atualize todas as integrações antes de rotacionar.
Ambientes de teste e de produção
| Ambiente | Domínio da loja | Comportamento |
|---|---|---|
| Teste | *.test, demo.myshopify.com, test.myshopify.com | Retorna dados fictícios, sem transações reais |
| Produção | O seu domínio *.myshopify.com real | Dados reais, transações reais |
As requisições em modo de teste retornam "testingMode": true nas respostas e usam dados de garantia de exemplo.
Tratamento de erros
Códigos de status de erro comuns a todos os endpoints:
| Status | Significado |
|---|---|
400 | Parâmetros ausentes ou inválidos |
401 | Nenhuma credencial de autenticação foi enviada |
403 | Origem não autorizada ou chave de API inválida |
404 | Recurso não encontrado |
408 | Tempo limite da requisição esgotado (limite de 25 segundos) |
429 | Limite de requisições excedido — aguarde e tente novamente |
500 | Erro interno do servidor |
Ao receber uma resposta 429, aguarde o período indicado antes de enviar novas requisições. Implemente backoff exponencial em cenários de alto volume.
Relacionados
- Visão geral dos endpoints — Lista completa dos endpoints disponíveis
- API de garantias — Endpoints de gerenciamento de planos de garantia
- Referência de webhooks — Integrações orientadas a eventos
