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

  1. No painel administrativo da loja, acesse Extensões e Integrações › API Admin:

    https://{sualoja}.fbits.app/integracoes/admin-api

    A página lista as aplicações já cadastradas na loja.

  2. Clique em Nova aplicação e preencha:

    CampoDescrição
    NomeIdentifica a aplicação na listagem. Obrigatório.
    Client IDSugerido a partir do nome. O prefixo da loja é fixo (ex.: minhaloja-integrador-de-promocoes). Obrigatório.
    AtivaStatus da aplicação.
    DescriçãoPara que serve a integração. Até 200 caracteres.
    Perfis de acessoUm ou mais perfis que definem o que a aplicação pode fazer. Veja Perfis de acesso.
  3. Clique em Salvar. A janela Aplicação criada mostra o client_id e o client_secret. Copie o secret com Copiar secret.

🚧

Guarde o client secret

Armazene o client_secret em 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"
HeaderValorObservação
AuthorizationBearer {access_token}Token gerado no passo 2.
x-api-version2.0Obrigatório. Sem ele, a resposta é 400 com code API_VERSION_REQUIRED.
📘

Identificação da loja

Nenhum 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.

ItemValor
Limite geral200 requisições por minuto, somando todos os endpoints liberados para a aplicação
Escrita de promoções20 requisições por minuto, em um limite próprio (veja abaixo)
ContagemPor aplicação (client_id)
📘

O limite geral não é por endpoint

As 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étodoRota
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 lote

Se 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 429 aguardando o tempo indicado no header Retry-After.

Headers de controle

Toda resposta traz os headers abaixo, para a integração acompanhar o próprio consumo:

HeaderDescrição
X-RateLimit-LimitQuantidade 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-RemainingQuantas requisições ainda restam nesse limite no momento.
Retry-AfterEnviado 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 header Retry-After antes 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-Remaining e 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

HTTPcodeCausa
401SESSION_INVALIDToken ausente, inválido ou expirado; aplicação não encontrada ou sem acesso à loja.
401UNAUTHORIZEDOs perfis de acesso da aplicação não permitem o endpoint chamado.
400API_VERSION_REQUIREDHeader x-api-version ausente ou vazio.
429RATE_LIMIT_EXCEEDEDA 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ções

O acesso de aplicações à Admin API precisa estar habilitado para a loja. Se o token for válido mas as chamadas retornarem 401 com code SESSION_INVALID, solicite a habilitação ao suporte Wake.