> ## 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.

# Primeira requisição

> Comece a usar a API da Alpa em minutos

<Info>
  Este guia rápido te ajudará a fazer sua primeira requisição à API da Alpa em poucos minutos.
</Info>

## Pré-requisitos

Antes de começar, você precisa de:

* Uma conta na Alpa
* Uma chave de API (criada no Dashboard)
* Conhecimento básico de HTTP e JSON

<Card title="Novo na Alpa?" icon="user-plus" horizontal>
  Se você ainda não tem uma conta, acesse o <a href="https://app.usealpa.com" target="_blank">Dashboard</a> e crie sua conta gratuitamente.
</Card>

## Passo 1: Obter sua Chave de API

<Steps>
  <Step title="Acesse o Dashboard">
    Faça login em <a href="https://app.usealpa.com" target="_blank">app.usealpa.com</a>.
  </Step>

  <Step title="Crie uma Chave de API">
    Navegue até **Configurações → Credenciais de API** e clique em **"Criar Nova API Key"**.
  </Step>

  <Step title="Copie sua Chave">
    Copie a chave gerada e armazene-a em um local seguro. **Ela não será exibida novamente.**
  </Step>
</Steps>

<Warning>
  Sua chave de API é uma credencial sensível. Nunca a compartilhe publicamente nem a commite em repositórios de código.
</Warning>

<Card title="Desenvolvimento x Produção" horizontal>
  O ambiente é determinado automaticamente pela **chave utilizada**:

  * **Chave de Desenvolvimento** → transações simuladas, ideal para testes
  * **Chave de Produção** → transações reais, requer conta verificada (KYC)
</Card>

Para mais detalhes, consulte a <a href="./authentication">documentação de Chaves de API</a>.

## Passo 2: Fazer sua Primeira Requisição

Vamos criar seu primeiro link de pagamento:

```bash theme={null}
curl --request POST \
  --url https://alpa-sistema-api.onrender.com/api/v1/payment-links \
  --header 'Authorization: Bearer SUA_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Produto Premium",
    "amountCents": 9900,
    "description": "Acesso vitalício"
  }'
```

### Resposta de sucesso

```json theme={null}
{
  "id": "lnk_abc123",
  "title": "Produto Premium",
  "description": "Acesso vitalício",
  "amount": 9900,
  "currency": "BRL",
  "status": "ACTIVE",
  "slug": "abc123",
  "createdAt": "2026-04-08T00:00:00.000Z"
}
```

<Note>
  A resposta traz o `slug`. Monte a URL pública do checkout assim: `https://checkout.usealpa.com/pay/{slug}` (ex.: `https://checkout.usealpa.com/pay/abc123`).
</Note>

<Card title="Visualize no Dashboard" horizontal>
  Após criar seu link, acesse o <a href="https://app.usealpa.com" target="_blank">Dashboard</a> e navegue até **Links de Pagamento** para ver todos os detalhes, status e histórico de pagamentos.
</Card>

## Passo 3: Criar uma Transação PIX

```bash theme={null}
curl --request POST \
  --url https://alpa-sistema-api.onrender.com/api/v1/transactions \
  --header 'Authorization: Bearer SUA_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "product": "Curso Online",
    "paymentMethod": "PIX",
    "amountCents": 9900,
    "clientName": "João Silva",
    "clientEmail": "joao@example.com",
    "clientDocument": "12345678900"
  }'
```

### Resposta de sucesso

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING",
  "paymentMethod": "PIX",
  "amountCents": 9900,
  "pixCopiaECola": "00020101021226940014br.gov.bcb.pix...",
  "pixExpiresAt": "2026-04-09T00:00:00.000Z",
  "createdAt": "2026-04-08T00:00:00.000Z"
}
```

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Chaves de API" icon="key" href="./authentication">
    Entenda permissões e boas práticas de segurança.
  </Card>

  <Card title="Links de Pagamento" icon="link" href="../payment-links/create">
    Todas as opções disponíveis para criar cobranças.
  </Card>

  <Card title="Webhooks" icon="bell" href="../webhooks/reference">
    Receba notificações em tempo real sobre eventos.
  </Card>

  <Card title="SDKs Oficiais" icon="boxes-stacked" href="../sdks">
    Use nossas bibliotecas para integrar mais rápido.
  </Card>
</CardGroup>

## Precisa de Ajuda?

<Card title="Suporte" horizontal>
  Nossa equipe está sempre à disposição. Entre em contato: <Icon icon="envelope" type="solid" /> [suporte@usealpa.com](mailto:suporte@usealpa.com)
</Card>