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

# SDKs

> Bibliotecas oficiais para integração com a API da Alpa

## O que são os SDKs da Alpa?

Os SDKs (Software Development Kits) da Alpa são bibliotecas oficiais que simplificam a comunicação com nossa API. Eles oferecem uma interface amigável e específica para cada linguagem, permitindo que você integre rapidamente PIX, cartão e boleto ao seu sistema.

<Card title="Benefícios de usar nossos SDKs" horizontal>
  * **Integração simplificada**: Funções prontas para todos os endpoints da API
  * **Tipagem forte**: Interfaces e types completos em linguagens com suporte a tipos
  * **Tratamento de erros**: Gerenciamento automático dos casos de erro mais comuns
  * **Validação de webhooks**: Utilitários prontos para verificar assinaturas HMAC-SHA256
  * **Menor curva de aprendizado**: Sem necessidade de conhecer todos os detalhes HTTP da API
</Card>

## SDKs Disponíveis

Oferecemos SDKs oficiais para as principais linguagens de backend. Escolha o que melhor se adapta à sua stack:

<CardGroup cols={2}>
  <Card title="Node.js / TypeScript" icon="node-js" color="#68A063" href="./sdk-nodejs">
    SDK oficial para Node.js 18+, compatível com TypeScript, ESM e edge runtimes.
  </Card>

  <Card title="Python" icon="python" color="#366B98" href="./sdk-python">
    SDK oficial para Python 3.8+, com type hints e suporte a frameworks como Flask e Django.
  </Card>

  <Card title="PHP" icon="php" color="#777BB3" href="./sdk-php">
    SDK oficial para PHP 8.1+, disponível via Composer e sem dependências externas além de cURL.
  </Card>

  <Card title="Java" icon="java" color="#E76F00" href="./sdk-java">
    SDK oficial para Java 17+, compatível com Spring Boot e qualquer projeto Maven/Gradle.
  </Card>
</CardGroup>

## Instalação Rápida

<Note>
  Os SDKs estão disponíveis no GitHub e ainda não foram publicados nos registros públicos de pacotes (npm, PyPI, Packagist, Maven Central). Consulte a página de cada SDK para instruções de instalação via GitHub.
</Note>

<CodeGroup>
  ```bash Node.js theme={null}
  npm install github:anthonymengottii/alpa-nodejs-sdk
  ```

  ```bash Python theme={null}
  pip install git+https://github.com/anthonymengottii/alpa-python-sdk.git
  ```

  ```bash PHP theme={null}
  composer config repositories.alpa vcs https://github.com/anthonymengottii/alpa-php-sdk
  composer require alpa/alpa-php:dev-main
  ```

  ```bash Java theme={null}
  git clone https://github.com/anthonymengottii/alpa-java-sdk
  cd alpa-java-sdk && mvn install
  ```
</CodeGroup>

## Primeiros Passos

Todos os SDKs seguem o mesmo padrão: instancie o cliente com sua API Key e acesse os recursos diretamente.

<CodeGroup>
  ```typescript Node.js theme={null}
  import AlpaClient from '@alpa/alpa-js';

  const alpa = new AlpaClient({ apiKey: process.env.ALPA_API_KEY });

  const link = await alpa.paymentLinks.create({
    title: 'Produto Premium',
    amountCents: 9900,
  });
  console.log('Checkout:', alpa.paymentLinks.getCheckoutUrl(link.slug));
  ```

  ```python Python theme={null}
  from alpa import AlpaClient

  alpa = AlpaClient(api_key=os.getenv('ALPA_API_KEY'))

  link = alpa.payment_links.create({
      'title': 'Produto Premium',
      'amountCents': 9900,
  })
  print('Checkout:', alpa.payment_links.get_checkout_url(link['slug']))
  ```

  ```php PHP theme={null}
  use Alpa\AlpaClient;

  $alpa = new AlpaClient($_ENV['ALPA_API_KEY']);

  $link = $alpa->paymentLinks->create([
      'title'       => 'Produto Premium',
      'amountCents' => 9900,
  ]);
  echo 'Checkout: ' . $alpa->paymentLinks->getCheckoutUrl($link['slug']);
  ```

  ```java Java theme={null}
  import com.alpa.AlpaClient;

  var alpa = new AlpaClient(System.getenv("ALPA_API_KEY"));

  var link = alpa.paymentLinks.create("Produto Premium", 9900, java.util.Map.of());
  System.out.println("Checkout: https://checkout.usealpa.com/pay/" + link.path("slug").asText());
  ```
</CodeGroup>

## Perguntas Frequentes

<AccordionGroup>
  <Accordion title="Como obtenho minha API Key?">
    Acesse o **Dashboard → Configurações → Credenciais de API** e gere uma nova chave. Nunca exponha sua API Key no código-fonte — use variáveis de ambiente e adicione `.env` ao `.gitignore`.
  </Accordion>

  <Accordion title="Os SDKs funcionam em ambiente de testes?">
    Sim. Todos os SDKs aceitam um parâmetro `baseUrl` opcional no construtor, permitindo apontar para qualquer ambiente. Use sua chave de API do ambiente desejado (desenvolvimento ou produção).
  </Accordion>

  <Accordion title="Como validar webhooks com os SDKs?">
    Todos os SDKs incluem um método `verifyWebhookSignature(payload, signature, secret)` que verifica a assinatura HMAC-SHA256 automaticamente. Consulte a página do SDK da sua linguagem para o exemplo completo.
  </Accordion>

  <Accordion title="O que fazer se encontrar um bug em um SDK?">
    Abra uma issue no repositório GitHub do SDK específico. Nossa equipe está sempre atenta para corrigir bugs e melhorar as bibliotecas. Você também pode entrar em contato pelo e-mail <Icon icon="envelope" type="solid" /> [suporte@usealpa.com](mailto:suporte@usealpa.com).
  </Accordion>

  <Accordion title="Falta um SDK para a linguagem que eu uso. O que fazer?">
    Entre em contato pelo e-mail <Icon icon="envelope" type="solid" /> [suporte@usealpa.com](mailto:suporte@usealpa.com) informando qual linguagem você precisa. Nossa equipe avaliará a demanda para incluir na roadmap.
  </Accordion>
</AccordionGroup>

## Recursos Adicionais

<CardGroup cols={2}>
  <Card title="Autenticação" icon="key" href="../pages/authentication">
    Como gerar e usar suas credenciais de API.
  </Card>

  <Card title="Webhooks" icon="webhook" href="../pages/webhooks/reference">
    Configure notificações automáticas para eventos de pagamento.
  </Card>

  <Card title="Referência da API" icon="code" href="../pages/introduction">
    Documentação completa de todos os endpoints.
  </Card>

  <Card title="Changelog" icon="clock-rotate-left" href="../pages/changelog">
    Histórico de versões e atualizações.
  </Card>
</CardGroup>

<Card title="Precisa de ajuda com a integração?" icon="headset">
  Nossa equipe está disponível para ajudar. Entre em contato: <Icon icon="envelope" type="solid" /> [suporte@usealpa.com](mailto:suporte@usealpa.com)
</Card>