Noviuz DocsQuickstart da API pública Nexiuz
Do zero ao primeiro PIX em 5 minutos: autenticação, consulta de saldo, criação de cobrança assinada com HMAC e simulação em sandbox.
Este guia conduz você pelo primeiro fluxo completo de ponta a ponta na API pública da Conta Nexiuz em ambiente de testes (TEST).
Integração REST direta: A API pública da Conta Nexiuz é um serviço HTTP REST servidor a servidor padronizado. Ela não requer um SDK proprietário — você integra utilizando os clientes HTTP e módulos criptográficos nativos da sua linguagem de preferência (Node.js/TypeScript, Python, Go, etc.).
1. Obtenha credenciais de sandbox no Portal
Acesse o Portal do Cliente Noviuz, navegue até Desenvolvedores e crie uma nova aplicação no ambiente TEST:
client_id: Identificador público da aplicação (ex:app_test_...).client_secret: Chave de autenticação confidencial para emissão do token (exibida apenas uma vez).signing_secret: Chave secreta compartilhada para cálculo da assinatura criptográfica HMAC-SHA256 das escritas.
Segurança em primeiro lugar: Armazene client_secret e signing_secret em variáveis de ambiente ou cofre de segredos no seu backend. Nunca exponha esses valores em frontends, aplicativos móveis ou repositórios de código.
2. Emita o token de acesso (Bearer)
A autenticação inicial utiliza HTTP Basic Auth via POST /api/public/v1/access-tokens enviando client_id como usuário e client_secret como senha.
curl --fail-with-body -X POST "$NOVIUZ_BASE_URL/api/public/v1/access-tokens" \
-u "$NOVIUZ_CLIENT_ID:$NOVIUZ_CLIENT_SECRET"A resposta retorna o token com prefixo nxt_test_ (em ambiente TEST) e validade de 1 hora (3600 segundos). Trate o token como credencial de curta duração.
3. Liste as contas vinculadas e consulte o saldo
Com o token Bearer, envie uma requisição GET /api/public/v1/accounts para listar as contas concedidas à sua aplicação e obter o saldo disponível.
# 1. Listar contas
curl --fail-with-body "$NOVIUZ_BASE_URL/api/public/v1/accounts" \
-H "Authorization: Bearer $NOVIUZ_ACCESS_TOKEN"
# 2. Consultar saldo da conta selecionada
curl --fail-with-body "$NOVIUZ_BASE_URL/api/public/v1/accounts/$ACCOUNT_ID/balance" \
-H "Authorization: Bearer $NOVIUZ_ACCESS_TOKEN"4. Crie uma cobrança PIX com assinatura HMAC
Todas as operações de escrita (POST, PATCH, DELETE) exigem assinatura criptográfica HMAC-SHA256 gerada com seu signing_secret.
O material assinado segue estritamente a fórmula:
material = timestamp + "." + nonce + "." + METHOD + "." + path + "." + body_hashtimestamp: Unix epoch em segundos (Math.floor(Date.now() / 1000)).nonce: String aleatória única de 16 a 128 caracteres (^[A-Za-z0-9_-]{16,128}$).METHOD: Método HTTP em maiúsculas (POST).path: Caminho exato sem query string (/api/public/v1/pix).body_hash: SHA-256 em hex dos bytes exatos do corpo JSON enviado (string vazia se sem corpo).code: Identificador opaco de até 80 caracteres para idempotência financeira.amount: Valor monetário estritamente formatado como string decimal com duas casas (ex:"50.00"), nunca númerofloat.payer_document: CPF ou CNPJ válido do pagador (validado rigorosamente e mascarado no retorno).
import { createHash, createHmac, randomBytes, randomUUID } from 'node:crypto';
const method = 'POST';
const path = '/api/public/v1/pix';
const body = JSON.stringify({
code: `pix_${Date.now()}_${randomUUID().slice(0, 8)}`,
account_id: primaryAccount.id,
amount: '50.00',
payer_document: '52998224725', // CPF válido de teste
payer_name: 'Maria da Silva',
});
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = randomBytes(16).toString('hex');
const bodyHash = createHash('sha256').update(body).digest('hex');
const material = `${timestamp}.${nonce}.${method}.${path}.${bodyHash}`;
const signature = createHmac('sha256', process.env.NOVIUZ_SIGNING_SECRET!)
.update(material)
.digest('hex');
const pixResponse = await fetch(`${process.env.NOVIUZ_BASE_URL}${path}`, {
method,
headers: {
Authorization: `Bearer ${token}`,
'Content-Type': 'application/json',
'X-Timestamp': timestamp,
'X-Nonce': nonce,
'X-Signature': signature,
},
body,
});
if (!pixResponse.ok) {
const err = await pixResponse.json();
throw new Error(`Erro ao criar PIX: ${JSON.stringify(err)}`);
}
const charge = await pixResponse.json();
console.log(`✅ Cobrança PIX criada! ID: ${charge.id}, Status: ${charge.status}`);
console.log(`PIX Copia e Cola: ${charge.qr_code}`);5. Simule o pagamento em Sandbox (Ambiente TEST)
No ambiente TEST, você não precisa de um banco real para confirmar a transação. Chame o endpoint de simulação assinado para liquidar a cobrança:
const simPath = `/api/public/v1/pix/${charge.id}/simulate-payment`;
const simBody = JSON.stringify({ outcome: 'SUCCESS' });
const simTimestamp = Math.floor(Date.now() / 1000).toString();
const simNonce = randomBytes(16).toString('hex');
const simBodyHash = createHash('sha256').update(simBody).digest('hex');
const simMaterial = `${simTimestamp}.${simNonce}.POST.${simPath}.${simBodyHash}`;
const simSig = createHmac('sha256', process.env.NOVIUZ_SIGNING_SECRET!)
.update(simMaterial)
.digest('hex');
const simResponse = await fetch(`${process.env.NOVIUZ_BASE_URL}${simPath}`, {
method: 'POST',
headers: {
Authorization: `Bearer ${token}`,
'Content-Type': 'application/json',
'X-Timestamp': simTimestamp,
'X-Nonce': simNonce,
'X-Signature': simSig,
},
body: simBody,
});
const confirmedCharge = await simResponse.json();
console.log(`⚡ Pagamento simulado com sucesso! Novo status: ${confirmedCharge.status}`);Próximos passos
Referência completa da API
Entenda detalhes de idempotência financeira, política de IP, paginação por cursor e catálogo de erros.
Try API Interativo
Explore e teste todas as operações da API pública diretamente na documentação.
Configurar Webhooks
Receba notificações assíncronas de cobranças PIX pagas e saques liquidados no seu servidor.
Governança e autorização patrimonial
Entenda o modelo do Sistema Operacional Patrimonial da Noviuz — separação de planos, mandatos, capacidade, EUID e soberania.
Ciclo de vida e máquinas de estado
Diagramas de estados formais, transições, regras de negócio e eventos de webhook para cobranças PIX e saques.