API atual/Referência completa/Autenticação avançada

Login por código (OTP)

Entra sem senha com um código de 6 dígitos enviado por e-mail, SMS ou WhatsApp.

O login por código serve para o cliente que não lembra a senha ou que prefere não ter uma. Você chama duas rotas em sequência: primeiro pede o código para um identificador (e-mail ou telefone), depois devolve o código que o cliente recebeu e recebe os tokens de sessão, exatamente como no login com senha.

O recurso depende do módulo otp-verification da loja. Com o módulo desligado, as duas rotas respondem 403 com module_disabled. Os canais (e-mail, SMS, WhatsApp) também são ligados loja a loja; peça ao administrador da loja para conferir.

POST/api/v1/auth/otp-login/requestPública

Pedir o código de login

Gera e envia o código. A plataforma não informa se o identificador existe: a resposta é 200 nos dois casos.

Corpo da requisição

identifierstringobrigatório

E-mail ou telefone do cliente. Espaços nas pontas são removidos.

channelstringpadrão: email

emailsmswhatsapp

Canal de entrega. Maiúsculas são aceitas. Vazio vale email.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/auth/otp-login/request" \
  -H "Content-Type: application/json" \
  -d '{
  "identifier": "maria.souza@example.com",
  "channel": "email"
}'

Resposta

200Código solicitado

json

{
  "success": true,
  "channel": "email"
}

Campos da resposta

successboolean

Sempre true quando a requisição foi aceita.

channelstring

Canal que a loja usa para esse tipo de envio. Vem da configuração da loja, não da conta do cliente, então não revela se a conta existe.

Erros

Status	Quando	Exemplo de corpo
400	Identificador vazio.	`{"error":"identifier is required","detail":"provide an email or phone"}`
400	Canal fora de email, sms e whatsapp.	`{"error":"invalid_channel","detail":"channel must be email, sms or whatsapp"}`
403	Módulo de OTP desligado na loja.	`{"error":"module_disabled","module":"otp-verification"}`
409	Canal WhatsApp com a janela de conversa fechada.	`{"error":"whatsapp_window_closed"}`
429	Muitos pedidos de código para o mesmo identificador, ou limite de requisições da API.	`{"error":"rate_limited","detail":"too many ..."}`

POST/api/v1/auth/otp-login/verifyPública

Trocar o código por tokens de sessão

Confere o código e, se estiver certo, abre a sessão. Use os mesmos tokens do login com senha.

Corpo da requisição

identifierstringobrigatório

O mesmo identificador usado no passo 1.

codestringobrigatório

Código de 6 dígitos recebido pelo cliente.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/auth/otp-login/verify" \
  -H "Content-Type: application/json" \
  -d '{
  "identifier": "maria.souza@example.com",
  "code": "482915"
}'

Resposta

200Sessão aberta

json

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "rt_9f2c1d7e4b...",
  "expires_at": "2026-10-11T21:30:00Z"
}

Campos da resposta

access_tokenstring

JWT de acesso, curto. Envie em Authorization: Bearer. Veja Tokens.

refresh_tokenstring

Token opaco para obter um novo par em POST /api/v1/auth/refresh.

expires_atstring

Quando o access_token expira (RFC 3339, UTC).

Erros

Status	Quando	Exemplo de corpo
400	Falta `identifier` ou `code`.	`{"error":"identifier and code are required"}`
401	Código errado, expirado, ou identificador sem conta. Os três casos têm a mesma resposta.	`{"error":"invalid_otp"}`
403	A conta pertence ao painel da plataforma, não à loja.	`{"error":"wrong_panel","detail":"this account belongs to the platform admin panel"}`
403	Subconta suspensa.	`{"error":"subaccount_suspended"}`
429	Tentativas erradas demais. O cabeçalho `Retry-After` traz os segundos de espera.	`{"error":"account_locked","detail":"too many failed login attempts, please try again later"}`

Veja também

Entra sem senha com um código de 6 dígitos enviado por e-mail, SMS ou WhatsApp.

POST/api/v1/auth/otp-login/requestPública

Pedir o código de login

Gera e envia o código. A plataforma não informa se o identificador existe: a resposta é 200 nos dois casos.

Corpo da requisição

identifierstringobrigatório

E-mail ou telefone do cliente. Espaços nas pontas são removidos.

channelstringpadrão: email

emailsmswhatsapp

Canal de entrega. Maiúsculas são aceitas. Vazio vale email.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/auth/otp-login/request" \
  -H "Content-Type: application/json" \
  -d '{
  "identifier": "maria.souza@example.com",
  "channel": "email"
}'

Resposta

200Código solicitado

json

{
  "success": true,
  "channel": "email"
}

Campos da resposta

successboolean

Sempre true quando a requisição foi aceita.

channelstring

Canal que a loja usa para esse tipo de envio. Vem da configuração da loja, não da conta do cliente, então não revela se a conta existe.

Erros

Status	Quando	Exemplo de corpo
400	Identificador vazio.	`{"error":"identifier is required","detail":"provide an email or phone"}`
400	Canal fora de email, sms e whatsapp.	`{"error":"invalid_channel","detail":"channel must be email, sms or whatsapp"}`
403	Módulo de OTP desligado na loja.	`{"error":"module_disabled","module":"otp-verification"}`
409	Canal WhatsApp com a janela de conversa fechada.	`{"error":"whatsapp_window_closed"}`
429	Muitos pedidos de código para o mesmo identificador, ou limite de requisições da API.	`{"error":"rate_limited","detail":"too many ..."}`

POST/api/v1/auth/otp-login/verifyPública

Trocar o código por tokens de sessão

Confere o código e, se estiver certo, abre a sessão. Use os mesmos tokens do login com senha.

Corpo da requisição

identifierstringobrigatório

O mesmo identificador usado no passo 1.

codestringobrigatório

Código de 6 dígitos recebido pelo cliente.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/auth/otp-login/verify" \
  -H "Content-Type: application/json" \
  -d '{
  "identifier": "maria.souza@example.com",
  "code": "482915"
}'

Resposta

200Sessão aberta

json

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "rt_9f2c1d7e4b...",
  "expires_at": "2026-10-11T21:30:00Z"
}

Campos da resposta

access_tokenstring

JWT de acesso, curto. Envie em Authorization: Bearer. Veja Tokens.

refresh_tokenstring

Token opaco para obter um novo par em POST /api/v1/auth/refresh.

expires_atstring

Quando o access_token expira (RFC 3339, UTC).

Erros

Status	Quando	Exemplo de corpo
400	Falta `identifier` ou `code`.	`{"error":"identifier and code are required"}`
401	Código errado, expirado, ou identificador sem conta. Os três casos têm a mesma resposta.	`{"error":"invalid_otp"}`
403	A conta pertence ao painel da plataforma, não à loja.	`{"error":"wrong_panel","detail":"this account belongs to the platform admin panel"}`
403	Subconta suspensa.	`{"error":"subaccount_suspended"}`
429	Tentativas erradas demais. O cabeçalho `Retry-After` traz os segundos de espera.	`{"error":"account_locked","detail":"too many failed login attempts, please try again later"}`