kra-etims-sdk 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

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/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/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.dist-info → kra_etims_sdk-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kra-etims-sdk
-Version: 0.1.0
+Version: 0.1.2
 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 |
@@ -191,17 +191,18 @@ flowchart TD
 Before integration, you **MUST** complete these prerequisites:
 
 ### 1. Device Registration (MANDATORY)
-- Register OSCU device via [eTIMS Taxpayer Sandbox Portal](https://sbx.kra.go.ke)
+- Register OSCU device via [eTIMS Taxpayer Production Portal](https://etims.kra.go.ke) 
+- Register OSCU device via [eTIMS Taxpayer Sandbox Portal](https://etims-sbx.kra.go.ke) 
 - Obtain **approved device serial number** (`dvcSrlNo`)
 - ⚠️ **Dynamic/unregistered device serials fail with `resultCd: 901`** ("It is not valid device")
 
 ### 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
+    "dvcSrlNo": config.oscu["device_serial"],  # KRA-approved serial
 })
 
 # 2. Extract cmcKey (sandbox returns at root level)
@@ -304,19 +305,19 @@ config = KraEtimsConfig(
     },
     
     api={
-        "sandbox": {"base_url": "https://sbx.kra.go.ke/etims-oscu/api/v1".strip()},
-        "production": {"base_url": "https://api.developer.go.ke/etims-oscu/api/v1".strip()}
+        "sandbox": {"base_url": "https://etims-api-sbx.kra.go.ke/etims-api".strip()},
+        "production": {"base_url": "https://etims-api.kra.go.ke/etims-api".strip()}
     },
     
     oscu={
         "tin": os.environ["KRA_TIN"],
-        "bhf_id": os.environ["KRA_BHF_ID"],
-        "cmc_key": "",  # Set AFTER initialization
+        "bhf_id": os.environ["KRA_BHF_ID"],        
+        "cmc_key": os.environ["CMC_KEY"] # Set AFTER initialization
     },
     
     endpoints={
         # INITIALIZATION (ONLY endpoint without tin/bhfId/cmcKey headers)
-        "initialize": "/initialize",
+        "selectInitOsdcInfo": "/selectInitOsdcInfo",
         
         # DATA MANAGEMENT
         "selectCodeList": "/selectCodeList",
@@ -355,7 +356,7 @@ config = KraEtimsConfig(
 ```
 
 > 💡 **Production URL Note**:  
-> Production base URL is `https://api.developer.go.ke/etims-oscu/api/v1` (NOT `kra.go.ke`)
+> Production base URL is `https://etims-api.kra.go.ke/etims-api` (NOT `https://etims-api-sbx.kra.go.ke/etims-api`)
 
 ---
 
@@ -386,12 +387,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 +506,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` |
@@ -720,7 +720,7 @@ KRA mandates successful completion of automated tests before verification:
 3. Deploy directly to production environment
 4. No SLA execution required
 
-> 💡 **Production URL**: `https://api.developer.go.ke/etims-oscu/api/v1`  
+> 💡 **Production URL**: `https://etims-api.kra.go.ke/etims-api`  
 > ⚠️ **Never use sandbox credentials in production** – KRA monitors environment separation strictly
 
 ---

kra_etims_sdk-0.1.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+kra_etims_sdk/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kra_etims_sdk/auth.py,sha256=_fRE1QhRWjOsHrd8ds9RAu_0kPrR4XFsl8KYrLf1avk,1812
+kra_etims_sdk/base_client.py,sha256=oWZhLWj7PCECW_tGim6U7venX7_OerkvePIyvXw0OCg,2266
+kra_etims_sdk/client.py,sha256=CEfk-DbVbTmSi-Q6pAgS3MHnofb5ejwnyYN-btXyNHA,3853
+kra_etims_sdk/exceptions.py,sha256=Kcwvh7dbsxZ5X2iHcW9p8bxWai2FiZHL6Jb7904u9HE,630
+kra_etims_sdk/schemas.py,sha256=mZEUAIDwrlG8NaE6rpPMHXFoNU2q2NOLj7YBM-gICAc,4585
+kra_etims_sdk/validator.py,sha256=JDBZo5GXuczibIia3XSE_ytjJ5OzqQ8e7QT9Fh7hmtk,1168
+kra_etims_sdk-0.1.2.dist-info/licenses/LICENSE,sha256=Fl2vp3H5372qSizz8VOT8f3H1bSxSqY-YZ8Qb4N25pM,1067
+kra_etims_sdk-0.1.2.dist-info/METADATA,sha256=4jRq84d05msYleJoxAgkpJYv0kZfwufdRKGqmIUsW2U,29550
+kra_etims_sdk-0.1.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+kra_etims_sdk-0.1.2.dist-info/top_level.txt,sha256=LRqz__wcOsq5Ds_evpPLZ9yHdxvIDCIu_oGSW3fRcTY,14
+kra_etims_sdk-0.1.2.dist-info/RECORD,,

kra_etims_sdk-0.1.0.dist-info/RECORD

@@ -1,12 +0,0 @@
-kra_etims_sdk/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kra_etims_sdk/auth.py,sha256=_fRE1QhRWjOsHrd8ds9RAu_0kPrR4XFsl8KYrLf1avk,1812
-kra_etims_sdk/base_client.py,sha256=Wn2esjMcjXsw6wPHIdXp0wmvoKSXWfMg7DLFQpsM8PA,2224
-kra_etims_sdk/client.py,sha256=3LrzXUupVMKQ3efupWJr6_wpK-RAjCYgEGYQFBoJHNM,3861
-kra_etims_sdk/exceptions.py,sha256=Kcwvh7dbsxZ5X2iHcW9p8bxWai2FiZHL6Jb7904u9HE,630
-kra_etims_sdk/schemas.py,sha256=InPS4VWmL0ssUKxUvVzpLjbivXARDb_I0iVuCdjiEoA,4585
-kra_etims_sdk/validator.py,sha256=JDBZo5GXuczibIia3XSE_ytjJ5OzqQ8e7QT9Fh7hmtk,1168
-kra_etims_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=Fl2vp3H5372qSizz8VOT8f3H1bSxSqY-YZ8Qb4N25pM,1067
-kra_etims_sdk-0.1.0.dist-info/METADATA,sha256=HgxEf3SEo_Y__2D8maWVDQbZ8u7fs8tEOz3vREV81co,29440
-kra_etims_sdk-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-kra_etims_sdk-0.1.0.dist-info/top_level.txt,sha256=LRqz__wcOsq5Ds_evpPLZ9yHdxvIDCIu_oGSW3fRcTY,14
-kra_etims_sdk-0.1.0.dist-info/RECORD,,