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

Recuperação de senha B2B

Recupera o acesso de uma conta empresarial por CNPJ, e-mail ou telefone, com código de 6 dígitos em vez de link.

Em lojas B2B, quem compra costuma ser um funcionário que só conhece o CNPJ da empresa. A recuperação B2B deixa o cliente se identificar por CNPJ, e-mail ou telefone e receber um código de 6 dígitos por e-mail ou SMS. Quando o código confere, a plataforma entrega um reset_token, que você troca pela nova senha em POST /api/v1/auth/reset-password (a mesma rota do "esqueci minha senha" comum, descrita em Autenticação).

As lojas escolhem se usam o fluxo: cada canal (e-mail, SMS) vem desligado de fábrica. Use GET /api/v1/auth/b2b-recovery/status para saber quais canais a loja ligou e só mostre o fluxo B2B quando algum estiver ligado; senão use o "esqueci minha senha" comum.

Descobrir os canais
Chame GET /auth/b2b-recovery/status.
Identificar
Chame lookup com o identificador. A resposta só informa quais canais estão disponíveis.
Enviar o código
Chame send com o identificador e o canal escolhido.
Validar
Chame validate com o código. Guarde o reset_token.
Definir a nova senha
Envie o reset_token e a nova senha para POST /api/v1/auth/reset-password.

GET/api/v1/auth/b2b-recovery/statusPública

Canais de recuperação habilitados

Sonda pública e somente leitura. Não exige reCAPTCHA.

bash

curl "$BASE_URL/api/v1/auth/b2b-recovery/status"

200Canais da loja

json

{
  "email": true,
  "sms": false
}

Campos da resposta

emailboolean

true se a loja envia o código por e-mail.

smsboolean

true se a loja envia o código por SMS.

POST/api/v1/auth/b2b-recovery/lookupPública

Identificar a conta e listar canais

Corpo da requisição

identifierstringobrigatório

CNPJ (com ou sem pontuação, válido), e-mail ou telefone com DDD.

Cabeçalhos

X-Recaptcha-Tokenstring

Token reCAPTCHA v3, obrigatório só se a loja configurou reCAPTCHA.

bash

curl -X POST "$BASE_URL/api/v1/auth/b2b-recovery/lookup" \
  -H "Content-Type: application/json" \
  -d '{
  "identifier": "12.345.678/0001-95"
}'

200Canais disponíveis

json

{
  "found": true,
  "email_enabled": true,
  "sms_enabled": false
}

Campos da resposta

foundboolean

Sempre true, para qualquer identificador (proteção contra enumeração de contas).

email_enabledboolean

A loja envia por e-mail.

sms_enabledboolean

A loja envia por SMS.

POST/api/v1/auth/b2b-recovery/sendPública

Enviar o código de recuperação

O código vai para o contato que já está no cadastro; você não informa o destino. Se o identificador não tem conta, a resposta é igual e nada é enviado.

Corpo da requisição

identifierstringobrigatório

O mesmo identificador do lookup.

channelstringobrigatório

emailsms

Canal de entrega.

bash

curl -X POST "$BASE_URL/api/v1/auth/b2b-recovery/send" \
  -H "Content-Type: application/json" \
  -d '{
  "identifier": "12.345.678/0001-95",
  "channel": "email"
}'

200Código enviado

json

{
  "sent": true
}

Campos da resposta

sentboolean

true quando o pedido foi aceito. O envio roda em segundo plano.

POST/api/v1/auth/b2b-recovery/validatePública

Validar o código e obter o reset_token

Corpo da requisição

identifierstringobrigatório

O mesmo identificador.

otpstringobrigatório

Código de 6 dígitos recebido.

bash

curl -X POST "$BASE_URL/api/v1/auth/b2b-recovery/validate" \
  -H "Content-Type: application/json" \
  -d '{
  "identifier": "12.345.678/0001-95",
  "otp": "482915"
}'

200Código correto

json

{
  "reset_token": "5b1f0c...e93a"
}

Campos da resposta

reset_tokenstring

Token de uso único para POST /api/v1/auth/reset-password. Trate como segredo e não registre em log.

Erros

As falhas deste fluxo trazem apenas o código em error.

Status	Quando	Exemplo de corpo
400	Corpo sem os campos obrigatórios.	`{"error":"identifier and channel are required"}`
403	A loja não ligou a recuperação B2B.	`{"error":"recovery_disabled"}`
403	O canal pedido está desligado.	`{"error":"channel_disabled"}`
403	reCAPTCHA exigido e ausente ou reprovado.	`{"error":"captcha_required"}`
422	Código errado ou expirado (`validate`).	`{"error":"invalid_otp"}`
429	Reenvio antes do fim da espera (`send`). `wait_minutes` diz quanto falta.	`{"error":"cooldown","wait_minutes":12}`
429	Tentativas de código esgotadas (`validate`).	`{"error":"too_many_attempts"}`
429	Limite de requisições da API (família `/auth/`).	`{"error":"rate limit exceeded","detail":"too many requests, please try again later"}`
500	Falha interna ao gerar ou conferir.	`{"error":"recovery_failed"}`

