VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Sessão do cliente

Verificação em duas etapas do cliente

Liga, confere e desliga o segundo fator (aplicativo autenticador) na conta do cliente logado.

A verificação em duas etapas (2FA) pede, além da senha, um código de 6 dígitos gerado por um aplicativo autenticador (Google Authenticator, Authy, 1Password). Estas quatro rotas deixam o cliente ligar e desligar o recurso na própria conta. Os mesmos caminhos existem para administrador e seller, em /api/v1/admin/2fa/... e /api/v1/vendor/2fa/..., com o mesmo comportamento.

Ligar tem dois passos: setup gera um segredo e um QR code; o cliente cadastra no aplicativo e confirm prova que o aplicativo gera códigos corretos. Só então o 2FA fica ativo e a plataforma entrega os códigos de recuperação.

Pontos principais
  • setup, confirm e disable dependem do módulo two-factor-auth da loja (403 module_disabled quando desligado). status funciona sempre.
  • Com o 2FA ativo, o login com senha não devolve tokens: devolve requires_2fa: true e um temp_token. Você conclui em POST /api/v1/auth/verify-2fa com temp_token e code (veja Autenticação).
  • Os 10 códigos de recuperação aparecem uma única vez, no confirm. Cada um serve uma vez no lugar do código do aplicativo.
  • As mutações são bloqueadas quando um administrador está se passando pelo cliente (impersonação): 403 impersonation_blocked.
  1. Gerar o segredo
    POST /2fa/setup devolve secret, otpauth_url e qr_code. Mostre o QR code.
  2. Confirmar
    O cliente digita o código atual do aplicativo; POST /2fa/confirm ativa o 2FA e devolve backup_codes.
  3. Guardar os códigos
    Peça que o cliente salve os códigos de recuperação antes de fechar a tela.
POST/api/v1/storefront/2fa/setupCliente

Gerar o segredo do autenticador

Sem corpo. Cada chamada gera um segredo novo e deixa o 2FA como não confirmado.

bash
curl -X POST "$BASE_URL/api/v1/storefront/2fa/setup" \
  -H "Authorization: Bearer $TOKEN"
200Segredo gerado
json
{
  "secret": "JBSWY3DPEHPK3PXP",
  "otpauth_url": "otpauth://totp/Minha%20Loja:maria.souza@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Minha%20Loja",
  "qr_code": "data:image/png;base64,iVBORw0KGgo..."
}

Campos da resposta

secretstring
Segredo em texto, para digitar no aplicativo se o QR code não puder ser lido.
otpauth_urlstring
URL otpauth:// que o aplicativo entende.
qr_codestring
Imagem PNG do QR code como data: URL em base64, pronta para um img src.
Chamar setup de novo desliga o 2FA

setup troca o segredo e marca o 2FA como desativado até o próximo confirm, mesmo se já estava ativo, e não pede o código atual. Só chame quando o cliente realmente quer (re)configurar. Para desligar de propósito, use disable, que exige o código.

POST/api/v1/storefront/2fa/confirmCliente

Confirmar o código e ativar o 2FA

Corpo da requisição

codestringobrigatório
Código de 6 dígitos que o aplicativo mostra agora.
bash
curl -X POST "$BASE_URL/api/v1/storefront/2fa/confirm" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "123456"
}'
2002FA ativado
json
{
  "backup_codes": [
    "a1b2c3d4e5",
    "0f9e8d7c6b",
    "5a4b3c2d1e",
    "91827364aa",
    "bb11cc22dd",
    "ee33ff4455",
    "6677889900",
    "12ab34cd56",
    "78ef90ab12",
    "cd34ef5678"
  ]
}

Campos da resposta

backup_codesarray
10 códigos de uso único (hexadecimal). Aparecem só nesta resposta.
POST/api/v1/storefront/2fa/disableCliente

Desligar o 2FA

Corpo da requisição

codestringobrigatório
Código atual do aplicativo ou um código de recuperação ainda não usado.
bash
curl -X POST "$BASE_URL/api/v1/storefront/2fa/disable" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "123456"
}'
2002FA desligado
json
{
  "message": "2FA disabled"
}
GET/api/v1/storefront/2fa/statusCliente

Consultar se o 2FA está ativo

bash
curl "$BASE_URL/api/v1/storefront/2fa/status" \
  -H "Authorization: Bearer $TOKEN"
200Situação
json
{
  "enabled": true
}

Campos da resposta

enabledboolean
true quando o 2FA está confirmado e ativo.

Erros

StatusQuandoExemplo de corpo
400confirm sem setup prévio.{"error":"2FA setup not initiated"}
400Código errado em confirm ou disable.{"error":"invalid verification code"}
400disable com o 2FA desligado.{"error":"2FA is not enabled"}
401Sem token, ou token inválido.{"error":"missing authorization header"}
403Módulo de 2FA desligado na loja.{"error":"module_disabled","module":"two-factor-auth"}
403Administrador em impersonação.{"error":"impersonation_blocked","message":"Esta ação requer login direto do usuário."}
429Limite de requisições da família /storefront/.{"error":"rate limit exceeded","detail":"too many requests, please try again later"}

A mensagem de impersonation_blocked volta em português; ela é parte do contrato atual.

Cliente sem o aplicativo

Quem perdeu o celular entra com um código de recuperação no campo code do verify-2fa e, já logado, pode desligar o 2FA com outro código de recuperação e refazer o setup.

Veja também

  • Sessões do cliente
  • Autenticação
  • Tokens e escopos
Anterior
Sessão do cliente
Próxima
Sessões do cliente
Nesta página
  • Erros
  • Veja também