> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pag.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Uso e Exemplos

> Exemplos práticos de uso do SDK: endpoints públicos, chamadas autenticadas, tratamento de erros e o fluxo ponta a ponta de transação.

Esta página reúne exemplos práticos de uso do `@pagfinance/sdk`.

## Endpoints públicos (sem autenticação)

```ts theme={null}
import { PagFinanceClient } from '@pagfinance/sdk';

const client = new PagFinanceClient({
  baseUrl: 'https://app.pag.finance',
  clientId: 'meu-app',
  appMeta: { name: 'meu-app', version: '1.0.0', domain: 'meuapp.com' },
  defaultBlockchain: 'solana',
});

// Configuração de criptos aceitas
const config = await client.assets.acceptedCryptos();

// Preço de um ativo em uma moeda fiat
const price = await client.assets.getAssetPrice({ assetId: 1, fiatCurrency: 'BRL' });

// Validação de um código de pagamento (PIX, boleto ou giftcard)
const transfer = await client.payments.validateCode({ code: '00020101...' });
```

## Chamadas autenticadas

Forneça o token JWT obtido fora do SDK e chame endpoints protegidos:

```ts theme={null}
client.setToken(tokenJWT);

const me = await client.user.me();
```

## Fluxo ponta a ponta de transação

O fluxo típico de pagamento segue três passos: cotação, criação e recibo.

<Steps>
  <Step title="Cotar">
    Solicite uma cotação para o pagamento desejado.

    ```ts theme={null}
    const quote = await client.payments.quote({
      code: '00020101...',
      assetId: 1,
      blockchain: 'solana',
    });
    ```
  </Step>

  <Step title="Criar">
    Crie o pagamento a partir da cotação.

    ```ts theme={null}
    const payment = await client.payments.create({
      quoteId: quote.id,
    });
    ```
  </Step>

  <Step title="Submeter e acompanhar">
    Submeta a transação e consulte o recibo.

    ```ts theme={null}
    await client.payments.submit({ paymentId: payment.id, txHash: '...' });

    const receipt = await client.receipts.get({
      type: 'pix',
      tx: payment.id,
      chain: 'solana',
    });
    ```
  </Step>
</Steps>

<Note>
  Os campos exatos de cada requisição e resposta dependem do contrato da API. Consulte a [API Reference](/pt-BR/api-reference/overview) e a [Referência de Métodos](/pt-BR/sdks/method-reference) para detalhes de parâmetros.
</Note>

## Tratamento de erros

Toda falha lança `PagFinanceError`, com mensagens e erros de campo já normalizados:

```ts theme={null}
import { PagFinanceError } from '@pagfinance/sdk';

try {
  await client.payments.quote(req);
} catch (e) {
  if (e instanceof PagFinanceError) {
    console.error(e.messages, e.fieldErrors, e.httpStatus);
  }
}
```

<Info>
  O `PagFinanceError` normaliza os dois envelopes de resposta da API (`{ success, data }` e `{ ok, error }`) em uma única estrutura com `messages`, `fieldErrors`, `httpStatus` e `code`.
</Info>

## Exemplo executável

O pacote inclui um exemplo ponta a ponta real em `examples/transaction-flow` (cotação, criação e recibo) usando um `TOKEN_JWT` de variável de ambiente:

```bash theme={null}
pnpm --filter @pagfinance/sdk build

PAGFINANCE_BASE_URL=https://app.pag.finance \
PAGFINANCE_CLIENT_ID=exemplo \
TOKEN_JWT=... \
PAYMENT_CODE='00020101...' \
SENDER_WALLET=7NaNvh... \
npx tsx examples/transaction-flow/index.ts
```

<Tip>
  Consulte o pacote oficial no [npm](https://www.npmjs.com/package/@pagfinance/sdk) para o código de exemplo mais recente.
</Tip>