API atual/Referência completa/Conta do seller

Segundo fator (2FA)

Liga, confere e desliga o segundo fator de autenticação da própria conta do seller.

O segundo fator (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 permitem ao usuário do seller ligar, conferir e desligar o 2FA da própria conta. Não existe rota para mexer no 2FA de outra pessoa.

O fluxo para ligar tem duas etapas: setup gera um segredo e um QR code; o usuário cadastra o QR no aplicativo e envia o primeiro código em confirm. Só então o 2FA vale, e a partir do próximo login a plataforma pede o código (veja Autenticação).

GET/api/v1/vendor/2fa/statusSeller

Consultar o estado do 2FA

Diz se o 2FA está ligado na conta do token. Use para decidir entre mostrar "ativar" ou "desativar".

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/2fa/status" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Estado

json

{
  "enabled": false
}

Campos da resposta

enabledboolean

true quando o 2FA está ligado e confirmado.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
500	Falha ao ler o estado.	`{"error":"failed to get 2FA status","detail":"..."}`

POST/api/v1/vendor/2fa/setupSeller

Iniciar a ativação do 2FA

Gera um segredo novo para a conta e devolve o QR code. Não recebe corpo. O 2FA ainda não está ligado: falta confirm.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/2fa/setup" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Segredo gerado

json

{
  "secret": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP",
  "otpauth_url": "otpauth://totp/Venddor:maria@minhaloja.com.br?secret=JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP&issuer=Venddor",
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
}

Campos da resposta

secretstring

Segredo em base32, para digitar à mão no aplicativo. Trate como senha: não registre em log.

otpauth_urlstring

URI otpauth:// que os aplicativos entendem.

qr_codestring

Imagem PNG do QR code como data URI (data:image/png;base64,...), pronta para um <img src>.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	O módulo `two-factor-auth` está desligado.	`{"error":"module_disabled","module":"two-factor-auth"}`
403	Sessão de personificação.	`{"error":"impersonation_blocked","message":"Esta ação requer login direto do usuário."}`
500	Falha ao gerar ou gravar o segredo.	`{"error":"failed to setup 2FA","detail":"..."}`

POST/api/v1/vendor/2fa/confirmSeller

Confirmar e ligar o 2FA

Confere o código contra o segredo gerado em setup. Se estiver certo, liga o 2FA e devolve os códigos de recuperação.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Corpo da requisição

codestringobrigatório

Código de 6 dígitos mostrado agora pelo aplicativo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/2fa/confirm" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "123456"
}'

Resposta

2002FA ligado

json

{
  "backup_codes": [
    "3fa91c0d",
    "b27e45a1",
    "0c8d19ee",
    "5a6f7d32",
    "e91b04c8",
    "7d3a2f60",
    "a14c8e95",
    "62b0d7f3",
    "c9e5183a",
    "48f2a6b7"
  ]
}

Campos da resposta

backup_codesstring[]

