# .NET SDK

The current .NET SDK supports:

- receipt processing
- credit note processing
- matching
- verification
- company provisioning
- store management


## Installation

```bash
dotnet add package cheqi-sdk --version 1.2.0
```

## Initialization

Builder-based initialization:

```csharp
var sdk = CheqiSdk.Builder()
    .ApiEndpoint(Environment.Sandbox)
    .ApiKey(Environment.GetEnvironmentVariable("CHEQI_API_KEY")!)
    .Build();
```

Options-based initialization:

```csharp
using var sdk = CheqiSdk.Create(new CheqiSdkOptions
{
    Environment = CheqiApiEnvironment.Sandbox,
    ApiKey = Environment.GetEnvironmentVariable("CHEQI_API_KEY")
});
```

## Receipt flow

```csharp
var customer = IdentificationDetails.ForCard(
    PaymentType.CARD_PAYMENT,
    new CardDetails(CardProvider.VISA, paymentAccountReference: "PAR123456789"),
    recipientEmail: "customer@example.com"
);

var receiptRequest = ReceiptTemplateRequest.Builder()
    .DocumentNumber("INV-2026-001")
    .IssueDate(DateTimeOffset.UtcNow)
    .Currency("EUR")
    .ReceiptSubtotal(10.00m)
    .TotalBeforeTax(10.00m)
    .TotalTaxAmount(2.10m)
    .TotalAmount(12.10m)
    .AddProduct(Product.Builder()
        .Name("Coffee")
        .Identifier("SKU-COFFEE-001")
        .Quantity(2)
        .BaseQuantity(1)
        .UnitCode(UnitCode.ONE)
        .UnitPrice(5.00m)
        .Subtotal(10.00m)
        .Total(12.10m)
        .AddTax(21.0, "VAT", 10.00m, 2.10m)
        .Build())
    .AddTax(Tax.Builder()
        .Rate(21.0)
        .Type("VAT")
        .TaxableAmount(10.00m)
        .Amount(2.10m)
        .Label("VAT 21%")
        .Build())
    .BuyerCountryCode(matchResult.BuyerCountryCode)
    .BuyerType(matchResult.BuyerType)
    .TaxesApplied(true)
    .Build();

var result = await sdk.ReceiptService.ProcessCompleteReceiptAsync(
    customer,
    receiptRequest
);
```

OAuth overload:

```csharp
var result = await sdk.ReceiptService.ProcessCompleteReceiptAsync(
    customer,
    receiptRequest,
    accessToken
);
```

## Matching flow

```csharp
var matchResult = await sdk.MatchingService.MatchCustomerAsync(customer);
```

The returned recipients can include `acceptedFormats`, which affects whether the encrypted envelope contains Cheqi JSON, UBL PurchaseReceipt XML, UBL Invoice XML, or a subset. `BuyerCountryCode`, `BuyerType`, and `TaxesApplied` are mandatory on the receipt template request.

## Verification flow

```csharp
var cheqiHash = sdk.VerificationService.CalculateCheqiReceiptHash(cheqiReceiptJson);
var ublHash = sdk.VerificationService.CalculateUblHash(ublPurchaseReceiptXml);
```

## Credit note flow

Use `sdk.CreditNoteService.ProcessCompleteCreditNoteAsync(...)` for returns and refunds tied to an existing receipt. That flow requires `cheqiReceiptId` in the identification details.

## Company and store flows

The SDK also exposes:

- `sdk.CompanyService`
- `sdk.StoreService`


Use those services for provisioning and branch/store management flows.