Skip to content

Configuração de Opções de MFA de Customer

Visão Geral

Este módulo reúne os endpoints administrativos para criar, listar, detalhar, atualizar e remover opções MFA usadas no login de clientes.

Entidades Envolvidas

  • Opção MFA de customer
  • Canal de venda
  • Layout de notificação

    • Regras Importantes

  • Tipos aceitos: email, sms, whatsapp, app, external.
  • name representa o nome interno da opção no painel administrativo.
  • label representa o nome de exibição utilizado no fluxo de autenticação do cliente.
  • notificationLayoutId é obrigatório para email, sms e whatsapp.
  • externalUrl é obrigatória para external.
  • A opção padrão de app não pode ser removida.

    • Endpoints Relacionados

  • GET /api/v3/customers/mfa/options
  • GET /api/v3/customers/mfa/options/{optionId}
  • POST /api/v3/customers/mfa/options
  • PUT /api/v3/customers/mfa/options/{optionId}
  • DELETE /api/v3/customers/mfa/options/{optionId}

Listagem de Opções de MFA

GET /customers/mfa/options

Lista opções administrativas de MFA de customer

Descrição

Retorna a lista paginada de opções MFA cadastradas para o contexto administrativo.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação de usuário da API privada

Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/customers/mfa/options' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 1,
7        "salesChannelId": null,
8        "notificationLayoutId": null,
9        "type": "app",
10        "externalUrl": null,
11        "name": "app-autenticador",
12        "label": "Aplicativo autenticador",
13        "active": true
14      }
15    ],
16    "pagination": {
17      "limit": 10,
18      "offset": 0,
19      "pages": 1,
20      "registers": 1
21    }
22  }
23}

⚠️ Possíveis erros:

Código InternoCódigo HTTPDescrição
UAPPI_AUTH_INVALID401Token de autenticação inválido ou ausente.
UAPPI_AUTH_FORBIDDEN_SCOPE403Usuário sem escopo CUSTOMER_MFA_READ.

Detalhe de Opção de MFA

GET /customers/mfa/options/{optionId}

Retorna detalhe de uma opção administrativa de MFA de customer

Descrição

Retorna os dados de uma opção MFA específica a partir do optionId.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação de usuário da API privada

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
optionIdintegerSimID da opção MFA

Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/customers/mfa/options/2' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "id": 2,
5    "salesChannelId": 1,
6    "notificationLayoutId": 45,
7    "type": "email",
8    "externalUrl": null,
9    "name": "email-principal",
10    "label": "Código por e-mail",
11    "active": true
12  }
13}

⚠️ Possíveis erros:

Código InternoCódigo HTTPDescrição
UAPPI_AUTH_INVALID401Token de autenticação inválido ou ausente.
UAPPI_AUTH_FORBIDDEN_SCOPE403Usuário sem escopo CUSTOMER_MFA_READ.
UAPPI_STORE_CUSTOMER_MFA_OPTION_NOT_FOUND404Opção MFA não encontrada.

Criação de Opção de MFA

POST /customers/mfa/options

Cria opção administrativa de MFA de customer

Descrição

Cria uma nova opção MFA para o catálogo administrativo de customer.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação de usuário da API privada
Content-Typeapplication/jsonTipo de conteúdo

Parâmetros do Corpo

CampoTipoObrigatórioDescrição
salesChannelIdintegerSimID do canal usado para validação de contexto da operação
typestringSimTipo de MFA: email, sms, whatsapp, app, external
namestringSimNome interno da opção no painel (até 100 caracteres)
labelstringSimNome de exibição da opção (até 100 caracteres)
activebooleanSimStatus da opção
notificationLayoutIdintegerCondicionalObrigatório para email, sms e whatsapp
externalUrlstringCondicionalObrigatório para external

Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/customers/mfa/options' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "salesChannelId": 1,
7    "type": "sms",
8    "name": "sms-principal",
9    "label": "Código por SMS",
10    "notificationLayoutId": 32,
11    "active": true
12  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "status": true,
3  "data": {
4    "id": 5,
5    "salesChannelId": 1,
6    "notificationLayoutId": 32,
7    "type": "sms",
8    "externalUrl": null,
9    "name": "sms-principal",
10    "label": "Código por SMS",
11    "active": true
12  }
13}

⚠️ Possíveis erros:

Código InternoCódigo HTTPDescrição
INVALID_REQUEST_PAYLOAD400Dados da requisição inválidos.
UAPPI_STORE_CUSTOMER_MFA_OPTION_INVALID_NOTIFICATION_LAYOUT_TYPE400Layout de notificação incompatível com o tipo da opção.
UAPPI_AUTH_INVALID401Token de autenticação inválido ou ausente.
UAPPI_AUTH_FORBIDDEN_SCOPE403Usuário sem escopo CUSTOMER_MFA_WRITE.

