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

# Java

> SDK oficial para Java — aceite pagamentos em segundos com uma integração simples

<Card title="Alpa Java SDK" icon="java" href="https://github.com/anthonymengottii/alpa-java-sdk">
  SDK oficial da Alpa para Java. Compatível com Java 17+ e Spring Boot.
</Card>

## Instalação

### Requisitos

Certifique-se de ter instalado:

* **Java**: JDK 17 ou superior
* **Maven**: Para gerenciar dependências e construir o projeto

### Instalando Maven

**Linux:**

```bash theme={null}
sudo apt install maven
```

**Windows (usando Chocolatey):**

```bash theme={null}
choco install maven -y
```

### Adicionando a dependência

<Note>
  Este SDK ainda não está publicado no Maven Central. Clone e instale localmente:
</Note>

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

Após o `mvn install`, adicione ao seu `pom.xml`:

```xml theme={null}
<dependency>
    <groupId>com.alpa</groupId>
    <artifactId>alpa-java</artifactId>
    <version>2.0.0</version>
</dependency>
```

E a dependência de serialização JSON:

```xml theme={null}
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.17.1</version>
</dependency>
```

## Uso Rápido

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

// Inicialize o SDK com sua API Key
AlpaClient alpa = new AlpaClient(System.getenv("ALPA_API_KEY"));
```

## Criando um Link de Pagamento

```java theme={null}
import com.alpa.AlpaClient;
import com.fasterxml.jackson.databind.JsonNode;
import java.util.Map;

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

JsonNode link = alpa.paymentLinks.create(Map.of(
    "title",       "Produto Premium",
    "amountCents", 9900,
    "description", "Acesso vitalício"
));

// A resposta traz o slug; monte a URL do checkout a partir dele:
String slug = link.path("slug").asText();
System.out.println("https://checkout.usealpa.com/pay/" + slug);
```

## Resposta

```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",
  "updatedAt": "2026-04-08T00:00:00.000Z"
}
```

## Criando uma Transação PIX

```java theme={null}
JsonNode tx = alpa.transactions.create(Map.of(
    "product",        "Curso Java",
    "paymentMethod",  "PIX",
    "amountCents",    19900,
    "clientName",     "João Silva",
    "clientEmail",    "joao@example.com",
    "clientDocument", "12345678900"
));

System.out.println(tx.path("pixCopiaECola").asText());
```

## Validando um Cupom

```java theme={null}
JsonNode result = alpa.coupons.validate("DESCONTO10", 19900);

if (result.path("valid").asBoolean()) {
    System.out.println("Desconto: " + result.path("discountCents").asInt());
    System.out.println("Total: " + result.path("finalAmountCents").asInt());
}
```

## Validação de Webhooks

```java theme={null}
// Spring Boot
@PostMapping("/webhook")
public ResponseEntity<?> webhook(
        @RequestBody byte[] body,
        @RequestHeader("x-webhook-signature") String signature
) throws Exception {
    if (!alpa.verifyWebhookSignature(new String(body), signature, System.getenv("ALPA_WEBHOOK_SECRET"))) {
        return ResponseEntity.status(401).body(Map.of("error", "Assinatura inválida"));
    }
    return ResponseEntity.ok(Map.of("received", true));
}
```

## Tratamento de Erros

```java theme={null}
import com.alpa.utils.AlpaException;

try {
    JsonNode tx = alpa.transactions.create(Map.of(...));
} catch (AlpaException e) {
    System.err.println("Erro " + e.getStatusCode() + ": " + e.getMessage());
} catch (IOException | InterruptedException e) {
    System.err.println("Erro de rede: " + e.getMessage());
}
```