API atual/Referência completa/Sessão do cliente

Verificação por código

Confirma que o visitante controla um e-mail ou telefone antes do checkout, do cadastro ou do login.

A verificação por código é o mecanismo genérico da loja para provar posse de um e-mail ou telefone, sem criar conta. O fluxo mais comum é no checkout do visitante: a loja exige que o e-mail tenha sido confirmado antes de aceitar o pedido de visitante. Você envia o código, o cliente o digita, você confere, e a plataforma passa a lembrar que aquele identificador está verificado.

O recurso depende do módulo otp-verification da loja. Com o módulo desligado, as três rotas respondem 403 module_disabled. Para entrar na conta com código, use o Login por código, que é outro fluxo.

POST/api/v1/storefront/otp/sendPública

Enviar o código

Corpo da requisição

identifierstringobrigatório

E-mail ou telefone. É convertido para minúsculas e e-mails são validados.

identifier_typestringobrigatório

emailphone

Tipo do identificador. Define o canal: e-mail ou SMS.

purposestringpadrão: checkout

checkoutregistrationlogin

Para que o código será usado. A verificação só vale para a mesma finalidade.

bash

curl -X POST "$BASE_URL/api/v1/storefront/otp/send" \
  -H "Content-Type: application/json" \
  -d '{
  "identifier": "maria.souza@example.com",
  "identifier_type": "email",
  "purpose": "checkout"
}'

200Código enviado

json

{
  "message": "verification code sent",
  "expires_at": "2026-10-11T20:51:07Z"
}

Campos da resposta

messagestring

Texto fixo em inglês.

expires_atstring

Quando o código expira (RFC 3339, UTC).

POST/api/v1/storefront/otp/verifyPública

Conferir o código

Corpo da requisição

identifierstringobrigatório

O mesmo identificador do envio.

codestringobrigatório

Código digitado pelo cliente.

purposestringpadrão: checkout

A mesma finalidade do envio.

bash

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

200Código correto

json

{
  "verified": true,
  "message": "verification successful"
}

200Código incorreto, expirado ou tentativas esgotadas

json

{
  "verified": false,
  "message": "verification code has expired"
}

Campos da resposta

verifiedboolean

true se o código confere.

messagestring

Motivo, em inglês: verification successful, incorrect verification code, verification code has expired, maximum verification attempts exceeded ou no pending verification found. Use para depurar; mostre ao cliente uma mensagem sua.

GET/api/v1/storefront/otp/statusPública

Consultar se o identificador está verificado

Parâmetros de consulta

identifierstringobrigatório

E-mail ou telefone.

purposestringpadrão: checkout

Finalidade a consultar.

bash

curl "$BASE_URL/api/v1/storefront/otp/status?identifier=maria.souza@example.com&purpose=checkout"

200Situação

json

{
  "verified": false,
  "identifier": "maria.souza@example.com",
  "purpose": "checkout"
}

Campos da resposta

verifiedboolean

true se houve verificação bem-sucedida recente (30 minutos) para o identificador e a finalidade.

identifierstring

O identificador, em minúsculas.

purposestring

A finalidade consultada.

Erros

Status	Quando	Exemplo de corpo
400	Falta `identifier`, `identifier_type` inválido, e-mail mal formado ou `purpose` fora da lista.	`{"detail":"must be checkout, registration, or login","error":"invalid purpose"}`
400	`verify` sem `code`.	`{"error":"code is required"}`
403	Módulo de OTP desligado.	`{"error":"module_disabled","module":"otp-verification"}`
429	Mais de 3 envios em 10 minutos.	`{"error":"too many verification requests","detail":"please wait before requesting another code"}`
500	Falha ao entregar o e-mail ou SMS.	`{"error":"failed to send verification email","detail":"the mail service is temporarily unavailable, please try again shortly"}`

Veja também

Verificação por código

Confirma que o visitante controla um e-mail ou telefone antes do checkout, do cadastro ou do login.

POST/api/v1/storefront/otp/sendPública

Enviar o código

Corpo da requisição

identifierstringobrigatório

E-mail ou telefone. É convertido para minúsculas e e-mails são validados.

identifier_typestringobrigatório

emailphone

Tipo do identificador. Define o canal: e-mail ou SMS.

purposestringpadrão: checkout

checkoutregistrationlogin

Para que o código será usado. A verificação só vale para a mesma finalidade.

bash

curl -X POST "$BASE_URL/api/v1/storefront/otp/send" \
  -H "Content-Type: application/json" \
  -d '{
  "identifier": "maria.souza@example.com",
  "identifier_type": "email",
  "purpose": "checkout"
}'

200Código enviado

json

{
  "message": "verification code sent",
  "expires_at": "2026-10-11T20:51:07Z"
}

Campos da resposta

messagestring

Texto fixo em inglês.

expires_atstring

Quando o código expira (RFC 3339, UTC).

POST/api/v1/storefront/otp/verifyPública

Conferir o código

Corpo da requisição

identifierstringobrigatório

O mesmo identificador do envio.

codestringobrigatório

Código digitado pelo cliente.

purposestringpadrão: checkout

A mesma finalidade do envio.

bash

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

200Código correto

json

{
  "verified": true,
  "message": "verification successful"
}

200Código incorreto, expirado ou tentativas esgotadas

json

{
  "verified": false,
  "message": "verification code has expired"
}

Campos da resposta

verifiedboolean

true se o código confere.

messagestring

GET/api/v1/storefront/otp/statusPública

Consultar se o identificador está verificado

Parâmetros de consulta

identifierstringobrigatório

E-mail ou telefone.

purposestringpadrão: checkout

Finalidade a consultar.

bash

curl "$BASE_URL/api/v1/storefront/otp/status?identifier=maria.souza@example.com&purpose=checkout"

200Situação

json

{
  "verified": false,
  "identifier": "maria.souza@example.com",
  "purpose": "checkout"
}

Campos da resposta

verifiedboolean

true se houve verificação bem-sucedida recente (30 minutos) para o identificador e a finalidade.

identifierstring

O identificador, em minúsculas.

purposestring

A finalidade consultada.

Erros

Status	Quando	Exemplo de corpo
400	Falta `identifier`, `identifier_type` inválido, e-mail mal formado ou `purpose` fora da lista.	`{"detail":"must be checkout, registration, or login","error":"invalid purpose"}`
400	`verify` sem `code`.	`{"error":"code is required"}`
403	Módulo de OTP desligado.	`{"error":"module_disabled","module":"otp-verification"}`
429	Mais de 3 envios em 10 minutos.	`{"error":"too many verification requests","detail":"please wait before requesting another code"}`
500	Falha ao entregar o e-mail ou SMS.	`{"error":"failed to send verification email","detail":"the mail service is temporarily unavailable, please try again shortly"}`