🔒 Sub Usuário (Envio Restrito a uma Chave Fixa)

Esta página mostra como restringir um usuário da sua conta a enviar valor apenas para uma chave DEX fixa — normalmente a conta do titular do negócio — mantendo os recebimentos liberados.

O caso típico: uma loja com funcionários. Cada colaborador movimenta valores pelo DEX, mas tudo que ele envia vai obrigatoriamente para a conta central.

1. O Que Muda para o Usuário Restrito

2. Credencial Necessária

A configuração exige a credencial pessoal de um usuário que administra sua conta de participante — gerada em Integrações → API, como qualquer credencial de usuário (veja Autenticação).

curl -X POST https://api.dexkey.finance/v1/auth/api-key \
  -H "Content-Type: application/json" \
  -d '{ "clientId": "...", "clientSecret": "..." }'

Use o accessToken retornado nas chamadas abaixo.

3. Ativar a Restrição

curl -X PATCH https://api.dexkey.finance/v1/admin/users/{userId}/sub-user \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fixedDestinationKey": "+595981234567",
    "reason": "Funcionario da loja — centralizar movimentacao na conta do titular"
  }'

Corpo enviado

Resposta

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "subUserEnabled": true,
  "fixedDestinationKey": "*********4567",
  "fixedDestinationName": "Comercial Guarani LTDA",
  "subUserEnabledAt": "2026-09-01T14:32:00.000Z"
}

Números fora do Brasil

Chave estrangeira precisa do código do país. 981234567 não resolve; para um celular paraguaio use +595981234567.

É o erro mais comum na integração — se você aceita entrada de operador, valide o prefixo antes de enviar.

4. Trocar a Chave Fixa

O mesmo endpoint, com a chave nova.

O comportamento é idempotente: repetir com a mesma chave devolve 200 sem alterar nada nem gerar novo registro. Chave diferente é tratada como troca.

5. Remover a Restrição

curl -X DELETE https://api.dexkey.finance/v1/admin/users/{userId}/sub-user \
  -H "Authorization: Bearer $TOKEN"

Devolve 200 com o mesmo formato da ativação, agora com subUserEnabled: false. O usuário volta a ter acesso total.

Também é idempotente — chamar sobre quem não está restrito devolve o estado atual, sem efeito.

6. Consultar Quem Está Restrito

GET /v1/admin/users e GET /v1/admin/users/{userId} trazem:

7. O Que o App do Usuário Enxerga

GET /v1/profile/restrictions, com o token do próprio usuário, devolve tudo que restringe a conta dele:

{
  "accountBlocked": false,
  "operations": [
    { "operation": "SEND_INTERNAL", "allowed": true, "reason": "SUB_USER_FIXED_DESTINATION_ONLY" },
    { "operation": "SEND_PIX", "allowed": false, "reason": "SUB_USER_BLOCKED" },
    { "operation": "SEND_CRYPTO", "allowed": false, "reason": "SUB_USER_BLOCKED" },
    { "operation": "SEND_PENDING_TRANSFER", "allowed": false, "reason": "SUB_USER_BLOCKED" },
    { "operation": "CARD_LOAD", "allowed": false, "reason": "SUB_USER_BLOCKED" },
    { "operation": "RECEIVE_PIX", "allowed": true, "reason": null }
  ],
  "subUser": {
    "enabled": true,
    "fixedDestinationKey": "*********4567",
    "fixedDestinationName": "Comercial Guarani LTDA",
    "fixedDestinationIdentifier": "USER_550e8400-e29b-41d4-a716-446655440000"
  }
}

Use operations[] para montar menu e telas sem esperar o erro no meio do fluxo.

SEND_INTERNAL vem com allowed: true e um reason. Não é contradição: o envio está liberado, com a ressalva de que só vai para a chave fixa. Trate reason presente com allowed: true como "liberado com restrição".

Motivos possíveis

8. Restrição e Verificação de Conta se Somam

São dimensões independentes. Uma conta sem verificação completa não recebe nem envia por Pix, mesmo sem restrição:

Ou seja: promover a conta a verificação completa libera o recebimento Pix de um Sub Usuário, e nunca o envio.

9. Erros da Configuração

10. Erros que o Usuário Restrito Recebe

Nas operações de envio, com o token do próprio usuário:

Trate os dois como caminho de erro previsto, não como falha inesperada — mesmo que sua interface já esconda a operação.

11. Detalhes de Contrato que Importam na Integração

A chave é resolvida, não armazenada como texto. A configuração grava a conta que a chave aponta. Se o titular do destino trocar de telefone depois, os envios continuam chegando na mesma conta, e a consulta passa a exibir o número novo.

Nenhum campo é removido de respostas existentes. Os campos de Sub Usuário são adicionais em GET /admin/users e GET /admin/users/{userId}.

Dois valores novos podem aparecer em respostas de cartão, se você consome esses endpoints:

• CardEligibilityBlocker pode vir SUB_USER_RESTRICTED — em GET /cards/eligibility
• CardFreezeOrigin pode vir SUB_USER_RESTRICTION — no detalhe e no resumo do cartão

Ambas as respostas já trazem o texto pronto para exibição. Se você mantém tabela própria de tradução por código, acrescente os dois.

O cartão acompanha a restrição. Ao restringir um usuário que já tem cartão ativo, ele é congelado; ao remover a restrição, volta ao ar. O titular não descongela pela tela enquanto a restrição existir.

12. Limites do Recurso

Uma chave fixa por usuário — não há múltiplos destinos.

A configuração é individual, um usuário por vez. Não há operação em lote.

Não é um sistema de permissões: é ligado ou desligado, sem granularidade por funcionalidade.

Um usuário só passa a ser Sub Usuário quando alguém o marca explicitamente. Contas existentes não são afetadas.