Atualização de Opção de MFA

PUT /customers/mfa/options/{optionId}

Atualiza opção administrativa de MFA de customer

Descrição

Atualiza os dados de uma opção MFA existente.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação de usuário da API privada
Content-Typeapplication/jsonTipo de conteúdo

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
optionIdintegerSimID da opção MFA

Parâmetros do Corpo

CampoTipoObrigatórioDescrição
salesChannelIdintegerSimID do canal usado para validação de contexto da operação
typestringSimTipo de MFA: email, sms, whatsapp, app, external
namestringSimNome interno da opção no painel (até 100 caracteres)
labelstringSimNome de exibição da opção (até 100 caracteres)
activebooleanSimStatus da opção
notificationLayoutIdintegerCondicionalObrigatório para email, sms e whatsapp
externalUrlstringCondicionalObrigatório para external

Exemplo de Requisição

1curl --request PUT \
2  --url '{{MAIN_URL}}/customers/mfa/options/5' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "salesChannelId": 1,
7    "type": "sms",
8    "name": "sms-principal",
9    "label": "Código por SMS (Atualizado)",
10    "notificationLayoutId": 32,
11    "active": true
12  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "id": 5,
5    "salesChannelId": 1,
6    "notificationLayoutId": 32,
7    "type": "sms",
8    "externalUrl": null,
9    "name": "sms-principal",
10    "label": "Código por SMS (Atualizado)",
11    "active": true
12  }
13}

⚠️ Possíveis erros:

Código InternoCódigo HTTPDescrição
INVALID_REQUEST_PAYLOAD400Dados da requisição inválidos.
UAPPI_STORE_CUSTOMER_MFA_OPTION_INVALID_NOTIFICATION_LAYOUT_TYPE400Layout de notificação incompatível com o tipo da opção.
UAPPI_AUTH_INVALID401Token de autenticação inválido ou ausente.
UAPPI_AUTH_FORBIDDEN_SCOPE403Usuário sem escopo CUSTOMER_MFA_WRITE.
UAPPI_STORE_CUSTOMER_MFA_OPTION_NOT_FOUND404Opção MFA não encontrada.

Remoção de Opção de MFA

DELETE /customers/mfa/options/{optionId}

Remove opção administrativa de MFA de customer

Descrição

Remove uma opção MFA do catálogo administrativo.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação de usuário da API privada

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
optionIdintegerSimID da opção MFA

Exemplo de Requisição

1curl --request DELETE \
2  --url '{{MAIN_URL}}/customers/mfa/options/5' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": true
4}

⚠️ Possíveis erros:

Código InternoCódigo HTTPDescrição
UAPPI_AUTH_INVALID401Token de autenticação inválido ou ausente.
UAPPI_AUTH_FORBIDDEN_SCOPE403Usuário sem escopo CUSTOMER_MFA_WRITE.
UAPPI_STORE_CUSTOMER_MFA_DEFAULT_OPTION_DELETE400A opção padrão de MFA não pode ser removida.
UAPPI_STORE_CUSTOMER_MFA_OPTION_NOT_FOUND404Opção MFA não encontrada.

Validação do Código MFA do Cliente

POST /customers/{customerId}/mfa/validate

Valida o código MFA app (TOTP) configurado pelo customer

Descrição

Valida o código TOTP informado contra o MFA app já configurado pelo customer, retornando um booleano simples.

Esse endpoint permite que sistemas externos integrados utilizem o MFA app já configurado pelo customer na plataforma como fator adicional de autenticação em seus próprios fluxos, sem precisar implementar um setup de MFA próprio.

O código não é consumido nem invalidado após a verificação, e não há bloqueio por tentativas para essa rota.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação de usuário da API privada
Content-Typeapplication/jsonTipo de conteúdo

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
customerIdintegerSimID do customer

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
codestringSimCódigo TOTP de 6 dígitos gerado pelo app autenticador do customer

Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/customers/10/mfa/validate' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "code": "123456"
7  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": true
4}

O valor de data é true quando o código informado é válido para o MFA app configurado, e false quando o código é inválido.

⚠️ Possíveis erros:

Código InternoCódigo HTTPDescrição
UAPPI_AUTH_INVALID401Token de autenticação inválido ou ausente.
UAPPI_AUTH_FORBIDDEN_SCOPE403Usuário sem escopo CUSTOMER_MFA_READ.
UAPPI_STORE_CUSTOMER_NOT_FOUND404Customer não encontrado.
UAPPI_STORE_CUSTOMER_MFA_NOT_CONFIGURED400O customer não possui MFA app configurado.

Uappi é a melhor opção para o crescimento da sua loja!

Institucional

;