Guia de início rápido — SDK Node.js

Pacote npm @nuvende/sdk-node. Cobre autenticação OAuth banking, cobranças Pix (Cob e Cobv), webhooks, contas e pagamentos Pix (cash-out) da API v2.

KYC, parceiros, terminais e documentos não estão neste pacote — use a Referência API com HTTP direto.

Pré-requisitos

• Node.js >= 18
• TypeScript recomendado (tipos incluídos)

Instalação

npm install @nuvende/sdk-node

Configuração

A conta da operação vem do Bearer token — não envie header Account-Id.

import {
  Client,
  AutenticarClienteRequest,
  NUVENDE_URL_HOMOLOGACAO,
} from '@nuvende/sdk-node';

const client = new Client(NUVENDE_URL_HOMOLOGACAO);

const auth = new AutenticarClienteRequest();
auth.grantType = 'client_credentials';

await client.autenticacao().loginComCredenciais(
  auth,
  process.env.NUVENDE_CLIENT_ID ?? 'seu-client-id',
  process.env.NUVENDE_CLIENT_SECRET ?? 'seu-client-secret',
);
// Bearer já configurado

Auth: o pacote banking usa api/v1/cobranca/auth (login/logout/refresh). O OpenAPI do portal também documenta api/v2/auth/* e POST /auth/user — fora deste SDK.

Recursos no Client

Guias de fluxo: Cobranças · Cobv · Pagamentos.

Exemplos

Cobrança imediata (PUT com txid)

import { SolicitacaoCobranca } from '@nuvende/sdk-node';

const request = Object.assign(new SolicitacaoCobranca(), {
  chave: 'e3fe4462-4c8e-42c1-8360-b41b404ae557',
  nomeRecebedor: 'Minha Loja',
  calendarioExpiracao: 3600,
});

const cob = await client.cob().criarOuSubstituir('seu-txid', request);

console.log(cob.txid, cob.status);

Alternativa sem txid na URL: client.cob().criar(request) (POST /api/v2/cobranca/cob).

Pagamento Pix por chave + confirmar

import {
  CriarPagamentoChaveRequest,
  ConfirmarPagamentoRequest,
} from '@nuvende/sdk-node';

const iniciar = Object.assign(new CriarPagamentoChaveRequest(), {
  chave: '[email protected]',
});

const pagamento = await client.pagamentos().criarPorChave(iniciar);

const confirmar = new ConfirmarPagamentoRequest();
confirmar.id = pagamento.id!;
confirmar.valor = 10.5;
confirmar.chaveIdempotencia = 'confirm-chave-001';
confirmar.recebedor = pagamento.recebedor!; // obrigatório — copie da iniciação

await client.pagamentos().confirmar(confirmar);

Consultar status: client.pagamentos().buscar(pagamento.id!).

Ver Confirmar pagamento para o contrato completo do body.

Webhook de recebimento

import { ConfigurarWebhookRequest } from '@nuvende/sdk-node';

const webhook = new ConfigurarWebhookRequest();
webhook.webhookUrl = 'https://seusite.com/webhook/pix';

await client.webhooks().criarOuAtualizar('sua-chave-pix', webhook);

Conta

const conta = await client.contas().buscar();
const saldo = await client.contas().saldo();
const extrato = await client.contas().extrato();

Exemplo completo

import {
  Client,
  AutenticarClienteRequest,
  AuthenticationException,
  SolicitacaoCobranca,
  ValidationException,
} from '@nuvende/sdk-node';

const client = new Client('https://api-h.nuvende.com.br');

const auth = new AutenticarClienteRequest();
auth.grantType = 'client_credentials';

try {
  const token = await client.autenticacao().login(
    auth,
    process.env.NUVENDE_CLIENT_ID!,
    process.env.NUVENDE_CLIENT_SECRET!,
  );
  client.definirToken(token.accessToken);

  const request = Object.assign(new SolicitacaoCobranca(), {
    chave: 'e3fe4462-4c8e-42c1-8360-b41b404ae557',
    nomeRecebedor: 'Minha Loja',
    calendarioExpiracao: 3600,
  });

  const cob = await client.cob().criar(request);
  console.log(`txid: ${cob.txid}`);
} catch (e) {
  if (e instanceof AuthenticationException) {
    console.error('Autenticação:', e.message);
  } else if (e instanceof ValidationException) {
    console.error('Validação:', e.violacoes);
  }
}

Tratamento de erros

import {
  isRateLimitException,
  isValidationException,
  recebedorPixFromApi,
} from '@nuvende/sdk-node';

try {
  await client.pagamentos().listar();
} catch (e) {
  if (isRateLimitException(e) && e.retryAfterSeconds) {
    // aguardar e repetir
  }
  if (isValidationException(e)) {
    console.error(e.violacoes);
  }
}

// Fluxo confirmar — copiar recebedor da iniciação
confirmar.recebedor = recebedorPixFromApi(pagamento.recebedor);

Recursos exportados

O pacote inclui requests tipados, ResultadoPaginado, constantes de ambiente (NUVENDE_URL_*), type guards (isApiException, etc.), MockTransport para testes e client.solicitar() para rotas fora do escopo banking.

Onde aprofundar

• Mapa de endpoints v2
• Referência API
• Códigos de erro

Suporte

• Email: [email protected]
• Documentação: https://docs.nuvende.com.br