Nominais

Uma nominal é o trilho de liquidação sob o qual a sua conta opera — a "instituição" por trás das suas cobranças e saques. Sua conta pode ter mais de uma nominal disponível (ex.: "Padrão" e "Hub") e alternar entre elas conforme as taxas e a disponibilidade. Cada nominal carrega a sua própria taxa de entrada (PIX recebido) e taxa de saque, já resolvidas para a sua conta no catálogo (GET /api/nominais).

Quem usa o quê

Usuário (sessão do painel ou API key): lista (GET /api/nominais), troca (POST /api/nominais/select), define fallback (PATCH /api/nominais/fallback) e acompanha a troca (GET /api/nominais/switch).

Admin (papel ADMIN): mantém o catálogo (/api/admin/nominais) e libera/bloqueia nominais + define taxas especiais por usuário (PATCH /api/admin/nominais/access).

Subconta white-label (API key do master): o master consulta e troca a nominal da subconta via /api/subaccounts/{id}/nominal.

Troca com dreno (`PENDING_DRAIN`)

Quando a troca cruza de uma instituição para outra e há saldo disponível, o sistema dispara automaticamente um saque do saldo disponível para a sua chave PIX aprovada antes de concluir a troca (não há cobrança de 2FA, pois o destino é a sua própria chave). Enquanto o dreno está em voo (202 PENDING_DRAIN), a conta fica travada para novos saques/cobranças. A troca conclui sozinha quando o saque liquida — acompanhe por GET /api/nominais/switch. Trocas dentro da mesma instituição (ou com saldo zero) são imediatas (200).

Convenções

Taxas vêm já resolvidas para a sua conta (catálogo + condições especiais). Não calcule taxa a partir do catálogo bruto.

slug é o identificador estável da nominal (ex.: hub, padrao); use-o no select/fallback. displayName é só para exibição.

O trilho/adquirente de lastro de cada nominal é interno e nunca é exposto nas respostas voltadas ao cliente.

Códigos de erro (`code`)

`code`	HTTP	Significado
`SWITCH_IN_PROGRESS`	409	Já há uma troca em andamento (corpo traz `switchId`). Aguarde concluir.
`NOMINAL_NOT_USABLE`	422	A nominal escolhida não está disponível para a sua conta.
`BALANCE_RESERVED`	409	Há saldo reservado (disputa/MED aberta). Resolva antes de trocar.
`WITHDRAWAL_IN_FLIGHT`	409	Há um saque em andamento. Aguarde a liquidação.
`CHARGE_PENDING`	409	Há cobrança pendente de liquidação. Aguarde.
`BALANCE_BELOW_MIN_DRAIN`	422	Saldo abaixo do mínimo para o saque de dreno da troca. Acumule mais antes de trocar.
`PIX_KEY_REQUIRED`	422	É preciso uma chave PIX cadastrada e aprovada (destino do dreno).
`FALLBACK_INVALID`	422	O `fallbackSlug` informado não corresponde a uma nominal válida.
`SLUG_TAKEN`	409	(Admin) Já existe nominal com o `slug` informado.
`NOMINAL_IS_DEFAULT`	422	(Admin) A nominal é a padrão; defina outra como padrão antes de desabilitar.
`AMOUNT_LIMIT`	422	Valor da cobrança acima do teto permitido para a nominal atual. Reduza o valor ou troque de nominal.

Nominais

Nominais#

Quem usa o quê#

Troca com dreno (PENDING_DRAIN)#

Convenções#

Códigos de erro (code)#

Nominais

Quem usa o quê

Troca com dreno (`PENDING_DRAIN`)

Convenções

Códigos de erro (`code`)