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

# Início rápido do SDK para TypeScript

> Instale e configure o SDK oficial server-side para TypeScript, depois faça requisições seguras com metadados de resposta, retentativas e erros tipados.

Use o SDK TypeScript em código confiável do lado do servidor. Não envie chaves secretas da API para o navegador.

## Qual SDK devo usar?

Use o SDK TypeScript em código server-side confiável para criar pagamentos, consultar transações, emitir reembolsos e criar transferências. Use o SDK v3 de navegador pelo Payment Element quando precisar de campos hospedados de cartão em uma página de checkout.

| Necessidade                                                                     | Use                                                                          |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Criar requisições Pix, voucher, cartão, reembolso e transferência pelo back-end | SDK TypeScript                                                               |
| Montar campos hospedados e tokenizar cartão no navegador                        | [Referência do SDK v3](/pt/frontend/payment-element/sdk-reference)           |
| Continuar um challenge 3D Secure no navegador                                   | [Referência do SDK v3](/pt/frontend/payment-element/sdk-reference#3d-secure) |

## Requisitos

* TypeScript ou JavaScript rodando no seu back-end.
* Uma chave secreta da Pagou para o ambiente chamado.
* Um runtime com `fetch`. Se seu runtime não expõe `fetch` global, injete uma implementação customizada nas opções do cliente.

## Instalação

```bash theme={null}
bun add @pagouai/api-sdk
```

## Crie um cliente

```ts theme={null}
import { Client } from "@pagouai/api-sdk";

const client = new Client({
  apiKey: process.env.PAGOU_API_KEY!,
  environment: "sandbox",
  timeoutMs: 30_000,
  maxRetries: 2,
});
```

Ambientes:

| Ambiente     | Base URL                       |
| ------------ | ------------------------------ |
| `production` | `https://api.pagou.ai`         |
| `sandbox`    | `https://api.sandbox.pagou.ai` |

Você também pode informar `baseUrl` para testes de desenvolvimento ou proxies controlados.

## Formato de resposta

Os métodos do SDK retornam `{ data, meta }`. `data` é o payload da API. `meta` contém metadados HTTP e o request ID usado para rastreio.

```ts theme={null}
const created = await client.transactions.create({
  external_ref: "order_1001",
  amount: 1500,
  currency: "BRL",
  method: "pix",
  buyer: {
    name: "Ada Lovelace",
    email: "ada@example.com",
    document: { type: "CPF", number: "12345678901" },
  },
  products: [{ name: "Starter order", price: 1500, quantity: 1 }],
});

console.log(created.data.id);
console.log(created.data.status);
console.log(created.meta.requestId);
```

## Primeiro pagamento Pix

```ts theme={null}
const created = await client.transactions.create(
  {
    external_ref: "order_1001",
    amount: 1500,
    currency: "BRL",
    method: "pix",
    buyer: {
      name: "Ada Lovelace",
      email: "ada@example.com",
      document: { type: "CPF", number: "12345678901" },
    },
    products: [{ name: "Starter order", price: 1500, quantity: 1 }],
  },
  {
    idempotencyKey: "tx_order_1001",
    requestId: "req_order_1001",
  },
);
```

## Opções por requisição

Todo método de recurso aceita um segundo argumento opcional:

```ts theme={null}
await client.transactions.retrieve("018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f", {
  requestId: "reconcile_018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f",
  timeoutMs: 10_000,
  signal: abortController.signal,
});
```

| Opção            | Uso                                                                  |
| ---------------- | -------------------------------------------------------------------- |
| `idempotencyKey` | Obrigatória para retentativas seguras em requisições `POST` e `PUT`. |
| `requestId`      | Envia `X-Request-Id` para rastreio.                                  |
| `timeoutMs`      | Sobrescreve o timeout do cliente para uma requisição.                |
| `signal`         | Cancela a requisição com um `AbortSignal`.                           |

## Variações de autenticação

Bearer auth é o padrão e a configuração recomendada.

```ts theme={null}
new Client({ apiKey: process.env.PAGOU_API_KEY!, auth: { scheme: "bearer" } });
```

Use os outros modos apenas para integrações legadas ou camadas de compatibilidade:

```ts theme={null}
new Client({ apiKey: process.env.PAGOU_API_KEY!, auth: { scheme: "basic" } });
new Client({ apiKey: process.env.PAGOU_API_KEY!, auth: { scheme: "api_key_header", headerName: "apiKey" } });
```

## Comportamento de retentativa

* Retries cobrem falhas de rede e `429`, `500`, `502`, `503`, `504`.
* `GET` e `HEAD` repetem automaticamente.
* `POST` e `PUT` só repetem quando você define `idempotencyKey`.
* A quantidade padrão de retentativas é `2`.
* O timeout padrão é `30_000` ms.

Defina chaves de idempotência em qualquer pagamento, reembolso, transferência ou cancelamento que possa ser repetido:

```ts theme={null}
await client.transactions.refund(
  "018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f",
  { amount: 500, reason: "requested_by_customer" },
  { idempotencyKey: "refund_018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f_1" },
);
```

## Tratamento de erros

```ts theme={null}
import { ApiError, NotFoundError, RateLimitError } from "@pagouai/api-sdk";

try {
  const transaction = await client.transactions.retrieve("018f1f2e-7b99-7c9a-8d3e-1a2b3c4d5e99");
  console.log(transaction.data.status);
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error("Transação não encontrada", error.requestId);
  } else if (error instanceof RateLimitError) {
    console.error("Rate limit atingido", error.status, error.requestId);
  } else if (error instanceof ApiError) {
    console.error(error.status, error.code, error.requestId, error.details);
  } else {
    throw error;
  }
}
```

Erros exportados pelo SDK incluem `AuthenticationError`, `PermissionError`, `RateLimitError`, `InvalidRequestError`, `NotFoundError`, `ConflictError`, `ServerError` e `NetworkError`.

## Leia a seguir

* [Pagamentos com o SDK TypeScript](/pt/sdks/typescript/payments)
* [Transferências com o SDK TypeScript](/pt/sdks/typescript/transfers)
* [Referência do SDK v3](/pt/frontend/payment-element/sdk-reference)