Trocar nominal da subconta (master)
PATCH
/api/subaccounts/{{subaccount_id}}/nominal
Autenticação
whiteLabelEnabled + escopo subaccounts:write). Sem a flag → 404.Trocar a nominal da subconta (caminho delegado)
POST /api/nominais/select: pode resultar em troca imediata (200) ou em dreno (202 PENDING_DRAIN) quando cruza instituições e há saldo. Como é caminho delegado, nenhum 2FA é coletado — o dreno vai obrigatoriamente para a chave PIX aprovada da pr ópria subconta.Path / Body
| Local | Campo | Tipo | Descrição |
|---|---|---|---|
| path | {{subaccount_id}} | string | Id da subconta. |
| body | slug | string (obrigatório) | slug da nominal de destino. |
| body | fallbackSlug | string | Opcional: define a nominal de fallback da subconta. |
Respostas de sucesso
| HTTP | code | Significado |
|---|---|---|
| 200 | APPLIED / APPLIED_NO_DRAIN | Troca imediata. |
| 202 | DRAINING | Dreno disparado (switchId no corpo). |
Erros (code)
POST /api/nominais/select (SWITCH_IN_PROGRESS, NOMINAL_NOT_USABLE, BALANCE_RESERVED, WITHDRAWAL_IN_FLIGHT, CHARGE_PENDING, BALANCE_BELOW_MIN_DRAIN, PIX_KEY_REQUIRED, FALLBACK_INVALID). Além disso:| HTTP | Quando |
|---|---|
| 400 | slug ausente. |
| 404 | Sem a flag, ou subconta inexistente/não pertencente ao master. |
Exemplo cURL
Requisição
Parâmetros Header
Parâmetros Bodyapplication/json
Respostas
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --globoff --request PATCH '/api/subaccounts/{{subaccount_id}}/nominal' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"slug": "hub"
}'Response Response Example
200 - Troca imediata (200)
{
"status": "COMPLETED",
"code": "APPLIED"
}Modificado em 2026-07-14 04:02:21