API pública da Conta Nexiuz

A API pública da Conta Nexiuz é a interface oficial servidor a servidor em /api/public/v1 para parceiros e sistemas integradores.

Fluxo recomendadoCopy Anchor Link

1. No Portal, crie uma aplicação e vincule somente as contas e escopos necessários. Gere credenciais TEST para desenvolvimento.
2. Armazene client_secret e signing_secret em um cofre de segredos no backend. Nunca os envie a navegador ou aplicativo móvel.
3. Troque client_id e client_secret por um token com POST /api/public/v1/access-tokens usando HTTP Basic.
4. Envie o token como Authorization: Bearer …. Para escritas, assine o método, caminho e bytes exatos do corpo com HMAC-SHA256.
5. Em toda mutação financeira, reutilize o mesmo code ao repetir a mesma intenção após timeout; use um code novo para uma intenção nova.

Autenticação e tokenCopy Anchor Link

curl -X POST "$BASE_URL/api/public/v1/access-tokens" \
  -u "$NOVIUZ_CLIENT_ID:$NOVIUZ_CLIENT_SECRET"

Resposta real (200):

{
  "token": "nxt_test_…",
  "expiresIn": 3600,
  "type": "Bearer"
}

O token dura uma hora. Renove-o antes de expirar. A aplicação, a credencial e o token precisam permanecer ativos; suspender a aplicação ou revogar a credencial bloqueia autenticações subsequentes. O token é retornado com Cache-Control: no-store.

EscoposCopy Anchor Link

O escopo do token limita a credencial. A aplicação também precisa ter a autorização exigida para a conta/operação; possuir withdrawals:write, por exemplo, não substitui a autorização de saque aplicável à Entity. Contas fora do vínculo da aplicação respondem 404 OBJECT_NOT_FOUND.

Assinatura das escritasCopy Anchor Link

Todas as rotas POST, PATCH e DELETE da API pública que exigem assinatura usam X-Signature, X-Timestamp e X-Nonce, além do Bearer. Gere o hash sobre os bytes exatos enviados. Para corpo vazio, o hash no material é a string vazia.

body_hash = hex(SHA256(raw_body))   # vazio se não houver corpo
material  = timestamp + "." + nonce + "." + METHOD + "." + path + "." + body_hash
signature = hex(HMAC_SHA256(signing_secret, material))

O METHOD é maiúsculo; path inclui o prefixo /api/public/v1 e não inclui query string. O timestamp é Unix em segundos: por padrão o servidor aceita até 300 segundos de idade e até 60 segundos de adiantamento (o limite de idade pode ser configurado por ambiente). X-Nonce deve ter 16–128 caracteres ASCII entre letras, números, _ e -; cada nonce só pode ser usado uma vez. Assinatura, timestamp, nonce ou credencial inválidos retornam erro genérico 401.

Exemplo Node.js para serializar e assinar uma requisição JSON:

import { createHash, createHmac, randomBytes, randomUUID } from 'node:crypto';

const method = 'POST';
const path = '/api/public/v1/pix';
const body = JSON.stringify({
  code: randomUUID(),
  account_id: process.env.NOVIUZ_ACCOUNT_ID,
  amount: '50.00',
  payer_document: '52998224725',
});
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 response = await fetch(`${process.env.NOVIUZ_BASE_URL}${path}`, {
  method,
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
    'X-Timestamp': timestamp,
    'X-Nonce': nonce,
    'X-Signature': signature,
  },
  body,
});

Não serialize o objeto novamente depois de calcular a assinatura: qualquer mudança nos bytes invalida o HMAC. Em produção, adicione timeout, tratamento do corpo de erro e renovação de token.

Idempotência financeiraCopy Anchor Link

PIX e saque identificam a intenção pelo campo code no corpo. Reenvie o mesmo corpo e code depois de timeout para obter o resultado da mesma operação. Se a chave já existir com dados diferentes, a API responde 409 IDEMPOTENCY_CONFLICT. Não gere um code novo automaticamente ao repetir uma chamada cujo resultado é desconhecido: isso pode criar uma segunda operação.

EndpointsCopy Anchor Link

Todas as respostas monetárias usam strings decimais. Valores devem ser positivos, finitos e ter no máximo duas casas decimais; o servidor não arredonda silenciosamente. Os cursores de paginação são opacos: envie after ou before, nunca ambos.

Criar cobrança PIXCopy Anchor Link

POST /api/public/v1/pix
Authorization: Bearer <token>
Content-Type: application/json
X-Timestamp: <unix-seconds>
X-Nonce: <unique-random-value>
X-Signature: <hex-hmac>

{
  "code": "order-4821-payment-1",
  "account_id": "<id-da-conta-vinculada>",
  "amount": "100.50",
  "payer_document": "52998224725",
  "payer_name": "Cliente",
  "metadata": {"order_id": "4821"}
}

metadata aceita até 50 pares; nomes de chave que indiquem PII (documento, e-mail, telefone, nome etc.) são recusados. Documentos são mascarados nas respostas. Uma criação nova retorna 201; replay idêntico retorna 200 com o recurso existente.

Solicitar saqueCopy Anchor Link

{
  "code": "payout-4821-1",
  "account_id": "<id-da-conta-vinculada>",
  "amount": "25.00",
  "destination": {
    "rail": "PIX",
    "pix_key": "financeiro@example.com",
    "pix_key_type": "EMAIL",
    "beneficiary_document": "52998224725",
    "beneficiary_name": "Beneficiário"
  }
}

O destino e os documentos são mascarados na resposta. Saques podem exigir um grant/autorização ativa no escopo patrimonial da conta; um token com o escopo correto, sozinho, não garante que a solicitação será autorizada.

ErrosCopy Anchor Link

Corpo de erro da API: {"code":"…","message":"…","errors":[]}. Use code para lógica de máquina; message é texto informativo.

WebhooksCopy Anchor Link

Eventos, formato de assinatura, deduplicação e política de retentativa estão no guia de Webhooks. O catálogo é limitado aos eventos habilitados para sua aplicação.