Introdução às SDKs da Nuvende

Bem-vindo ao guia completo de exemplos para integração com a API da Nuvende! Aqui você encontrará diversos exemplos para guiá-lo na integração da sua aplicação e o ambiente Nuvende.

O que são SDKs?

Uma SDK (Software Development Kit) é como uma "caixa de ferramentas" que facilita o uso de uma API. Em vez de fazer requisições HTTP complexas manualmente, você usa métodos simples e prontos que já estão organizados e testados.

Exemplo sem SDK (difícil):

// Fazer requisição HTTP manual
fetch('https://api-h.nuvende.com.br/api/v2/cobranca/cob/charge-123', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    chave: 'e3fe4462-4c8e-42c1-8360-b41b404ae557',
    nomeRecebedor: 'Minha Loja',
    valor: { original: '100.00', modalidadeAlteracao: 0 },
    devedor: { nome: 'João Silva', cpf: '12345678901' }
  })
})

Exemplo com SDK (fácil):

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

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

Por que usar nossas SDKs?

Vantagens das SDKs da Nuvende:

• Desenvolvimento mais rápido - Métodos prontos e testados
• Segurança integrada - Autenticação e validação automáticas
• Documentação clara - Código autodocumentado e intuitivo
• Manutenção simplificada - Atualizações automáticas da API
• Menos erros - Validação de dados e tratamento de erros
• Performance otimizada - Conexões reutilizadas e cache inteligente

SDKs Disponíveis

A Nuvende oferece SDKs oficiais para as principais linguagens de programação:

SDK Node.js

npm install @nuvende/sdk-node

• Linguagem: JavaScript/TypeScript
• Ambiente: Node.js 18+
• Características: Assíncrono, tipos incluídos, resources cob(), pagamentos(), etc.

SDK Python

pip install nuvende-sdk

• Linguagem: Python 3.10+
• Ambiente: Qualquer ambiente Python
• Características: Síncrono, type hints (py.typed), zero deps runtime

SDK PHP

composer require nuvende/sdk-php

• Linguagem: PHP 8.1+
• Ambiente: Qualquer servidor PHP
• Características: Namespaces PSR-4, autoloading, Composer
• Repositório: github.com/nuvende/conta-php

Estrutura Organizada com Namespaces

Todas as nossas SDKs seguem uma estrutura organizada em namespaces para facilitar o uso:

Autenticação

// Métodos diretos para autenticação
await client.login()        // Fazer login
await client.logout()       // Fazer logout  
await client.getUser()      // Obter dados do usuário

KYC (Know Your Customer)

// Verificação de pessoas físicas e jurídicas
await client.kyc.backgroundCheckNaturalPerson('12345678901')
await client.kyc.backgroundCheckLegalPerson('12345678000195')

Payment (Pagamentos e Cobranças)

// Gestão completa de pagamentos Pix
await client.payment.createCharge('charge-123', {...})
await client.payment.getCharge('charge-123')
await client.payment.listTransactions()
await client.payment.createTransaction({...})

Webhook (Notificações)

// Configuração de notificações automáticas
await client.webhook.createWebhook('sua-chave-pix', {...})
await client.webhook.listWebhooks('sua-chave-pix')
await client.webhook.deleteWebhook('sua-chave-pix')

Merchant (Estabelecimentos)

// Gestão de estabelecimentos comerciais
await client.merchant.listMerchants()
await client.merchant.createMerchant({...})
await client.merchant.updateMerchant('merchant-id', {...})
await client.merchant.deleteMerchant('merchant-id')

Terminal (Terminais)

// Gestão de terminais de pagamento
await client.terminal.listTerminals()
await client.terminal.createTerminal({...})
await client.terminal.updateTerminal('terminal-id', {...})

Document (Documentos)

// Gestão de documentos e comprovantes
await client.document.createDocument({...})
await client.document.updateDocument('document-id', {...})

Ambientes Disponíveis

A API da Nuvende opera em dois ambientes distintos:

Sandbox (Homologação)

