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

# SDK

> SDKs oficiais da Avantti Finance para Node.js, PHP, Python, Go e Java — integrações rápidas, modernas e previsíveis.

SDKs oficiais da Avantti Finance para integrações rápidas, modernas e previsíveis. Com poucos comandos você cria pagamentos, gerencia clientes, escuta eventos e automatiza operações.

As SDKs da Avantti foram desenvolvidas para simplificar integrações financeiras em qualquer stack.

SDKs oficiais da Avantti Finance para integrações rápidas, modernas e previsíveis. Com poucos comandos você cria pagamentos, gerencia clientes, escuta eventos e automatiza operações.

As SDKs da Avantti foram desenvolvidas para simplificar integrações financeiras em qualquer stack.

## SDKs disponíveis

| Linguagem | Pacote            |
| --------- | ----------------- |
| Node.js   | `@avantti/sdk`    |
| PHP       | `avantti/sdk-php` |
| Python    | `avantti-python`  |
| Go        | `avantti-go`      |
| Java      | `avantti-java`    |

## Filosofia das SDKs

As SDKs da Avantti seguem os mesmos princípios da plataforma: simples, modernas, type-safe, rápidas, consistentes, AI-ready e preparadas para automação.

## Autenticação

Todas as SDKs utilizam API Keys seguras.

```env theme={null}
AVANTTI_API_KEY=sk_test_xxxxxxxxx
```

## Instalação e inicialização

<Tabs>
  <Tab title="Node.js">
    <CodeGroup>
      ```bash npm theme={null}
      npm install @avantti/sdk
      ```

      ```bash pnpm theme={null}
      pnpm add @avantti/sdk
      ```

      ```bash yarn theme={null}
      yarn add @avantti/sdk
      ```
    </CodeGroup>

    ```ts theme={null}
    import { Avantti } from "@avantti/sdk"

    const avantti = new Avantti({
      apiKey: process.env.AVANTTI_API_KEY
    })
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require avantti/sdk-php
    ```

    ```php theme={null}
    <?php

    use Avantti\Client;

    $avantti = new Client([
      "api_key" => $_ENV["AVANTTI_API_KEY"]
    ]);
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install avantti-python
    ```

    ```python theme={null}
    from avantti import Avantti
    import os

    avantti = Avantti(
        api_key=os.getenv("AVANTTI_API_KEY")
    )
    ```
  </Tab>

  <Tab title="Go">
    ```bash theme={null}
    go get github.com/avanttifinance/avantti-go
    ```

    ```go theme={null}
    package main

    import (
      "github.com/avanttifinance/avantti-go"
    )

    client := avantti.New("sk_test_xxxxx")
    ```
  </Tab>

  <Tab title="Java">
    ```xml theme={null}
    <dependency>
      <groupId>com.avantti</groupId>
      <artifactId>avantti-java</artifactId>
      <version>1.0.0</version>
    </dependency>
    ```

    ```java theme={null}
    Avantti client = new Avantti("sk_test_xxxxx");
    ```
  </Tab>
</Tabs>

## Criar pagamento PIX

<CodeGroup>
  ```ts Node.js theme={null}
  const payment = await avantti.payments.create({
    method: "pix",
    amount: 5000,
    customer: {
      name: "João Silva",
      email: "joao@email.com"
    }
  })
  ```

  ```php PHP theme={null}
  $payment = $avantti->payments->create([
    "method" => "pix",
    "amount" => 5000
  ]);
  ```

  ```python Python theme={null}
  payment = avantti.payments.create({
      "method": "pix",
      "amount": 5000
  })
  ```

  ```go Go theme={null}
  payment, err := client.Payments.Create(
    avantti.PaymentRequest{
      Method: "pix",
      Amount: 5000,
    },
  )
  ```

  ```java Java theme={null}
  Payment payment = client.payments().create(
    new PaymentRequest()
      .method("pix")
      .amount(5000)
  );
  ```
</CodeGroup>

## Outras operações (Node.js)

### Buscar pagamento

```ts theme={null}
const payment = await avantti.payments.get("pay_123456")
```

### Listar pagamentos

```ts theme={null}
const payments = await avantti.payments.list()
```

### Criar cliente

```ts theme={null}
const customer = await avantti.customers.create({
  name: "João Silva",
  email: "joao@email.com"
})
```

### Criar assinatura

