Noviuz DocsAPI Nexiuz
Obtenção e Gestão de Credenciais
Como emitir, rotacionar e proteger suas chaves de API pelo Portal do Cliente Noviuz.
Para integrar seu sistema à API da Conta Nexiuz, você precisa criar uma Aplicação no Portal do Cliente Noviuz. A aplicação vincula suas contas bancárias aos escopos de acesso e gera o par de credenciais criptográficas.
1. Onde Obter suas Chaves
- Acesse o Portal do Cliente Noviuz com seu login e senha.
- No menu lateral, acesse Desenvolvedores > Aplicações de API.
- Clique em Nova Aplicação.
- No autosserviço do Portal, você pode criar aplicações
TESTimediatamente. AplicaçõesLIVEsão provisionadas junto à equipe da Noviuz após a homologação das credenciais. - Escolha quais contas vinculadas essa aplicação poderá movimentar e marque os escopos necessários.
- Confirme com sua senha ou verificação em duas etapas (MFA).
2. As Chaves de Acesso da sua Aplicação
Ao concluir a criação, o Portal exibirá suas credenciais:
| Credencial | Finalidade | Onde é Usada |
|---|---|---|
client_id | Identificador público da sua aplicação. | Autenticação Basic para emissão de Access Token. |
client_secret | Chave secreta de autenticação. Exibida uma única vez. | Autenticação Basic para emissão de Access Token. |
signing_secret | Segredo para assinatura HMAC de requisições de escrita da API pública. | Assina com X-Signature, X-Timestamp e X-Nonce as operações POST, PATCH e DELETE que exigem HMAC, incluindo PIX, saques e administração de webhooks. |
Aviso de Segurança Crítico: O client_secret e o signing_secret são exibidos apenas uma vez no momento da criação. A Noviuz não armazena essas chaves em texto claro. Guarde-as imediatamente em um cofre de segredos ou variável de ambiente segura no seu servidor.
3. Ambientes: TEST vs LIVE
| Característica | Ambiente TEST (Sandbox) | Ambiente LIVE (Produção) |
|---|---|---|
| Prefixo dos Tokens | nxt_test_... | nxt_live_... |
| Dinheiro Real | Não (saldo fictício de teste) | Sim (liquidação bancária real) |
| Simulação de PIX | Endpoint de simulação disponível somente para aplicação TEST | Não disponível; em LIVE o recurso não é encontrado |
| Simulação de Saques | Endpoint de simulação de desfecho disponível somente para TEST | Não disponível; em LIVE o recurso não é encontrado |
4. Escopos de Permissão
Conceda apenas os escopos estritamente necessários para o seu caso de uso (princípio do menor privilégio):
accounts:read: Consulta contas e saldos das contas vinculadas.transactions:read: Consulta ao extrato e histórico de lançamentos.pix:read: Consulta ao status de cobranças PIX emitidas.pix:write: Emissão de cobranças e geração de QR Codes PIX.withdrawals:read: Consulta ao status de solicitações de saque.withdrawals:write: Solicitação de transferências e saques para contas externas.webhooks:read: Consulta aos endpoints e histórico de entregas de notificações.webhooks:write: Cadastro e configuração de URLs de webhook.
5. Rotação de Segredos e Revogação
- Rotação: emita uma nova credencial antes de revogar a antiga e atualize seu cofre de segredos. Tokens e credenciais são verificados a cada chamada; planeje a transição e valide-a no ambiente TEST.
- Suspensão Imediata (Kill Switch): Caso suspeite de vazamento de segredos, clique em Suspender no Portal. Todas as chamadas com tokens existentes serão imediatamente recusadas com HTTP
401. - Revogação Definitiva: Invalida permanentemente a aplicação e todas as credenciais associadas.