• URL: https://api-h.nuvende.com.br
• Uso: Testes e desenvolvimento
• Características: Dados simulados, sem impacto real

Produção

• URL: https://api.nuvende.com.br
• Uso: Operações reais
• Características: Transações efetivas, dados reais

Configuração Básica

1. Instalar a SDK

# Node.js
npm install @nuvende/sdk-node

# Python  
pip install nuvende-sdk

# PHP
composer require nuvende/sdk-php

2. Configurar Credenciais

// Node.js
import { Client, AutenticarClienteRequest } from '@nuvende/sdk-node';

const client = new Client('https://api-h.nuvende.com.br');
const auth = new AutenticarClienteRequest();
auth.grantType = 'client_credentials';
const token = await client.autenticacao().login(
  auth,
  process.env.NUVENDE_CLIENT_ID!,
  process.env.NUVENDE_CLIENT_SECRET!,
);
client.definirToken(token.accessToken);

# Python
import os
from nuvende import Client, AutenticarClienteRequest

client = Client('https://api-h.nuvende.com.br')
auth = AutenticarClienteRequest(grant_type='client_credentials')
token = client.autenticacao().login(
    auth,
    os.environ['NUVENDE_CLIENT_ID'],
    os.environ['NUVENDE_CLIENT_SECRET'],
)
client.definir_token(token.access_token)

// PHP (nuvende/sdk-php)
use Nuvende\Client;
use Nuvende\Requests\Autenticacao\AutenticarClienteRequest;

$client = new Client('https://api-h.nuvende.com.br');
$auth = new AutenticarClienteRequest();
$auth->grantType = 'client_credentials';
$token = $client->autenticacao()->login($auth, clientId: '...', clientSecret: '...');
$client->definirToken($token->accessToken);

3. Fazer Primeira Requisição

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

const cob = await client.cob().criar(
  Object.assign(new SolicitacaoCobranca(), {
    chave: 'sua-chave-pix',
    nomeRecebedor: 'Minha Loja',
    calendarioExpiracao: 3600,
  }),
);
console.log('txid:', cob.txid);

Segurança e Boas Práticas

Sempre faça:

• Use HTTPS em todas as requisições
• Mantenha credenciais seguras (nunca no código)
• Teste primeiro no sandbox antes de produção
• Configure webhooks para notificações
• Monitore logs para identificar problemas
• Use try/catch para tratar erros
• Valide dados antes de enviar

Nunca faça:

• Expor credenciais no código fonte
• Usar ambiente de produção para testes
• Ignorar tratamento de erros
• Fazer requisições sem autenticação
• Armazenar tokens em localStorage (frontend)

Variáveis de Ambiente

Arquivo .env:

NUVENDE_CLIENT_ID=seu-client-id
NUVENDE_CLIENT_SECRET=seu-client-secret

Uso no código:

const client = new Client(
  process.env.NUVENDE_BASE_URL ?? 'https://api-h.nuvende.com.br',
);
// login com process.env.NUVENDE_CLIENT_ID / NUVENDE_CLIENT_SECRET

Rate Limits e Controle de Acesso

A API possui limites de requisições para garantir estabilidade:

Tratamento de Rate Limit:

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

try {
  await client.pagamentos().listar();
} catch (e) {
  if (e instanceof RateLimitException) {
    // aguardar e repetir
  }
}

Próximos Passos

Agora que você entende o básico sobre nossas SDKs, escolha sua linguagem preferida e siga para o guia específico:

• SDK Node.js - Para aplicações JavaScript/TypeScript
• SDK Python - Para aplicações Python
• SDK PHP - Para aplicações PHP
• SDK Java - Para aplicações Java
• Collections Postman - Para testes manuais

Precisa de Ajuda?

• Email: [email protected]
• Documentação: https://docs.nuvende.com.br
• Issues (SDK PHP): github.com/nuvende/conta-php/issues
• Suporte Técnico: Disponível 24/7

Dica: Comece sempre pelo ambiente sandbox para testar suas integrações antes de migrar para produção!