```ts theme={null}
const subscription = await avantti.subscriptions.create({
  customerId: "cus_123456",
  plan: "premium"
})
```

## Webhooks (Express.js)

```ts theme={null}
import express from "express"

const app = express()

app.post("/webhooks", async (req, res) => {
  const signature = req.headers["avantti-signature"]

  const event = avantti.webhooks.constructEvent(
    req.body,
    signature
  )

  switch (event.type) {
    case "payment.approved":
      console.log("Pagamento aprovado")
      break
  }

  res.sendStatus(200)
})
```

## Tratamento de erros

```ts theme={null}
try {
  await avantti.payments.create({
    method: "pix",
    amount: 5000
  })
} catch (error) {
  console.error(error.message)
}
```

## Estrutura de recursos

| Recurso         | Descrição   |
| --------------- | ----------- |
| `payments`      | Pagamentos  |
| `customers`     | Clientes    |
| `subscriptions` | Assinaturas |
| `webhooks`      | Eventos     |
| `refunds`       | Reembolsos  |
| `accounts`      | Contas      |
| `balance`       | Saldo       |

## Paginação e filtros

```ts theme={null}
const payments = await avantti.payments.list({
  page: 1,
  limit: 10
})
```

```ts theme={null}
const payments = await avantti.payments.list({
  status: "approved"
})
```

## Idempotência

A API suporta idempotência para evitar cobranças duplicadas.

```ts theme={null}
await avantti.payments.create(
  {
    method: "pix",
    amount: 5000
  },
  {
    idempotencyKey: "payment-123"
  }
)
```

## Retry automático

As SDKs possuem retry automático para falhas temporárias de rede.

## Timeouts, sandbox e produção

<CodeGroup>
  ```ts Timeout theme={null}
  const avantti = new Avantti({
    apiKey: process.env.AVANTTI_API_KEY,
    timeout: 10000
  })
  ```

  ```ts Sandbox theme={null}
  const avantti = new Avantti({
    apiKey: process.env.AVANTTI_API_KEY,
    environment: "sandbox"
  })
  ```

  ```ts Produção theme={null}
  const avantti = new Avantti({
    apiKey: process.env.AVANTTI_API_KEY,
    environment: "production"
  })
  ```
</CodeGroup>

## Logs

Ative logs detalhados para depuração:

```ts theme={null}
const avantti = new Avantti({
  apiKey: process.env.AVANTTI_API_KEY,
  debug: true
})
```

## TypeScript

A SDK Node.js possui suporte completo para TypeScript.

```ts theme={null}
const payment: Payment = await avantti.payments.create({
  method: "pix",
  amount: 5000
})
```

## Segurança

As SDKs utilizam HTTPS obrigatório, criptografia TLS, API Keys seguras, validação de assinatura e rotação de credenciais.

<Tip>
  Nunca exponha chaves privadas, utilize variáveis de ambiente, use sandbox durante o desenvolvimento, implemente retries e faça validação de webhooks.
</Tip>

## Versionamento

As SDKs seguem Semantic Versioning (`1.0.0`):

* **MAJOR** → mudanças incompatíveis
* **MINOR** → novas funcionalidades
* **PATCH** → correções

Acompanhe atualizações e mudanças através do changelog oficial.

## Exemplos reais

<CodeGroup>
  ```ts Criar checkout PIX theme={null}
  const checkout = await avantti.checkouts.create({
    amount: 5000,
    method: "pix",
    successUrl: "https://meusite.com/success"
  })
  ```

  ```ts Reembolso theme={null}
  await avantti.refunds.create({
    paymentId: "pay_123456"
  })
  ```

  ```ts Saldo theme={null}
  const balance = await avantti.balance.get()
  ```
</CodeGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Erro de autenticação (Invalid API Key)" icon="key">
    Verifique:

    * API Key correta
    * Ambiente correto
    * Token expirado
  </Accordion>

  <Accordion title="Timeout (Request timeout)" icon="clock">
    Aumente o timeout da SDK.
  </Accordion>
</AccordionGroup>

## Suporte e recursos relacionados

