Autenticação
Integrações servidor-a-servidor com a Admin API se autenticam com uma aplicação cadastrada na loja. A aplicação tem um client_id e um client_secret, que geram o token de acesso pelo fluxo OAuth 2.0 client credentials.
1. Cadastre uma aplicação
-
No painel administrativo da loja, acesse Extensões e Integrações › API Admin:
https://{sualoja}.fbits.app/integracoes/admin-apiA página lista as aplicações já cadastradas na loja.
-
Clique em Nova aplicação e preencha:
Campo Descrição Nome Identifica a aplicação na listagem. Obrigatório. Client ID Sugerido a partir do nome. O prefixo da loja é fixo (ex.: minhaloja-integrador-de-promocoes). Obrigatório.Ativa Status da aplicação. Descrição Para que serve a integração. Até 200 caracteres. Perfis de acesso Um ou mais perfis que definem o que a aplicação pode fazer. Veja Perfis de acesso. -
Clique em Salvar. A janela Aplicação criada mostra o
client_ide oclient_secret. Copie o secret com Copiar secret.
Guarde o client secretArmazene o
client_secretem um cofre de credenciais. Depois, ele só pode ser consultado na tela da aplicação por quem tem a permissão ApplicationsSecrets.
Perfis de acesso
Os perfis de acesso são os mesmos que podem ser associados aos usuários do painel administrativo. Eles controlam quais operações a aplicação pode executar e, portanto, quais endpoints ela pode chamar. A aplicação só acessa os endpoints permitidos pelos seus perfis.
Chamadas a um endpoint sem a permissão exigida retornam 401 com code UNAUTHORIZED. As permissões exigidas por cada endpoint estão na descrição dele em Referências de API.
2. Gere o token de acesso
Com o client_id e o client_secret, solicite o token ao Wake SSO:
curl -X POST "https://wake-sso.fbits.net/realms/master/protocol/openid-connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id={client_id}" \
-d "client_secret={client_secret}"A resposta traz o access_token e o tempo de validade em segundos (expires_in). Reaproveite o token até ele expirar e então gere outro.
3. Chame a Admin API
Envie o token no header Authorization de toda requisição, junto com o header x-api-version:
curl "https://{loja}.commerce-wake.tech/api/promotions" \
-H "Authorization: Bearer {access_token}" \
-H "x-api-version: 2.0"| Header | Valor | Observação |
|---|---|---|
Authorization | Bearer {access_token} | Token gerado no passo 2. |
x-api-version | 2.0 | Obrigatório. Sem ele, a resposta é 400 com code API_VERSION_REQUIRED. |
Identificação da lojaNenhum endpoint pede a loja: ela é sempre a loja à qual a aplicação pertence. O autor das alterações registrado nos históricos também vem do token: para aplicações, é o
client_id.
Limite de requisições
Para garantir a estabilidade da plataforma, a Admin API limita a quantidade de requisições que cada aplicação pode fazer.
| Item | Valor |
|---|---|
| Limite geral | 200 requisições por minuto, somando todos os endpoints liberados para a aplicação |
| Escrita de promoções | 20 requisições por minuto, em um limite próprio (veja abaixo) |
| Contagem | Por aplicação (client_id) |
O limite geral não é por endpointAs 200 requisições por minuto são compartilhadas entre todos os endpoints. Por exemplo: se a aplicação fizer 150 chamadas em produtos e 50 em pedidos no mesmo minuto, ela já terá atingido o limite.
O limite funciona como um saldo: a aplicação pode fazer até 200 requisições de uma só vez, e esse saldo é reposto aos poucos, cerca de 3 requisições por segundo. Na prática, quem mantém um ritmo constante de até 200 requisições por minuto não é bloqueado.
Escrita de promoções
As rotas que criam, alteram ou excluem promoções têm um limite próprio de 20 requisições por minuto:
| Método | Rota |
|---|---|
POST | /api/promotions |
POST | /api/promotions/duplicate |
PUT | /api/promotions/{promotionId} |
PUT | /api/promotions/{promotionId}/status |
DELETE | /api/promotions |
POST | /api/promotions/batch-delete |
Esse limite é separado do limite geral: as chamadas dessas rotas não consomem as 200 requisições por minuto, e as consultas de promoções seguem no limite geral. O saldo de escrita é reposto a uma requisição a cada 3 segundos.
Criação de promoções em loteSe a integração cria ou altera muitas promoções de uma vez, distribua as chamadas para não passar de 20 por minuto e trate o retorno
429aguardando o tempo indicado no headerRetry-After.
Headers de controle
Toda resposta traz os headers abaixo, para a integração acompanhar o próprio consumo:
| Header | Descrição |
|---|---|
X-RateLimit-Limit | Quantidade máxima de requisições do limite que se aplica à rota chamada (200 no limite geral ou 20 na escrita de promoções). |
X-RateLimit-Remaining | Quantas requisições ainda restam nesse limite no momento. |
Retry-After | Enviado apenas quando o limite é excedido: quantos segundos esperar antes de tentar de novo. |
Quando o limite é excedido
A requisição é recusada com status 429 Too Many Requests e code RATE_LIMIT_EXCEEDED, com a mensagem "Limite de requisições excedido. Tente novamente em N segundo(s).".
Boas práticas para evitar o bloqueio:
- Ao receber
429, aguarde o tempo indicado no headerRetry-Afterantes de reenviar a requisição. - Distribua as chamadas ao longo do tempo em vez de disparar grandes lotes em paralelo.
- Acompanhe o header
X-RateLimit-Remaininge reduza o ritmo quando o valor estiver próximo de zero. - Reaproveite o token até ele expirar, sem pedir um novo a cada chamada.
Erros de autenticação
| HTTP | code | Causa |
|---|---|---|
401 | SESSION_INVALID | Token ausente, inválido ou expirado; aplicação não encontrada ou sem acesso à loja. |
401 | UNAUTHORIZED | Os perfis de acesso da aplicação não permitem o endpoint chamado. |
400 | API_VERSION_REQUIRED | Header x-api-version ausente ou vazio. |
429 | RATE_LIMIT_EXCEEDED | A aplicação excedeu o limite de requisições (200 por minuto no geral ou 20 por minuto na escrita de promoções). Aguarde o tempo indicado no header Retry-After e tente novamente. Veja Limite de requisições. |
Acesso de aplicaçõesO acesso de aplicações à Admin API precisa estar habilitado para a loja. Se o token for válido mas as chamadas retornarem
401comcodeSESSION_INVALID, solicite a habilitação ao suporte Wake.
Updated 9 days ago

