# Python SDK

The Python SDK is present in `../sdk/python/cheqi-sdk` and supports:

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


## Installation

```bash
pip install cheqi-sdk
```

## Initialization

```python
from cheqi import CheqiSDK, Environment

sdk = CheqiSDK(
    environment=Environment.SANDBOX,
    api_key="sk_test_...",
)
```

## Receipt flow

```python
from datetime import datetime, timezone
from decimal import Decimal

from cheqi.models import (
    CardDetails,
    CardProvider,
    IdentificationDetails,
    PaymentType,
    Product,
    ReceiptTemplateRequest,
    Tax,
    UnitCode,
)

customer = IdentificationDetails(
    payment_type=PaymentType.CARD_PAYMENT,
    card_details=CardDetails(
        payment_account_reference="PAR123456789",
        card_provider=CardProvider.VISA,
    ),
    recipient_email="customer@example.com",
)

receipt_request = ReceiptTemplateRequest(
    document_number="INV-2026-001",
    issue_date=datetime.now(tz=timezone.utc),
    currency="EUR",
    receipt_subtotal=Decimal("10.00"),
    total_before_tax=Decimal("10.00"),
    total_tax_amount=Decimal("2.10"),
    total_amount=Decimal("12.10"),
    products=[
        Product(
            name="Coffee",
            identifier="SKU-COFFEE-001",
            quantity=2.0,
            base_quantity=1.0,
            unit_code=UnitCode.ONE,
            unit_price=Decimal("5.00"),
            subtotal=Decimal("10.00"),
            total=Decimal("12.10"),
            taxes=[
                Tax(
                    rate=21.0,
                    type="VAT",
                    taxable_amount=Decimal("10.00"),
                    amount=Decimal("2.10"),
                )
            ],
        )
    ],
    taxes=[
        Tax(
            rate=21.0,
            type="VAT",
            taxable_amount=Decimal("10.00"),
            amount=Decimal("2.10"),
            label="VAT 21%",
        )
    ],
    buyer_country_code=match_response.buyer_country_code,
    recipient_entity_type=match_response.recipient_entity_type,
    taxes_applied=True,
)

result = sdk.receipt_service.process_complete_receipt(
    identification_details=customer,
    receipt_request=receipt_request,
)
```

With an access token:

```python
result = sdk.receipt_service.process_complete_receipt(
    identification_details=customer,
    receipt_request=receipt_request,
    access_token=access_token,
)
```

## Matching flow

```python
match_response = sdk.matching_service.match_customer(customer)
```

Use `match_response.buyer_country_code` and `match_response.recipient_entity_type` when building the receipt request. `buyer_country_code`, `recipient_entity_type`, and `taxes_applied` are mandatory on the receipt template request.

## Verification flow

```python
json_hash = sdk.verification_service.canonicalize_and_hash_json(cheqi_receipt_json)
xml_hash = sdk.verification_service.canonicalize_and_hash_xml(ubl_xml)
```

## Credit note flow

Use `sdk.credit_note_service.process_complete_credit_note(...)` for return and refund flows. This is the Python equivalent of the Java and .NET credit note services.

## Company and store flows

The SDK exposes:

- `sdk.company_service`
- `sdk.store_service`


Use those services for provisioning and store management operations.