kra-etims-sdk 0.1.0__tar.gz → 0.1.1__tar.gz

{kra_etims_sdk-0.1.0 → kra_etims_sdk-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kra-etims-sdk
-Version: 0.1.0
+Version: 0.1.1
 Summary: Python SDK for KRA eTIMS OSCU API
 Author: Emmanuel Bartile
 License: MIT
@@ -41,7 +41,7 @@ Dynamic: license-file
 
 A production-ready **Python SDK** for integrating with the Kenya Revenue Authority (KRA) **eTIMS OSCU** (Online Sales Control Unit) API. Built to match the official Postman collection specifications with strict header compliance, token management, and comprehensive Pydantic validation.
 
-> ⚠️ **Critical Note**: This SDK implements the **new OSCU specification** (KRA-hosted), *not* the legacy eTIMS API. OSCU requires device registration, headers, and `cmcKey` lifecycle management.
+> ⚠️ **Critical Note**: This SDK implements the **new OSCU specification** (KRA-hosted), *not* the VSCU eTIMS API. OSCU requires device registration, headers, and `cmcKey` lifecycle management.
 
 ## Author
 **Bartile Emmanuel**  
@@ -73,15 +73,15 @@ A production-ready **Python SDK** for integrating with the Kenya Revenue Authori
 
 ## Introduction to eTIMS OSCU
 
-KRA's **Electronic Tax Invoice Management System (eTIMS)** uses **OSCU** (Online Sales Control Unit) – a KRA-hosted software module that validates and signs tax invoices in real-time before issuance. Unlike legacy systems, OSCU requires:
+KRA's **Electronic Tax Invoice Management System (eTIMS)** uses **OSCU** (Online Sales Control Unit) – a KRA-hosted software module that validates and signs tax invoices in real-time before issuance. Unlike VSCU, OSCU requires:
 
 - Pre-registered device serial numbers (`dvcSrlNo`)
 - Communication key (`cmcKey`) lifecycle management
 - Strict payload schema compliance per KRA specifications
 
-### OSCU vs Legacy eTIMS
+### OSCU vs VSCU eTIMS
 
-| Feature | OSCU (This SDK) | Legacy eTIMS |
+| Feature | OSCU (This SDK) | VSCU eTIMS |
 |---------|-----------------|--------------|
 | **Hosting** | KRA-hosted (cloud) | Self-hosted (on-premise) |
 | **Device Registration** | Mandatory pre-registration | Not required |
@@ -198,7 +198,7 @@ Before integration, you **MUST** complete these prerequisites:
 ### 2. Communication Key Lifecycle
 ```python
 # 1. Initialize FIRST (returns cmcKey)
-response = etims.initialize({
+response = etims.select_init_osdc_info({
     "tin": config.oscu["tin"],
     "bhfId": config.oscu["bhf_id"],
     "dvcSrlNo": "dvcv1130",  # KRA-approved serial
@@ -316,7 +316,7 @@ config = KraEtimsConfig(
     
     endpoints={
         # INITIALIZATION (ONLY endpoint without tin/bhfId/cmcKey headers)
-        "initialize": "/initialize",
+        "selectInitOsdcInfo": "/selectInitOsdcInfo",
         
         # DATA MANAGEMENT
         "selectCodeList": "/selectCodeList",
@@ -386,12 +386,11 @@ except AuthenticationException as e:
 try:
     # ⚠️ MUST use KRA-approved device serial (NOT dynamic!)
     # Common sandbox test value (if pre-provisioned by KRA):
-    device_serial = "dvcv1130"  # REPLACE with your approved serial
     
-    response = etims.initialize({
+    response = etims.select_init_info({
         "tin": config.oscu["tin"],
         "bhfId": config.oscu["bhf_id"],
-        "dvcSrlNo": device_serial.strip(),
+        "dvcSrlNo": config.oscu["device_serial"],
     })
 
     # Extract cmcKey (sandbox returns at root level)
@@ -506,7 +505,7 @@ except ApiException as e:
 
 | Category | Purpose | Endpoints |
 |----------|---------|-----------|
-| **Initialization** | Device registration & cmcKey acquisition | `initialize` |
+| **Initialization** | Device registration & cmcKey acquisition | `select_init_info` |
 | **Data Management** | Retrieve standard codes & master data | `select_code_list`, `select_item_cls_list`, `select_bhf_list`, `select_taxpayer_info`, `select_customer_list`, `select_notice_list` |
 | **Branch Management** | Manage branch offices & users | `branch_insurance_info`, `branch_user_account`, `branch_send_customer_info` |
 | **Item Management** | Item master data | `save_item`, `item_info` |

{kra_etims_sdk-0.1.0 → kra_etims_sdk-0.1.1}/README.md

@@ -18,7 +18,7 @@
 
 A production-ready **Python SDK** for integrating with the Kenya Revenue Authority (KRA) **eTIMS OSCU** (Online Sales Control Unit) API. Built to match the official Postman collection specifications with strict header compliance, token management, and comprehensive Pydantic validation.
 
-> ⚠️ **Critical Note**: This SDK implements the **new OSCU specification** (KRA-hosted), *not* the legacy eTIMS API. OSCU requires device registration, headers, and `cmcKey` lifecycle management.
+> ⚠️ **Critical Note**: This SDK implements the **new OSCU specification** (KRA-hosted), *not* the VSCU eTIMS API. OSCU requires device registration, headers, and `cmcKey` lifecycle management.
 
 ## Author
 **Bartile Emmanuel**  
@@ -50,15 +50,15 @@ A production-ready **Python SDK** for integrating with the Kenya Revenue Authori
 
 ## Introduction to eTIMS OSCU
 
-KRA's **Electronic Tax Invoice Management System (eTIMS)** uses **OSCU** (Online Sales Control Unit) – a KRA-hosted software module that validates and signs tax invoices in real-time before issuance. Unlike legacy systems, OSCU requires:
+KRA's **Electronic Tax Invoice Management System (eTIMS)** uses **OSCU** (Online Sales Control Unit) – a KRA-hosted software module that validates and signs tax invoices in real-time before issuance. Unlike VSCU, OSCU requires:
 
 - Pre-registered device serial numbers (`dvcSrlNo`)
 - Communication key (`cmcKey`) lifecycle management
 - Strict payload schema compliance per KRA specifications
 
-### OSCU vs Legacy eTIMS
+### OSCU vs VSCU eTIMS
 
-| Feature | OSCU (This SDK) | Legacy eTIMS |
+| Feature | OSCU (This SDK) | VSCU eTIMS |
 |---------|-----------------|--------------|
 | **Hosting** | KRA-hosted (cloud) | Self-hosted (on-premise) |
 | **Device Registration** | Mandatory pre-registration | Not required |
@@ -175,7 +175,7 @@ Before integration, you **MUST** complete these prerequisites:
 ### 2. Communication Key Lifecycle
 ```python
 # 1. Initialize FIRST (returns cmcKey)
-response = etims.initialize({
+response = etims.select_init_osdc_info({
     "tin": config.oscu["tin"],
     "bhfId": config.oscu["bhf_id"],
     "dvcSrlNo": "dvcv1130",  # KRA-approved serial
@@ -293,7 +293,7 @@ config = KraEtimsConfig(
     
     endpoints={
         # INITIALIZATION (ONLY endpoint without tin/bhfId/cmcKey headers)
-        "initialize": "/initialize",
+        "selectInitOsdcInfo": "/selectInitOsdcInfo",
         
         # DATA MANAGEMENT
         "selectCodeList": "/selectCodeList",
@@ -363,12 +363,11 @@ except AuthenticationException as e:
 try:
     # ⚠️ MUST use KRA-approved device serial (NOT dynamic!)
     # Common sandbox test value (if pre-provisioned by KRA):
-    device_serial = "dvcv1130"  # REPLACE with your approved serial
     
-    response = etims.initialize({
+    response = etims.select_init_info({
         "tin": config.oscu["tin"],
         "bhfId": config.oscu["bhf_id"],
-        "dvcSrlNo": device_serial.strip(),
+        "dvcSrlNo": config.oscu["device_serial"],
     })
 
     # Extract cmcKey (sandbox returns at root level)
@@ -483,7 +482,7 @@ except ApiException as e:
 
 | Category | Purpose | Endpoints |
 |----------|---------|-----------|
-| **Initialization** | Device registration & cmcKey acquisition | `initialize` |
+| **Initialization** | Device registration & cmcKey acquisition | `select_init_info` |
 | **Data Management** | Retrieve standard codes & master data | `select_code_list`, `select_item_cls_list`, `select_bhf_list`, `select_taxpayer_info`, `select_customer_list`, `select_notice_list` |
 | **Branch Management** | Manage branch offices & users | `branch_insurance_info`, `branch_user_account`, `branch_send_customer_info` |
 | **Item Management** | Item master data | `save_item`, `item_info` |

{kra_etims_sdk-0.1.0 → kra_etims_sdk-0.1.1}/kra_etims_sdk/base_client.py

@@ -32,10 +32,11 @@ class BaseClient:
     def _request(self, method, endpoint, data):
         url = self.base_url() + endpoint
         headers = self._headers(endpoint)
+        print(url, headers, data)
         return requests.request(method, url, json=data, headers=headers, timeout=30)
 
     def _headers(self, endpoint):
-        if endpoint.endswith("/initialize"):
+        if endpoint.endswith("/selectInitOsdcInfo"):
             return {
                 "Authorization": f"Bearer {self.auth.token()}",
                 "Content-Type": "application/json",

{kra_etims_sdk-0.1.0 → kra_etims_sdk-0.1.1}/kra_etims_sdk/client.py

@@ -11,12 +11,12 @@ class EtimsClient(BaseClient):
     def _validate(self, data: dict, schema: str) -> dict:
         return self.validator.validate(data, schema)
 
-    # -----------------------------
-    # INITIALIZATION (POSTMAN-COMPLIANT)
-    # -----------------------------
-    def initialize(self, data: dict) -> dict:
-        validated = self._validate(data, "initialization")
-        return self.post("initialize", validated)
+    def select_init_osdc_info(self, data: dict) -> dict:
+        """
+        Initialize the OSCU device with KRA.
+        Returns cmcKey and device information.
+        """
+        return self.post("selectInitOsdcInfo", self._validate(data, "initialization"))
 
     # -----------------------------
     # BASIC DATA ENDPOINTS

{kra_etims_sdk-0.1.0 → kra_etims_sdk-0.1.1}/kra_etims_sdk/schemas.py

@@ -14,7 +14,7 @@ from pydantic import (
 # =========================================================
 
 TIN = Annotated[str, StringConstraints(min_length=1, max_length=20)]
-BHF = Annotated[str, StringConstraints(min_length=1, max_length=10)]
+BHF = Annotated[str, StringConstraints(min_length=1, max_length=20)]
 
 YN = Annotated[str, StringConstraints(pattern="^[YN]$")]
 

{kra_etims_sdk-0.1.0 → kra_etims_sdk-0.1.1}/kra_etims_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kra-etims-sdk
-Version: 0.1.0
+Version: 0.1.1
 Summary: Python SDK for KRA eTIMS OSCU API
 Author: Emmanuel Bartile
 License: MIT
@@ -41,7 +41,7 @@ Dynamic: license-file
 
 A production-ready **Python SDK** for integrating with the Kenya Revenue Authority (KRA) **eTIMS OSCU** (Online Sales Control Unit) API. Built to match the official Postman collection specifications with strict header compliance, token management, and comprehensive Pydantic validation.
 
-> ⚠️ **Critical Note**: This SDK implements the **new OSCU specification** (KRA-hosted), *not* the legacy eTIMS API. OSCU requires device registration, headers, and `cmcKey` lifecycle management.
+> ⚠️ **Critical Note**: This SDK implements the **new OSCU specification** (KRA-hosted), *not* the VSCU eTIMS API. OSCU requires device registration, headers, and `cmcKey` lifecycle management.
 
 ## Author
 **Bartile Emmanuel**  
@@ -73,15 +73,15 @@ A production-ready **Python SDK** for integrating with the Kenya Revenue Authori
 
 ## Introduction to eTIMS OSCU
 
-KRA's **Electronic Tax Invoice Management System (eTIMS)** uses **OSCU** (Online Sales Control Unit) – a KRA-hosted software module that validates and signs tax invoices in real-time before issuance. Unlike legacy systems, OSCU requires:
+KRA's **Electronic Tax Invoice Management System (eTIMS)** uses **OSCU** (Online Sales Control Unit) – a KRA-hosted software module that validates and signs tax invoices in real-time before issuance. Unlike VSCU, OSCU requires:
 
 - Pre-registered device serial numbers (`dvcSrlNo`)
 - Communication key (`cmcKey`) lifecycle management
 - Strict payload schema compliance per KRA specifications
 
-### OSCU vs Legacy eTIMS
+### OSCU vs VSCU eTIMS
 
-| Feature | OSCU (This SDK) | Legacy eTIMS |
+| Feature | OSCU (This SDK) | VSCU eTIMS |
 |---------|-----------------|--------------|
 | **Hosting** | KRA-hosted (cloud) | Self-hosted (on-premise) |
 | **Device Registration** | Mandatory pre-registration | Not required |
@@ -198,7 +198,7 @@ Before integration, you **MUST** complete these prerequisites:
 ### 2. Communication Key Lifecycle
 ```python
 # 1. Initialize FIRST (returns cmcKey)
-response = etims.initialize({
+response = etims.select_init_osdc_info({
     "tin": config.oscu["tin"],
     "bhfId": config.oscu["bhf_id"],
     "dvcSrlNo": "dvcv1130",  # KRA-approved serial
@@ -316,7 +316,7 @@ config = KraEtimsConfig(
     
     endpoints={
         # INITIALIZATION (ONLY endpoint without tin/bhfId/cmcKey headers)
-        "initialize": "/initialize",
+        "selectInitOsdcInfo": "/selectInitOsdcInfo",
         
         # DATA MANAGEMENT
         "selectCodeList": "/selectCodeList",
@@ -386,12 +386,11 @@ except AuthenticationException as e:
 try:
     # ⚠️ MUST use KRA-approved device serial (NOT dynamic!)
     # Common sandbox test value (if pre-provisioned by KRA):
-    device_serial = "dvcv1130"  # REPLACE with your approved serial
     
-    response = etims.initialize({
+    response = etims.select_init_info({
         "tin": config.oscu["tin"],
         "bhfId": config.oscu["bhf_id"],
-        "dvcSrlNo": device_serial.strip(),
+        "dvcSrlNo": config.oscu["device_serial"],
     })
 
     # Extract cmcKey (sandbox returns at root level)
@@ -506,7 +505,7 @@ except ApiException as e:
 
 | Category | Purpose | Endpoints |
 |----------|---------|-----------|
-| **Initialization** | Device registration & cmcKey acquisition | `initialize` |
+| **Initialization** | Device registration & cmcKey acquisition | `select_init_info` |
 | **Data Management** | Retrieve standard codes & master data | `select_code_list`, `select_item_cls_list`, `select_bhf_list`, `select_taxpayer_info`, `select_customer_list`, `select_notice_list` |
 | **Branch Management** | Manage branch offices & users | `branch_insurance_info`, `branch_user_account`, `branch_send_customer_info` |
 | **Item Management** | Item master data | `save_item`, `item_info` |

{kra_etims_sdk-0.1.0 → kra_etims_sdk-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kra-etims-sdk"
-version = "0.1.0"
+version = "0.1.1"
 description = "Python SDK for KRA eTIMS OSCU API"
 readme = "README.md"
 requires-python = ">=3.9"

{kra_etims_sdk-0.1.0 → kra_etims_sdk-0.1.1}/tests/test_etims.py

@@ -60,10 +60,10 @@ CONFIG = {
 
     "api": {
         "sbx": {
-            "base_url": "https://sbx.kra.go.ke/etims-oscu/api/v1",
+            "base_url": "https://etims-api-sbx.kra.go.ke/etims-api",
         },
         "prod": {
-            "base_url": "https://kra.go.ke/etims-oscu/api/v1",
+            "base_url": "https://etims-api.kra.go.ke/etims-api",
         },
     },
 
@@ -72,13 +72,14 @@ CONFIG = {
     },
 
     "oscu": {
-        "tin": os.getenv("KRA_TIN", "P000000002"),
-        "bhf_id": os.getenv("KRA_BHF_ID", "00"),
-        "cmc_key": "",
+        "tin": os.getenv("KRA_TIN", ""),
+        "bhf_id": os.getenv("KRA_BHF_ID", ""),
+        "cmc_key": os.getenv("CMC_KEY", ""),
+        "device_serial": os.getenv("DEVICE_SERIAL", ""),
     },
 
     "endpoints": {
-        "initialize": "/initialize",
+        "selectInitOsdcInfo": "/selectInitOsdcInfo",
         "selectCodeList": "/selectCodeList",
         "selectTaxpayerInfo": "/selectTaxpayerInfo",
         "selectNoticeList": "/selectNoticeList",
@@ -124,28 +125,26 @@ except AuthenticationException as e:
 header("STEP 2: OSCU INITIALIZATION")
 warning("Device serial MUST be pre-registered with KRA")
 
-DEVICE_SERIAL = "dvcv1130"  # 🔴 REPLACE WITH APPROVED SERIAL
-
 try:
     etims = EtimsClient(CONFIG, auth)
 
-    response = etims.initialize({
-        "tin": CONFIG["oscu"]["tin"],
-        "bhfId": CONFIG["oscu"]["bhf_id"],
-        "dvcSrlNo": DEVICE_SERIAL,
-    })
+    # response = etims.select_init_info({
+    #     "tin": CONFIG["oscu"]["tin"],
+    #     "bhfId": CONFIG["oscu"]["bhf_id"],
+    #     "dvcSrlNo": CONFIG["oscu"]["device_serial"],
+    # })
 
-    pprint(response)
+    # pprint(response)
+
+    # cmc_key = response.get("cmcKey") or response.get("data", {}).get("info", {}).get("cmcKey")
+    # if not cmc_key:
+    #     raise RuntimeError("cmcKey missing from initialization response")
 
-    cmc_key = response.get("cmcKey") or response.get("data", {}).get("cmcKey")
-    if not cmc_key:
-        raise RuntimeError("cmcKey missing from initialization response")
+    # success("Initialization successful")
+    # print("cmcKey:", cmc_key[:15], "...")
 
-    CONFIG["oscu"]["cmc_key"] = cmc_key
     etims = EtimsClient(CONFIG, auth)
 
-    success("Initialization successful")
-    print("cmcKey:", cmc_key[:15], "...")
 except ApiException as e:
     error(f"Initialization failed: {e}")
     pprint(e.details)
@@ -160,10 +159,10 @@ try:
         "bhfId": CONFIG["oscu"]["bhf_id"],
         "lastReqDt": format_date(),
     })
-
     count = len(response.get("itemList", []))
     success(f"Retrieved {count} code list items")
 except ApiException as e:
+    print("emm")
     error(str(e))
     sys.exit(1)