Guia de início rápido — SDK PHP

Pacote Composer nuvende/sdk-php, repositório nuvende/conta-php, namespace Nuvende\. Cobre autenticação, 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

• PHP 8.1+
• Composer

Instalação

composer require nuvende/sdk-php

Código fonte, issues e releases: github.com/nuvende/conta-php.

Configuração

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

<?php

require_once 'vendor/autoload.php';

use Nuvende\Client;
use Nuvende\Requests\Autenticacao\AutenticarClienteRequest;

$baseUrl = 'https://api-h.nuvende.com.br'; // homologação; produção: https://api.nuvende.com.br

$client = new Client($baseUrl);

$auth = new AutenticarClienteRequest();
$auth->grantType = 'client_credentials';

$token = $client->autenticacao()->login(
    $auth,
    clientId: getenv('NUVENDE_CLIENT_ID') ?: 'seu-client-id',
    clientSecret: getenv('NUVENDE_CLIENT_SECRET') ?: 'seu-client-secret',
);

$client->definirToken($token->accessToken);

Recursos no Client

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

Exemplos

Cobrança imediata (PUT com txid)

use Nuvende\Requests\Cobrancas\SolicitacaoCobranca;

$request = new SolicitacaoCobranca();
$request->chave = 'e3fe4462-4c8e-42c1-8360-b41b404ae557';
$request->nomeRecebedor = 'Minha Loja';
$request->calendarioExpiracao = 3600;
// Preencha demais campos conforme o contrato em /tecnica/mundo-digital/pix/cobrancas/criar

$cob = $client->cob()->criarOuSubstituir('seu-txid', $request);

echo $cob->txid;
echo $cob->status;

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

Cobrança com vencimento (Cobv)

$cobv = $client->cobv()->criar('seu-txid', $request);
$cobv = $client->cobv()->buscar('seu-txid');

Pagamento Pix por chave

use Nuvende\Requests\Pagamentos\CriarPagamentoChaveRequest;
use Nuvende\Requests\Pagamentos\ConfirmarPagamentoRequest;

$iniciar = new CriarPagamentoChaveRequest();
$iniciar->chave = '[email protected]';

$pagamento = $client->pagamentos()->criarPorChave($iniciar);

$confirmar = new ConfirmarPagamentoRequest();
$confirmar->id = $pagamento->id;
$confirmar->valor = 10.50;

$client->pagamentos()->confirmar($confirmar);

Consultar status: $client->pagamentos()->buscar($pagamento->id).

Webhook de recebimento

use Nuvende\Requests\Webhook\ConfigurarWebhookRequest;

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

$client->webhooks()->criarOuAtualizar('sua-chave-pix', $webhook);

Evento documentado no portal: recebimento.

Conta

$conta = $client->contas()->buscar();
$saldo = $client->contas()->saldo();
$extrato = $client->contas()->extrato();

Exemplo completo

<?php

require_once 'vendor/autoload.php';

use Nuvende\Client;
use Nuvende\Exceptions\AuthenticationException;
use Nuvende\Exceptions\ValidationException;
use Nuvende\Requests\Autenticacao\AutenticarClienteRequest;
use Nuvende\Requests\Cobrancas\SolicitacaoCobranca;

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

$auth = new AutenticarClienteRequest();
$auth->grantType = 'client_credentials';

try {
    $token = $client->autenticacao()->login(
        $auth,
        clientId: $_ENV['NUVENDE_CLIENT_ID'],
        clientSecret: $_ENV['NUVENDE_CLIENT_SECRET'],
    );
    $client->definirToken($token->accessToken);

    $request = new SolicitacaoCobranca();
    $request->chave = 'e3fe4462-4c8e-42c1-8360-b41b404ae557';
    $request->nomeRecebedor = 'Minha Loja';
    $request->calendarioExpiracao = 3600;

    $cob = $client->cob()->criar($request);

    echo "txid: {$cob->txid}\n";
    echo "status: {$cob->status}\n";
} catch (AuthenticationException $e) {
    echo "Autenticação: {$e->getMessage()}\n";
} catch (ValidationException $e) {
    echo "Validação: " . json_encode($e->violacoes, JSON_UNESCAPED_UNICODE) . "\n";
}

Tratamento de erros

Exceções em Nuvende\Exceptions\:

use Nuvende\Exceptions\RateLimitException;

try {
    $client->pagamentos()->listar();
} catch (RateLimitException $e) {
    // aguardar e repetir
}

Onde aprofundar

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

Suporte

• Repositório: github.com/nuvende/conta-php
• Email: [email protected]
• Documentação: https://docs.nuvende.com.br