# GavaConnect - Kenya Revenue Authority API Client
A Python package for simplified access to Kenya Revenue Authority (KRA) API. This package provides an easy-to-use interface for checking KRA PIN numbers and validating taxpayer information.
## Features
- 🔐 Secure authentication with KRA API
- 📋 KRA PIN validation
- 🆔 ID-based PIN lookup
- 🏗️ Support for both sandbox and production environments
- 📊 Tax obligation type enumeration
- 🛡️ Error handling and logging
## Installation
```bash
pip install gava-connect
```
## Quick Start
### 1. Set up your environment variables
Create a `.env` file in your project directory:
```env
PIN_CHECKER_CONSUMER_KEY=your_consumer_key_here
PIN_CHECKER_CONSUMER_SECRET=your_consumer_secret_here
```
### 2. Basic Usage
```python
from gava_connect import KRAGavaConnect
# Initialize the client (sandbox environment)
kra_client = KRAGavaConnect(
consumer_key="your_consumer_key",
consumer_secret="your_consumer_secret",
environment="sandbox" # or "production"
)
# Check KRA PIN
result = kra_client.check_pin_kra_pin("A123456789")
print(result)
# Check PIN by ID number
result = kra_client.check_pin_by_id("12345678")
print(result)
```
## API Reference
### KRAGavaConnect
The main client class for interacting with the KRA API.
#### Constructor
```python
KRAGavaConnect(consumer_key, consumer_secret, environment="sandbox")
```
**Parameters:**
- `consumer_key` (str): Your KRA API consumer key
- `consumer_secret` (str): Your KRA API consumer secret
- `environment` (str): Environment to use ("sandbox" or "production")
#### Methods
##### check_pin_kra_pin(kra_pin_number)
Check if a KRA PIN is valid.
**Parameters:**
- `kra_pin_number` (str): The KRA PIN number to validate
**Returns:**
- dict: JSON response from the KRA API
##### check_pin_by_id(id_number)
Check KRA PIN using ID number.
**Parameters:**
- `id_number` (str): The ID number to lookup
**Returns:**
- dict: JSON response from the KRA API
### TaxObligationType
Enumeration of tax obligation types supported by KRA.
#### Available Types
- `"4"`: Income Tax - Company
- `"7"`: Income Tax - PAYE
- `"9"`: Value Added Tax (VAT)
- `"22"`: Advance Tax
- `"6"`: Income Tax - Withholding
- `"32"`: Capital Gain Tax (CGT)
- `"29"`: VAT Withholding
#### Methods
##### get_obligation_type(code)
Get the description of a tax obligation type by its code.
##### get_obligation_code(description)
Get the code of a tax obligation type by its description.
## Environment Configuration
The package supports two environments:
- **Sandbox**: For testing and development
- Base URL: `https://sbx.kra.go.ke`
- **Production**: For live applications
- Base URL: `https://api.kra.go.ke`
## Error Handling
The package includes comprehensive error handling:
- Invalid environment specification
- Missing or invalid credentials
- API authentication failures
- Network request errors
## Logging
The package uses Python's built-in logging module. Logs are set to INFO level by default.
## Examples
### Complete Example
```python
import os
from dotenv import load_dotenv
from gava_connect import KRAGavaConnect, TaxObligationType
# Load environment variables
load_dotenv()
# Initialize client
kra_client = KRAGavaConnect(
consumer_key=os.getenv("PIN_CHECKER_CONSUMER_KEY"),
consumer_secret=os.getenv("PIN_CHECKER_CONSUMER_SECRET"),
environment="sandbox"
)
# Check a KRA PIN
try:
result = kra_client.check_pin_kra_pin("A123456789")
print("PIN Check Result:", result)
except Exception as e:
print(f"Error checking PIN: {e}")
# Get tax obligation type description
obligation_desc = TaxObligationType.get_obligation_type("9")
print(f"Tax obligation 9: {obligation_desc}") # Output: Value Added Tax (VAT)
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
For support, please open an issue on the GitHub repository or contact the maintainers.
## Disclaimer
This package is not officially affiliated with the Kenya Revenue Authority. Please ensure you comply with KRA's terms of service and API usage guidelines.
# KRA-GAVA-Connect
Raw data
{
"_id": null,
"home_page": "https://github.com/Paulndambo/KRA-Gava-Connect",
"name": "gava-connect",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Paul Ndambo <paulkadabo@gmail.com>",
"keywords": "kra, kenya, revenue, authority, api, tax, pin, gava",
"author": "Paul Ndambo",
"author_email": "Paul Ndambo <paulkadabo@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/bf/61/52728f84efcc82977a8c3a0cd9f71bbff2d83641678310c0a2c164ecbeb8/gava_connect-1.0.1.tar.gz",
"platform": null,
"description": "# GavaConnect - Kenya Revenue Authority API Client\n\nA Python package for simplified access to Kenya Revenue Authority (KRA) API. This package provides an easy-to-use interface for checking KRA PIN numbers and validating taxpayer information.\n\n## Features\n\n- \ud83d\udd10 Secure authentication with KRA API\n- \ud83d\udccb KRA PIN validation\n- \ud83c\udd94 ID-based PIN lookup\n- \ud83c\udfd7\ufe0f Support for both sandbox and production environments\n- \ud83d\udcca Tax obligation type enumeration\n- \ud83d\udee1\ufe0f Error handling and logging\n\n## Installation\n\n```bash\npip install gava-connect\n```\n\n## Quick Start\n\n### 1. Set up your environment variables\n\nCreate a `.env` file in your project directory:\n\n```env\nPIN_CHECKER_CONSUMER_KEY=your_consumer_key_here\nPIN_CHECKER_CONSUMER_SECRET=your_consumer_secret_here\n```\n\n### 2. Basic Usage\n\n```python\nfrom gava_connect import KRAGavaConnect\n\n# Initialize the client (sandbox environment)\nkra_client = KRAGavaConnect(\n consumer_key=\"your_consumer_key\",\n consumer_secret=\"your_consumer_secret\",\n environment=\"sandbox\" # or \"production\"\n)\n\n# Check KRA PIN\nresult = kra_client.check_pin_kra_pin(\"A123456789\")\nprint(result)\n\n# Check PIN by ID number\nresult = kra_client.check_pin_by_id(\"12345678\")\nprint(result)\n```\n\n## API Reference\n\n### KRAGavaConnect\n\nThe main client class for interacting with the KRA API.\n\n#### Constructor\n\n```python\nKRAGavaConnect(consumer_key, consumer_secret, environment=\"sandbox\")\n```\n\n**Parameters:**\n- `consumer_key` (str): Your KRA API consumer key\n- `consumer_secret` (str): Your KRA API consumer secret\n- `environment` (str): Environment to use (\"sandbox\" or \"production\")\n\n#### Methods\n\n##### check_pin_kra_pin(kra_pin_number)\n\nCheck if a KRA PIN is valid.\n\n**Parameters:**\n- `kra_pin_number` (str): The KRA PIN number to validate\n\n**Returns:**\n- dict: JSON response from the KRA API\n\n##### check_pin_by_id(id_number)\n\nCheck KRA PIN using ID number.\n\n**Parameters:**\n- `id_number` (str): The ID number to lookup\n\n**Returns:**\n- dict: JSON response from the KRA API\n\n### TaxObligationType\n\nEnumeration of tax obligation types supported by KRA.\n\n#### Available Types\n\n- `\"4\"`: Income Tax - Company\n- `\"7\"`: Income Tax - PAYE\n- `\"9\"`: Value Added Tax (VAT)\n- `\"22\"`: Advance Tax\n- `\"6\"`: Income Tax - Withholding\n- `\"32\"`: Capital Gain Tax (CGT)\n- `\"29\"`: VAT Withholding\n\n#### Methods\n\n##### get_obligation_type(code)\n\nGet the description of a tax obligation type by its code.\n\n##### get_obligation_code(description)\n\nGet the code of a tax obligation type by its description.\n\n## Environment Configuration\n\nThe package supports two environments:\n\n- **Sandbox**: For testing and development\n - Base URL: `https://sbx.kra.go.ke`\n- **Production**: For live applications\n - Base URL: `https://api.kra.go.ke`\n\n## Error Handling\n\nThe package includes comprehensive error handling:\n\n- Invalid environment specification\n- Missing or invalid credentials\n- API authentication failures\n- Network request errors\n\n## Logging\n\nThe package uses Python's built-in logging module. Logs are set to INFO level by default.\n\n## Examples\n\n### Complete Example\n\n```python\nimport os\nfrom dotenv import load_dotenv\nfrom gava_connect import KRAGavaConnect, TaxObligationType\n\n# Load environment variables\nload_dotenv()\n\n# Initialize client\nkra_client = KRAGavaConnect(\n consumer_key=os.getenv(\"PIN_CHECKER_CONSUMER_KEY\"),\n consumer_secret=os.getenv(\"PIN_CHECKER_CONSUMER_SECRET\"),\n environment=\"sandbox\"\n)\n\n# Check a KRA PIN\ntry:\n result = kra_client.check_pin_kra_pin(\"A123456789\")\n print(\"PIN Check Result:\", result)\nexcept Exception as e:\n print(f\"Error checking PIN: {e}\")\n\n# Get tax obligation type description\nobligation_desc = TaxObligationType.get_obligation_type(\"9\")\nprint(f\"Tax obligation 9: {obligation_desc}\") # Output: Value Added Tax (VAT)\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\nFor support, please open an issue on the GitHub repository or contact the maintainers.\n\n## Disclaimer\n\nThis package is not officially affiliated with the Kenya Revenue Authority. Please ensure you comply with KRA's terms of service and API usage guidelines.\n# KRA-GAVA-Connect\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python package for simplified access to Kenya Revenue Authority (KRA) API",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/Paulndambo/KRA-Gava-Connect/issues",
"Documentation": "https://github.com/Paulndambo/KRA-Gava-Connect#readme",
"Homepage": "https://github.com/Paulndambo/KRA-Gava-Connect",
"Repository": "https://github.com/Paulndambo/KRA-Gava-Connect"
},
"split_keywords": [
"kra",
" kenya",
" revenue",
" authority",
" api",
" tax",
" pin",
" gava"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f4692d0f9a668b9b378feb7428c6733538f770910aa9d76867521d7f5b6632c0",
"md5": "6c0bc067800a2f2ecc4899de69e91d5e",
"sha256": "003164b88b53cd3a0a839af506ef70e8717555b99329c20f6877d878b9df0193"
},
"downloads": -1,
"filename": "gava_connect-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6c0bc067800a2f2ecc4899de69e91d5e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 9986,
"upload_time": "2025-08-18T13:16:46",
"upload_time_iso_8601": "2025-08-18T13:16:46.885389Z",
"url": "https://files.pythonhosted.org/packages/f4/69/2d0f9a668b9b378feb7428c6733538f770910aa9d76867521d7f5b6632c0/gava_connect-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bf6152728f84efcc82977a8c3a0cd9f71bbff2d83641678310c0a2c164ecbeb8",
"md5": "b7a27edbb4f09f35840aeb2e4bedb816",
"sha256": "df9dfde5c3c995e33793c4a7a12f21e498d98e1e07ccc6d8064c46a9fcd111dc"
},
"downloads": -1,
"filename": "gava_connect-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "b7a27edbb4f09f35840aeb2e4bedb816",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 13293,
"upload_time": "2025-08-18T13:16:48",
"upload_time_iso_8601": "2025-08-18T13:16:48.113484Z",
"url": "https://files.pythonhosted.org/packages/bf/61/52728f84efcc82977a8c3a0cd9f71bbff2d83641678310c0a2c164ecbeb8/gava_connect-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 13:16:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Paulndambo",
"github_project": "KRA-Gava-Connect",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"0.19.0"
]
]
},
{
"name": "build",
"specs": []
},
{
"name": "twine",
"specs": []
}
],
"lcname": "gava-connect"
}
JSON
