Login e segundo fator
Entra com e-mail, CPF ou CNPJ e senha, devolve o par de tokens e conclui o 2FA quando o usuário o ativou.
Use o login quando uma pessoa (ou um robô com conta de usuário) precisa de um token de acesso. A mesma rota atende administrador, seller (lojista) e cliente; o tipo do usuário fica no token. Se a conta tem verificação em duas etapas (2FA), o login não devolve o token ainda: devolve um temp_token, e você termina em verify-2fa.
Cada tentativa errada é registrada. Depois de várias senhas erradas para o mesmo identificador (10 por padrão, a loja pode mudar), a conta fica bloqueada por um período (1 minuto por padrão) e a API devolve 429 account_locked com o cabeçalho Retry-After. Bloqueios por política (conta pendente, desativada, e-mail não verificado) não contam como senha errada.
Entrar
/api/v1/auth/loginPúblicaEntrar com identificador e senha
Cabeçalhos
Content-Typestringobrigatórioapplication/json.X-Recaptcha-Tokenstring403 captcha_required.Corpo da requisição
identifierstringemail. Informe identifier ou email.emailstringidentifier em código novo.passwordstringobrigatórioaccept_pending_sessionbooleanpadrão: falsetrue, um cliente que aguarda aprovação da loja recebe uma sessão restrita (só rotas de onboarding) em vez de 403 account_pending_approval. Clientes antigos não precisam enviar.Exemplo de requisição
curl -X POST "$BASE_URL/api/v1/auth/login" \
-H "Content-Type: application/json" \
-d '{"identifier":"maria.souza@example.com","password":"MinhaSenha#2026"}'Resposta
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "4913f14458dfe5bb7497c7b2d4508d01671c8b41c422c8faf2eb5f6efd4e9f48",
"expires_at": "2026-10-11T21:06:19Z"
}{
"requires_2fa": true,
"temp_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Campos da resposta
access_tokenstringAuthorization: Bearer. Ausente quando requires_2fa é true.refresh_tokenstringexpires_atstringrequires_2fabooleantrue quando é preciso concluir o segundo fator.temp_tokenstringverify-2fa.requires_2fa_setupbooleanaccount_statusstringpending_approvalaccept_pending_session).Verificar o segundo fator
Quando o login devolve requires_2fa, peça ao usuário o código de 6 dígitos do aplicativo autenticador (ou um código de recuperação) e envie junto com o temp_token. Para ativar ou desativar o 2FA de uma conta, veja a seção de conta do administrador, do seller ou do cliente.
/api/v1/auth/verify-2faPúblicaConcluir o login com o código do segundo fator
Corpo da requisição
temp_tokenstringobrigatóriotemp_token devolvido pelo login. Vale 5 minutos.codestringobrigatóriocurl -X POST "$BASE_URL/api/v1/auth/verify-2fa" \
-H "Content-Type: application/json" \
-d '{"temp_token":"'"$TEMP_TOKEN"'","code":"123456"}'{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "7c1d0f5e2b9a4c6d8e3f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d",
"expires_at": "2026-10-11T21:08:02Z"
}Os campos são os mesmos do login.
Erros
| Status | Quando | Corpo |
|---|---|---|
| 400 | Corpo inválido; sem identifier/email; sem password | {"error":"password is required"} |
| 401 | Credenciais erradas | {"error":"invalid credentials"} |
| 403 | reCAPTCHA ausente ou reprovado | {"error":"captcha_required","detail":"reCAPTCHA token is required"} |
| 403 | Conta de administrador da plataforma tentando entrar numa loja | {"error":"wrong_panel","detail":"..."} |
| 403 | Seller sem loja vinculada | {"error":"vendor_no_store","message":"..."} |
| 403 | Candidatura de seller em análise | {"error":"vendor_pending_review","message":"..."} |
| 403 | Subconta suspensa pela empresa titular | {"error":"subaccount_suspended","message":"..."} |
| 403 | A loja exige e-mail verificado | {"error":"email_not_verified","message":"please verify your email address before logging in"} |
| 403 | Cliente aguardando aprovação da loja | {"error":"account_pending_approval","message":"..."} |
| 403 | Conta desativada | {"error":"account_disabled","message":"..."} |
| 409 | CPF, CNPJ ou telefone pertence a mais de uma conta | {"error":"multiple_accounts_cpf","message":"Multiple accounts are associated with this CPF. Please login with your email address instead."} (também multiple_accounts_cnpj, multiple_accounts_phone) |
| 429 | Conta bloqueada por senhas erradas | {"error":"account_locked","detail":"too many failed login attempts, please try again later"} com Retry-After |
| 429 | Mais de 5 logins por minuto do mesmo IP | {"error":"rate limit exceeded","detail":"too many requests, please try again later"} com Retry-After: 60 |
Para verify-2fa: 400 se faltar temp_token ou code (temp_token and code are required); 401 com invalid or expired verification token ou invalid verification code. Os textos de erro são em inglês; programe pelo código.