Trocar de nominal
POST
/api/nominais/select
Autenticação
Authorization: Bearer {{api_key}}.Trocar de nominal
Body
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
slug | string | sim | slug da nominal de destino (veja GET /api/nominais). |
fallbackSlug | string | null | não | Define (ou limpa, com null) a nominal de fallback na mesma chamada. Atalho para PATCH /fallback. |
Dois caminhos de troca
200) — quando origem e destino estão na mesma instituição (ou seu saldo disponível é zero). A nominal já fica ativa na resposta.202 PENDING_DRAIN) — quando a troca cruza para outra instituição e há saldo disponível. O sistema dispara automaticamente um saque do seu saldo disponível para a sua chave PIX aprovada antes de concluir. Não é necessário código 2FA: o destino é obrigatoriamente a sua própria chave aprovada. Acompanhe pelo GET /api/nominais/switch. A troca conclui sozinha quando o saque liquida.PENDING_DRAIN a conta fica travada para novos saques/cobranças até a liquidação do dreno (garante que o único saque em voo é o próprio dreno).Respostas de sucesso
| HTTP | code | Significado |
|---|---|---|
| 200 | APPLIED | Troca imediata aplicada (mesma instituição). |
| 200 | APPLIED_NO_DRAIN | Troca aplicada sem dreno (saldo disponível era zero). |
| 202 | DRAINING | Dreno disparado; corpo traz switchId e status: PENDING_DRAIN. |
Erros (code)
| HTTP | code | Quando |
|---|---|---|
| 400 | — | slug ausente. |
| 409 | SWITCH_IN_PROGRESS | Já existe uma troca em andamento (corpo traz switchId). |
| 409 | BALANCE_RESERVED | Há saldo reservado (disputa/MED aberta). Resolva antes. |
| 409 | WITHDRAWAL_IN_FLIGHT | Há um saque em andamento. Aguarde a liquidação. |
| 409 | CHARGE_PENDING | Há cobrança pendente de liquidação. Aguarde. |
| 422 | NOMINAL_NOT_USABLE | A nominal de destino não está disponível para a sua conta. |
| 422 | BALANCE_BELOW_MIN_DRAIN | Saldo abaixo do mínimo para o saque de dreno. Acumule mais antes de trocar. |
| 422 | PIX_KEY_REQUIRED | Cadastre e aprove uma chave PIX antes de trocar (destino do dreno). |
| 422 | FALLBACK_INVALID | fallbackSlug informado não corresponde a uma nominal válida. |
Exemplo cURL
429 ao exceder).Requisição
Parâmetros Header
Parâmetros Bodyapplication/json
Respostas
Request Request Example
Shell
JavaScript
Java
Swift
curl --location '/api/nominais/select' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"slug": "hub",
"fallbackSlug": "padrao"
}'Response Response Example
200 - Troca imediata (200)
{
"status": "COMPLETED",
"code": "APPLIED"
}Modificado em 2026-07-14 04:02:21