<CardGroup cols={2}>
  <Card title="Suporte por e-mail" color="#ff7e00" icon="envelope" href="mailto:suporte@avanttifinance.com">
    [suporte@avanttifinance.com](mailto:suporte@avanttifinance.com)
  </Card>

  <Card title="Discord da comunidade" color="#ff7e00" icon="discord">
    Tire dúvidas com outros desenvolvedores
  </Card>

  <Card title="GitHub Issues" color="#ff7e00" icon="github">
    Reporte bugs e acompanhe o desenvolvimento
  </Card>

  <Card title="Changelog" color="#ff7e00" icon="clock-rotate-left">
    Acompanhe novidades e mudanças
  </Card>
</CardGroup>

<Info>
  As SDKs da Avantti foram construídas para entregar integrações financeiras rápidas, modernas e previsíveis para qualquer stack.
</Info>

## Filosofia das SDKs

As SDKs da Avantti seguem os mesmos princípios da plataforma: simples, modernas, type-safe, rápidas, consistentes, AI-ready e preparadas para automação.

## Autenticação

## Instalação e inicialização

<Tabs>
  <Tab title="Node.js">
    <CodeGroup>
      ```bash npm theme={null}
      npm install @avantti/sdk
      ```

      ```bash pnpm theme={null}
      pnpm add @avantti/sdk
      ```

      ```bash yarn theme={null}
      yarn add @avantti/sdk
      ```
    </CodeGroup>

    ```ts theme={null}
    import { Avantti } from "@avantti/sdk"

    const avantti = new Avantti({
      apiKey: process.env.AVANTTI_API_KEY
    })
    ```
  </Tab>

  <Tab title="PHP">
    ```bash theme={null}
    composer require avantti/sdk-php
    ```

    ```php theme={null}
    <?php

    use Avantti\Client;

    $avantti = new Client([
      "api_key" => $_ENV["AVANTTI_API_KEY"]
    ]);
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install avantti-python
    ```

    ```python theme={null}
    from avantti import Avantti
    import os

    avantti = Avantti(
        api_key=os.getenv("AVANTTI_API_KEY")
    )
    ```
  </Tab>

  <Tab title="Go">
    ```bash theme={null}
    go get github.com/avanttifinance/avantti-go
    ```

    ```go theme={null}
    package main

    import (
      "github.com/avanttifinance/avantti-go"
    )

    client := avantti.New("sk_test_xxxxx")
    ```
  </Tab>

  <Tab title="Java">
    ```xml theme={null}
    <dependency>
      <groupId>com.avantti</groupId>
      <artifactId>avantti-java</artifactId>
      <version>1.0.0</version>
    </dependency>
    ```

    ```java theme={null}
    Avantti client = new Avantti("sk_test_xxxxx");
    ```
  </Tab>
</Tabs>

## Criar pagamento PIX

<CodeGroup>
  ```ts Node.js theme={null}
  const payment = await avantti.payments.create({
    method: "pix",
    amount: 5000,
    customer: {
      name: "João Silva",
      email: "joao@email.com"
    }
  })
  ```

  ```php PHP theme={null}
  $payment = $avantti->payments->create([
    "method" => "pix",
    "amount" => 5000
  ]);
  ```

  ```python Python theme={null}
  payment = avantti.payments.create({
      "method": "pix",
      "amount": 5000
  })
  ```

  ```go Go theme={null}
  payment, err := client.Payments.Create(
    avantti.PaymentRequest{
      Method: "pix",
      Amount: 5000,
    },
  )
  ```

  ```java Java theme={null}
  Payment payment = client.payments().create(
    new PaymentRequest()
      .method("pix")
      .amount(5000)
  );
  ```
</CodeGroup>

## Outras operações (Node.js)

### Buscar pagamento

```ts theme={null}
const payment = await avantti.payments.get("pay_123456")
```

### Listar pagamentos

```ts theme={null}
const payments = await avantti.payments.list()
```

### Criar cliente

```ts theme={null}
const customer = await avantti.customers.create({
  name: "João Silva",
  email: "joao@email.com"
})
```

### Criar assinatura

```ts theme={null}
const subscription = await avantti.subscriptions.create({
  customerId: "cus_123456",
  plan: "premium"
})
```

## Webhooks (Express.js)

```ts theme={null}
import express from "express"

const app = express()

app.post("/webhooks", async (req, res) => {
  const signature = req.headers["avantti-signature"]

  const event = avantti.webhooks.constructEvent(
    req.body,
    signature
  )

  switch (event.type) {
    case "payment.approved":
      console.log("Pagamento aprovado")
      break
  }

  res.sendStatus(200)
})
```

## Tratamento de erros