Veja também

Recuperação de senha B2B

Recupera o acesso de uma conta empresarial por CNPJ, e-mail ou telefone, com código de 6 dígitos em vez de link.

Descobrir os canais
Chame GET /auth/b2b-recovery/status.
Identificar
Chame lookup com o identificador. A resposta só informa quais canais estão disponíveis.
Enviar o código
Chame send com o identificador e o canal escolhido.
Validar
Chame validate com o código. Guarde o reset_token.
Definir a nova senha
Envie o reset_token e a nova senha para POST /api/v1/auth/reset-password.

GET/api/v1/auth/b2b-recovery/statusPública

Canais de recuperação habilitados

Sonda pública e somente leitura. Não exige reCAPTCHA.

bash

curl "$BASE_URL/api/v1/auth/b2b-recovery/status"

200Canais da loja

json

{
  "email": true,
  "sms": false
}

Campos da resposta

emailboolean

true se a loja envia o código por e-mail.

smsboolean

true se a loja envia o código por SMS.

POST/api/v1/auth/b2b-recovery/lookupPública

Identificar a conta e listar canais

Corpo da requisição

identifierstringobrigatório

CNPJ (com ou sem pontuação, válido), e-mail ou telefone com DDD.

Cabeçalhos

X-Recaptcha-Tokenstring

Token reCAPTCHA v3, obrigatório só se a loja configurou reCAPTCHA.

bash

curl -X POST "$BASE_URL/api/v1/auth/b2b-recovery/lookup" \
  -H "Content-Type: application/json" \
  -d '{
  "identifier": "12.345.678/0001-95"
}'

200Canais disponíveis

json

{
  "found": true,
  "email_enabled": true,
  "sms_enabled": false
}

Campos da resposta

foundboolean

Sempre true, para qualquer identificador (proteção contra enumeração de contas).

email_enabledboolean

A loja envia por e-mail.

sms_enabledboolean

A loja envia por SMS.

POST/api/v1/auth/b2b-recovery/sendPública

Enviar o código de recuperação

O código vai para o contato que já está no cadastro; você não informa o destino. Se o identificador não tem conta, a resposta é igual e nada é enviado.

Corpo da requisição

identifierstringobrigatório

O mesmo identificador do lookup.

channelstringobrigatório

emailsms

Canal de entrega.

bash

curl -X POST "$BASE_URL/api/v1/auth/b2b-recovery/send" \
  -H "Content-Type: application/json" \
  -d '{
  "identifier": "12.345.678/0001-95",
  "channel": "email"
}'

200Código enviado

json

{
  "sent": true
}

Campos da resposta

sentboolean

true quando o pedido foi aceito. O envio roda em segundo plano.

POST/api/v1/auth/b2b-recovery/validatePública

Validar o código e obter o reset_token

Corpo da requisição

identifierstringobrigatório

O mesmo identificador.

otpstringobrigatório

Código de 6 dígitos recebido.

bash

curl -X POST "$BASE_URL/api/v1/auth/b2b-recovery/validate" \
  -H "Content-Type: application/json" \
  -d '{
  "identifier": "12.345.678/0001-95",
  "otp": "482915"
}'

200Código correto

json

{
  "reset_token": "5b1f0c...e93a"
}

Campos da resposta

reset_tokenstring

Token de uso único para POST /api/v1/auth/reset-password. Trate como segredo e não registre em log.

Erros

As falhas deste fluxo trazem apenas o código em error.

Status	Quando	Exemplo de corpo
400	Corpo sem os campos obrigatórios.	`{"error":"identifier and channel are required"}`
403	A loja não ligou a recuperação B2B.	`{"error":"recovery_disabled"}`
403	O canal pedido está desligado.	`{"error":"channel_disabled"}`
403	reCAPTCHA exigido e ausente ou reprovado.	`{"error":"captcha_required"}`
422	Código errado ou expirado (`validate`).	`{"error":"invalid_otp"}`
429	Reenvio antes do fim da espera (`send`). `wait_minutes` diz quanto falta.	`{"error":"cooldown","wait_minutes":12}`
429	Tentativas de código esgotadas (`validate`).	`{"error":"too_many_attempts"}`
429	Limite de requisições da API (família `/auth/`).	`{"error":"rate limit exceeded","detail":"too many requests, please try again later"}`
500	Falha interna ao gerar ou conferir.	`{"error":"recovery_failed"}`