# .NET SDK

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

## Installation

Install the Cheqi SDK via NuGet:


```bash
dotnet add package Cheqi.Sdk
```

Or via Package Manager Console:


```powershell
Install-Package Cheqi.Sdk
```

## Quick Start

### Initialize the SDK


```csharp
using Cheqi.Sdk;
using Cheqi.Sdk.Config;

var sdk = CheqiSdk.Builder()
    .ApiEndpoint(Environment.Production)
    .ApiKey(System.Environment.GetEnvironmentVariable("CHEQI_API_KEY"))
    .Build();
```

### Send a Receipt


```csharp
using Cheqi.Sdk.Models;

// 1. Identify customer
var customer = IdentificationDetails.Builder()
    .PaymentType(PaymentType.CARD_PAYMENT)
    .CardDetails(CardDetails.Builder()
        .Par("PAR123456789")
        .CardProvider(CardProvider.VISA)
        .Build())
    .RecipientEmail("customer@example.com")  // Fallback
    .Build();

// 2. Create receipt
var receipt = ReceiptTemplateRequest.Builder()
    .DocumentNumber("INV-2024-001")
    .IssueDate(DateTimeOffset.UtcNow)
    .Currency("EUR")
    .InvoiceSubtotal(10.00m)
    .TotalBeforeTax(10.00m)
    .TotalTaxAmount(2.10m)
    .TotalAmount(12.10m)
    .AddProduct(Product.Builder()
        .Name("Coffee")
        .Quantity(2)
        .BaseQuantity(1.0)
        .UnitCode(UnitCode.ONE)
        .UnitPrice(5.00m)
        .Subtotal(10.00m)
        .Total(12.10m)
        .AddTax(21.0, "VAT", 2.10m)
        .Build())
    .Build();

// 3. Send receipt
var result = await sdk.ReceiptService.ProcessCompleteReceiptAsync(customer, receipt);

// 4. Check result
if (result.IsSuccess)
{
    Console.WriteLine($"✅ Receipt delivered to {result.ReceiptCount} devices");
}
else if (!result.RecipientsFound)
{
    Console.WriteLine("⚠️ Customer not found");
}
else
{
    Console.WriteLine($"❌ Failed: {result.ErrorMessage}");
}
```

## Configuration

### Environment Options


```csharp
// 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:


```csharp
// From environment variable (recommended)
.ApiKey(System.Environment.GetEnvironmentVariable("CHEQI_API_KEY"))

// From configuration (appsettings.json)
.ApiKey(configuration["Cheqi:ApiKey"])

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

## Customer Identification

### Card Payment


```csharp
var customer = IdentificationDetails.Builder()
    .PaymentType(PaymentType.CARD_PAYMENT)
    .CardDetails(CardDetails.Builder()
        .Par("PAR123456789")
        .CardProvider(CardProvider.VISA)
        .Build())
    .Build();
```

### IBAN Payment


```csharp
var customer = IdentificationDetails.Builder()
    .PaymentType(PaymentType.IBAN_PAYMENT)
    .PaymentAccountDetails(PaymentAccountDetails.Builder()
        .Iban("NL91ABNA0417164300")
        .Build())
    .Build();
```

### Email Fallback


```csharp
var customer = IdentificationDetails.Builder()
    .PaymentType(PaymentType.CARD_PAYMENT)
    .CardDetails(CardDetails.Builder()
        .Par("PAR123456789")
        .CardProvider(CardProvider.VISA)
        .Build())
    .RecipientEmail("customer@example.com")  // Fallback if not found
    .Build();
```

## Building Receipts

### Basic Receipt


```csharp
var receipt = ReceiptTemplateRequest.Builder()
    .DocumentNumber("INV-2024-001")
    .IssueDate(DateTimeOffset.UtcNow)
    .Currency("EUR")
    .InvoiceSubtotal(10.00m)
    .TotalBeforeTax(10.00m)
    .TotalTaxAmount(2.10m)
    .TotalAmount(12.10m)
    .AddProduct(/* ... */)
    .AddTax(/* ... */)
    .Build();
```

### Adding Products


```csharp
var product = Product.Builder()
    .Name("Product Name")
    .Quantity(1)
    .BaseQuantity(1.0)
    .UnitCode(UnitCode.ONE)
    .UnitPrice(10.00m)
    .Subtotal(10.00m)
    .Total(12.10m)
    .Identifier("SKU-123")
    .Brand("Brand Name")
    .AddTax(21.0, "VAT", 2.10m)
    .Build();
```

### Adding Taxes


```csharp
var tax = Tax.Builder()
    .Rate(21.0)
    .Type("VAT")
    .TaxableAmount(10.00m)
    .Amount(2.10m)
    .Label("VAT 21%")
    .Build();
```

## Error Handling


```csharp
try
{
    var result = await sdk.ReceiptService.ProcessCompleteReceiptAsync(customer, receipt);
    
    if (result.IsSuccess)
    {
        // Handle success
    }
    else if (!result.RecipientsFound)
    {
        // Prompt for email
    }
}
catch (CheqiSdkException ex)
{
    _logger.LogError(ex, "Failed to send receipt");
    // Handle error
}
```

## ASP.NET Core Integration

### Startup Configuration


```csharp
// Program.cs or Startup.cs
services.AddSingleton<ICheqiSdk>(sp =>
{
    var configuration = sp.GetRequiredService<IConfiguration>();
    
    return CheqiSdk.Builder()
        .ApiEndpoint(configuration["Cheqi:ApiEndpoint"])
        .ApiKey(configuration["Cheqi:ApiKey"])
        .Build();
});
```

### appsettings.json


```json
{
  "Cheqi": {
    "ApiEndpoint": "https://api.cheqi.io",
    "ApiKey": "your-api-key-here"
  }
}
```

### Service Class


```csharp
public class ReceiptService
{
    private readonly ICheqiSdk _cheqiSdk;
    private readonly ILogger<ReceiptService> _logger;
    
    public ReceiptService(ICheqiSdk cheqiSdk, ILogger<ReceiptService> logger)
    {
        _cheqiSdk = cheqiSdk;
        _logger = logger;
    }
    
    public async Task SendReceiptAsync(IdentificationDetails customer, ReceiptTemplateRequest receipt)
    {
        var result = await _cheqiSdk.ReceiptService.ProcessCompleteReceiptAsync(customer, receipt);
        
        if (!result.IsSuccess)
        {
            throw new InvalidOperationException($"Failed to send receipt: {result.ErrorMessage}");
        }
    }
}
```

## Async/Await Pattern

All SDK methods are async and return `Task<T>`:


```csharp
// Use await
var result = await sdk.ReceiptService.ProcessCompleteReceiptAsync(customer, receipt);

// Or use .Result (not recommended - can cause deadlocks)
var result = sdk.ReceiptService.ProcessCompleteReceiptAsync(customer, receipt).Result;
```

## Requirements

- .NET 6.0 or higher
- C# 10.0 or higher


## Next Steps

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