```ts theme={null}
try {
  await avantti.payments.create({
    method: "pix",
    amount: 5000
  })
} catch (error) {
  console.error(error.message)
}
```

## Estrutura de recursos

| Recurso         | Descrição   |
| --------------- | ----------- |
| `payments`      | Pagamentos  |
| `customers`     | Clientes    |
| `subscriptions` | Assinaturas |
| `webhooks`      | Eventos     |
| `refunds`       | Reembolsos  |
| `accounts`      | Contas      |
| `balance`       | Saldo       |

## Paginação e filtros

```ts theme={null}
const payments = await avantti.payments.list({
  page: 1,
  limit: 10
})
```

```ts theme={null}
const payments = await avantti.payments.list({
  status: "approved"
})
```

## Idempotência

A API suporta idempotência para evitar cobranças duplicadas.

```ts theme={null}
await avantti.payments.create(
  {
    method: "pix",
    amount: 5000
  },
  {
    idempotencyKey: "payment-123"
  }
)
```

## Retry automático

As SDKs possuem retry automático para falhas temporárias de rede.

## Timeouts, sandbox e produção

<CodeGroup>
  ```ts Timeout theme={null}
  const avantti = new Avantti({
    apiKey: process.env.AVANTTI_API_KEY,
    timeout: 10000
  })
  ```

  ```ts Sandbox theme={null}
  const avantti = new Avantti({
    apiKey: process.env.AVANTTI_API_KEY,
    environment: "sandbox"
  })
  ```

  ```ts Produção theme={null}
  const avantti = new Avantti({
    apiKey: process.env.AVANTTI_API_KEY,
    environment: "production"
  })
  ```
</CodeGroup>

## Logs

Ative logs detalhados para depuração:

```ts theme={null}
const avantti = new Avantti({
  apiKey: process.env.AVANTTI_API_KEY,
  debug: true
})
```

## TypeScript

A SDK Node.js possui suporte completo para TypeScript.

```ts theme={null}
const payment: Payment = await avantti.payments.create({
  method: "pix",
  amount: 5000
})
```

## Segurança

As SDKs utilizam HTTPS obrigatório, criptografia TLS, API Keys seguras, validação de assinatura e rotação de credenciais.

<Tip>
  Nunca exponha chaves privadas, utilize variáveis de ambiente, use sandbox durante o desenvolvimento, implemente retries e faça validação de webhooks.
</Tip>

## Versionamento

As SDKs seguem Semantic Versioning (`1.0.0`):

* **MAJOR** → mudanças incompatíveis
* **MINOR** → novas funcionalidades
* **PATCH** → correções

Acompanhe atualizações e mudanças através do changelog oficial.

## Exemplos reais

<CodeGroup>
  ```ts Criar checkout PIX theme={null}
  const checkout = await avantti.checkouts.create({
    amount: 5000,
    method: "pix",
    successUrl: "https://meusite.com/success"
  })
  ```

  ```ts Reembolso theme={null}
  await avantti.refunds.create({
    paymentId: "pay_123456"
  })
  ```

  ```ts Saldo theme={null}
  const balance = await avantti.balance.get()
  ```
</CodeGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Erro de autenticação (Invalid API Key)" icon="key">
    Verifique:

    * API Key correta
    * Ambiente correto
    * Token expirado
  </Accordion>

  <Accordion title="Timeout (Request timeout)" icon="clock">
    Aumente o timeout da SDK.
  </Accordion>
</AccordionGroup>

## Suporte e recursos relacionados

<CardGroup cols={2}>
  <Card title="Suporte por e-mail" color="#ff7e00" icon="envelope" href="mailto:suporte@avanttifinance.com">
    [suporte@avanttifinance.com](mailto:suporte@avanttifinance.com)
  </Card>

  <Card title="Discord da comunidade" color="#ff7e00" icon="discord">
    Tire dúvidas com outros desenvolvedores
  </Card>

  <Card title="GitHub Issues" color="#ff7e00" icon="github">
    Reporte bugs e acompanhe o desenvolvimento
  </Card>

  <Card title="Changelog" color="#ff7e00" icon="clock-rotate-left">
    Acompanhe novidades e mudanças
  </Card>
</CardGroup>

<Info>
  As SDKs da Avantti foram construídas para entregar integrações financeiras rápidas, modernas e previsíveis para qualquer stack.
</Info>