Dez códigos de uso único, 8 caracteres hexadecimais cada. Aparecem só nesta resposta; guarde em lugar seguro. Cada um substitui o código do aplicativo uma vez.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	O módulo `two-factor-auth` está desligado.	`{"error":"module_disabled","module":"two-factor-auth"}`
403	Sessão de personificação.	`{"error":"impersonation_blocked","message":"Esta ação requer login direto do usuário."}`
400	`setup` não foi chamado antes.	`{"error":"2FA setup not initiated"}`
400	Código errado ou expirado.	`{"error":"invalid verification code"}`
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`

POST/api/v1/vendor/2fa/disableSeller

Desligar o 2FA

Desliga o 2FA da conta e apaga o segredo e os códigos de recuperação. Exige um código válido, para que um token roubado sozinho não consiga remover a proteção.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Corpo da requisição

codestringobrigatório

Código atual do aplicativo ou um dos códigos de recuperação.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/2fa/disable" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "123456"
}'

Resposta

2002FA desligado

json

{
  "message": "2FA disabled"
}

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	O módulo `two-factor-auth` está desligado.	`{"error":"module_disabled","module":"two-factor-auth"}`
403	Sessão de personificação.	`{"error":"impersonation_blocked","message":"Esta ação requer login direto do usuário."}`
400	O 2FA não está ligado.	`{"error":"2FA is not enabled"}`
400	Código errado.	`{"error":"invalid verification code"}`
403	Conta de dono da plataforma: o 2FA é obrigatório.	`{"error":"root_2fa_mandatory","detail":"root admin 2FA cannot be disabled"}`

Veja também

Segundo fator (2FA)

Liga, confere e desliga o segundo fator de autenticação da própria conta do seller.

GET/api/v1/vendor/2fa/statusSeller

Consultar o estado do 2FA

Diz se o 2FA está ligado na conta do token. Use para decidir entre mostrar "ativar" ou "desativar".

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/2fa/status" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Estado

json

{
  "enabled": false
}

Campos da resposta

enabledboolean

true quando o 2FA está ligado e confirmado.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
500	Falha ao ler o estado.	`{"error":"failed to get 2FA status","detail":"..."}`

POST/api/v1/vendor/2fa/setupSeller

Iniciar a ativação do 2FA

Gera um segredo novo para a conta e devolve o QR code. Não recebe corpo. O 2FA ainda não está ligado: falta confirm.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/2fa/setup" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Segredo gerado

json

{
  "secret": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP",
  "otpauth_url": "otpauth://totp/Venddor:maria@minhaloja.com.br?secret=JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP&issuer=Venddor",
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
}

Campos da resposta

secretstring

Segredo em base32, para digitar à mão no aplicativo. Trate como senha: não registre em log.

otpauth_urlstring

URI otpauth:// que os aplicativos entendem.

qr_codestring

Imagem PNG do QR code como data URI (data:image/png;base64,...), pronta para um <img src>.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	O módulo `two-factor-auth` está desligado.	`{"error":"module_disabled","module":"two-factor-auth"}`
403	Sessão de personificação.	`{"error":"impersonation_blocked","message":"Esta ação requer login direto do usuário."}`
500	Falha ao gerar ou gravar o segredo.	`{"error":"failed to setup 2FA","detail":"..."}`

POST/api/v1/vendor/2fa/confirmSeller

Confirmar e ligar o 2FA

Confere o código contra o segredo gerado em setup. Se estiver certo, liga o 2FA e devolve os códigos de recuperação.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Corpo da requisição

codestringobrigatório

Código de 6 dígitos mostrado agora pelo aplicativo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/2fa/confirm" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "123456"
}'

Resposta

2002FA ligado

json

{
  "backup_codes": [
    "3fa91c0d",
    "b27e45a1",
    "0c8d19ee",
    "5a6f7d32",
    "e91b04c8",
    "7d3a2f60",
    "a14c8e95",
    "62b0d7f3",
    "c9e5183a",
    "48f2a6b7"
  ]
}

Campos da resposta

backup_codesstring[]

Dez códigos de uso único, 8 caracteres hexadecimais cada. Aparecem só nesta resposta; guarde em lugar seguro. Cada um substitui o código do aplicativo uma vez.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	O módulo `two-factor-auth` está desligado.	`{"error":"module_disabled","module":"two-factor-auth"}`
403	Sessão de personificação.	`{"error":"impersonation_blocked","message":"Esta ação requer login direto do usuário."}`
400	`setup` não foi chamado antes.	`{"error":"2FA setup not initiated"}`
400	Código errado ou expirado.	`{"error":"invalid verification code"}`
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`

POST/api/v1/vendor/2fa/disableSeller

Desligar o 2FA

Desliga o 2FA da conta e apaga o segredo e os códigos de recuperação. Exige um código válido, para que um token roubado sozinho não consiga remover a proteção.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Corpo da requisição

codestringobrigatório

Código atual do aplicativo ou um dos códigos de recuperação.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/2fa/disable" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "123456"
}'

Resposta

2002FA desligado

json

{
  "message": "2FA disabled"
}

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	O módulo `two-factor-auth` está desligado.	`{"error":"module_disabled","module":"two-factor-auth"}`
403	Sessão de personificação.	`{"error":"impersonation_blocked","message":"Esta ação requer login direto do usuário."}`
400	O 2FA não está ligado.	`{"error":"2FA is not enabled"}`
400	Código errado.	`{"error":"invalid verification code"}`
403	Conta de dono da plataforma: o 2FA é obrigatório.	`{"error":"root_2fa_mandatory","detail":"root admin 2FA cannot be disabled"}`