Guia de início rápido — SDK Python

Pacote PyPI nuvende-sdk, import nuvende. 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

• Python 3.10+
• Sem dependências de runtime (stdlib)

Instalação

pip install nuvende-sdk

Configuração

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

import os
from nuvende import Client, AutenticarClienteRequest, NUVENDE_URL_HOMOLOGACAO

client = Client(NUVENDE_URL_HOMOLOGACAO)

auth = AutenticarClienteRequest(grant_type='client_credentials')

client.autenticacao().login_com_credenciais(
    auth,
    os.environ.get('NUVENDE_CLIENT_ID', 'seu-client-id'),
    os.environ.get('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

Métodos em snake_case, alinhados à API REST.

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

Exemplos

Cobrança imediata (PUT com txid)

from nuvende import SolicitacaoCobranca

request = SolicitacaoCobranca(
    chave='e3fe4462-4c8e-42c1-8360-b41b404ae557',
    nome_recebedor='Minha Loja',
    calendario_expiracao=3600,
)

cob = client.cob().criar_ou_substituir('seu-txid', request)

print(cob.get('txid'), cob.get('status'))

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

Pagamento Pix por chave + confirmar

from nuvende import (
    CriarPagamentoChaveRequest,
    ConfirmarPagamentoRequest,
    RecebedorPix,
)

iniciar = CriarPagamentoChaveRequest(chave='[email protected]')

pagamento = client.pagamentos().criar_por_chave(iniciar)

client.pagamentos().confirmar(ConfirmarPagamentoRequest(
    id=pagamento['id'],
    valor=10.50,
    chave_idempotencia='confirm-chave-001',
    recebedor=RecebedorPix.from_dict(pagamento.get('recebedor')),
))

Consultar status: client.pagamentos().buscar(pagamento['id']).

Ver Confirmar pagamento para o contrato completo do body.

Webhook de recebimento

from nuvende import ConfigurarWebhookRequest

webhook = ConfigurarWebhookRequest(webhook_url='https://seusite.com/webhook/pix')

client.webhooks().criar_ou_atualizar('sua-chave-pix', webhook)

Conta

conta = client.contas().buscar()
saldo = client.contas().saldo()
extrato = client.contas().extrato()

Exemplo completo

import os
from nuvende import (
    AuthenticationException,
    AutenticarClienteRequest,
    Client,
    SolicitacaoCobranca,
    ValidationException,
)

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

auth = AutenticarClienteRequest(grant_type='client_credentials')

try:
    token = client.autenticacao().login(
        auth,
        os.environ['NUVENDE_CLIENT_ID'],
        os.environ['NUVENDE_CLIENT_SECRET'],
    )
    client.definir_token(token.access_token)

    request = SolicitacaoCobranca(
        chave='e3fe4462-4c8e-42c1-8360-b41b404ae557',
        nome_recebedor='Minha Loja',
        calendario_expiracao=3600,
    )

    cob = client.cob().criar(request)
    print(f"txid: {cob.get('txid')}")
except AuthenticationException as e:
    print(f'Autenticação: {e}')
except ValidationException as e:
    print(f'Validação: {e.violacoes}')

Tratamento de erros

from nuvende import RateLimitException, is_rate_limit_exception, RecebedorPix
import time

try:
    client.pagamentos().listar()
except RateLimitException as e:
    if is_rate_limit_exception(e) and e.retry_after_seconds:
        time.sleep(e.retry_after_seconds)
    raise

# Fluxo confirmar — copiar recebedor da iniciação
RecebedorPix.from_dict(pagamento.get('recebedor'))

Recursos exportados

O pacote inclui requests tipados, TypedDict (PagamentoPix, CobrancaImediata), py.typed, ResultadoPaginado, constantes NUVENDE_URL_*, type guards, 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