# Java SDK

The Cheqi Java SDK provides a simple, type-safe way to integrate digital receipt delivery into your Java applications.

## Installation

Add the Cheqi SDK dependency to your `pom.xml`:


```xml
<dependency>
    <groupId>io.cheqi</groupId>
    <artifactId>cheqi-sdk</artifactId>
    <version>1.0.0</version>
</dependency>
```

Or if using Gradle:


```gradle
implementation 'io.cheqi:cheqi-sdk:1.0.0'
```

## Quick Start

### Initialize the SDK


```java
import com.cheqi.sdk.CheqiSDK;
import com.cheqi.sdk.config.Environment;

CheqiSDK sdk = CheqiSDK.builder()
    .apiEndpoint(Environment.PRODUCTION)
    .apiKey(System.getenv("CHEQI_API_KEY"))
    .build();
```

### Send a Receipt


```java
import com.cheqi.sdk.models.*;
import com.cheqi.sdk.receipt.ReceiptResult;

// 1. Identify customer
IdentificationDetails customer = IdentificationDetails.builder()
    .paymentType(PaymentType.CARD_PAYMENT)
    .cardDetails(CardDetails.builder()
        .paymentAccountReference("PAR123456789")
        .cardProvider(CardProvider.VISA)
        .build())
    .customerEmail("customer@example.com")  // Fallback
    .build();

// 2. Create receipt
ReceiptTemplateRequest receipt = ReceiptTemplateRequest.builder()
    .documentNumber("INV-2024-001")
    .issueDate(Instant.now())
    .currency("EUR")
    .totalAmount(new BigDecimal("121.00"))
    .totalTaxAmount(new BigDecimal("21.00"))
    .addProduct(Product.builder()
        .name("Coffee")
        .quantity(2.0)
        .unitCode(UnitCode.ONE)
        .unitPrice("5.00")
        .subtotal("10.00")
        .total("12.10")
        .addTax(21.0, "VAT", "2.10")
        .build())
    .build();

// 3. Send receipt
ReceiptResult result = sdk.getReceiptService()
    .processCompleteReceipt(customer, receipt);

// 4. Check result
if (result.isSuccess()) {
    System.out.println("✅ Receipt delivered to " + result.getReceiptCount() + " devices");
} else if (result.isCustomerNotFound()) {
    System.out.println("⚠️ Customer not found");
} else {
    System.out.println("❌ Failed: " + result.getMessage());
}
```

## Configuration

### Environment Options


```java
// Production
.apiEndpoint(Environment.PRODUCTION)

// Sandbox (for testing)
.apiEndpoint(Environment.SANDBOX)

// Custom endpoint
.apiEndpoint("https://custom-api.cheqi.io")
```

### Authentication

The SDK requires an API key for authentication:


```java
// From environment variable (recommended)
.apiKey(System.getenv("CHEQI_API_KEY"))

// Direct (not recommended for production)
.apiKey("your-api-key-here")
```

## Customer Identification

### Card Payment


```java
IdentificationDetails customer = IdentificationDetails.builder()
    .paymentType(PaymentType.CARD_PAYMENT)
    .cardDetails(CardDetails.builder()
        .paymentAccountReference("PAR123456789")
        .cardProvider(CardProvider.VISA)
        .build())
    .build();
```

### IBAN Payment


```java
IdentificationDetails customer = IdentificationDetails.builder()
    .paymentType(PaymentType.IBAN_PAYMENT)
    .iban("NL91ABNA0417164300")
    .build();
```

### Email Fallback


```java
IdentificationDetails customer = IdentificationDetails.builder()
    .paymentType(PaymentType.CARD_PAYMENT)
    .cardDetails(CardDetails.builder()
        .paymentAccountReference("PAR123456789")
        .cardProvider(CardProvider.VISA)
        .build())
    .customerEmail("customer@example.com")  // Fallback if not found
    .build();
```

## Building Receipts

### Basic Receipt


```java
ReceiptTemplateRequest receipt = ReceiptTemplateRequest.builder()
    .documentNumber("INV-2024-001")
    .issueDate(Instant.now())
    .currency("EUR")
    .totalAmount(new BigDecimal("121.00"))
    .totalTaxAmount(new BigDecimal("21.00"))
    .addProduct(/* ... */)
    .addTax(/* ... */)
    .build();
```

### Adding Products


```java
Product product = Product.builder()
    .name("Product Name")
    .quantity(1.0)
    .unitCode(UnitCode.ONE)
    .unitPrice("10.00")
    .subtotal("10.00")
    .total("12.10")
    .sku("SKU-123")
    .brand("Brand Name")
    .addTax(21.0, "VAT", "2.10")
    .build();
```

### Adding Taxes


```java
Tax tax = Tax.builder()
    .rate(21.0)
    .type("VAT")
    .taxableAmount("10.00")
    .amount("2.10")
    .label("VAT 21%")
    .build();
```

## Error Handling


```java
try {
    ReceiptResult result = sdk.getReceiptService()
        .processCompleteReceipt(customer, receipt);
    
    if (result.isSuccess()) {
        // Handle success
    } else if (result.isCustomerNotFound()) {
        // Prompt for email
    }
} catch (CheqiSDKException e) {
    logger.error("Failed to send receipt", e);
    // Handle error
}
```

## Spring Boot Integration

### Configuration Class


```java
@Configuration
public class CheqiConfig {
    
    @Value("${cheqi.api.key}")
    private String apiKey;
    
    @Value("${cheqi.api.endpoint}")
    private String apiEndpoint;
    
    @Bean
    public CheqiSDK cheqiSDK() {
        return CheqiSDK.builder()
            .apiEndpoint(apiEndpoint)
            .apiKey(apiKey)
            .build();
    }
}
```

### Service Class


```java
@Service
public class ReceiptService {
    
    private final CheqiSDK cheqiSDK;
    
    public ReceiptService(CheqiSDK cheqiSDK) {
        this.cheqiSDK = cheqiSDK;
    }
    
    public void sendReceipt(IdentificationDetails customer, ReceiptTemplateRequest receipt) {
        ReceiptResult result = cheqiSDK.getReceiptService()
            .processCompleteReceipt(customer, receipt);
        
        if (!result.isSuccess()) {
            throw new RuntimeException("Failed to send receipt: " + result.getMessage());
        }
    }
}
```

## Requirements

- Java 11 or higher
- Maven 3.6+ or Gradle 6.0+


## Next Steps

- [Receipt Flow Overview](/receipts/overview) - Understand the complete receipt flow
- [Authentication](/authentication/overview) - API Keys and OAuth 2.0
- [.NET SDK](/sdk/dotnet) - Alternative SDK for .NET applications