Metadata-Version: 2.4
Name: insideapp-python-sdk
Version: 1.30.2
Summary: Python SDK pentru InsideApp - gestiune facturi și integrare completă cu SPV. Emite facturi, integrează eFactura automat cu ANAF și gestionează tot procesul de facturare pentru mai multe firme direct din aplicația ta Python.
Project-URL: Homepage, https://iapp.ro
Project-URL: Documentation, https://doc.iapp.ro
Project-URL: Repository, https://github.com/AninuApps/InsideApp-Python
Project-URL: Bug Reports, https://github.com/AninuApps/InsideApp-Python/issues
Project-URL: API Reference, https://doc.iapp.ro/swagger
Project-URL: Support, https://developer.iapp.ro
Project-URL: Reseller API, https://doc.iapp.ro/reseller
Author-email: InsideApp <support@iapp.ro>
Maintainer-email: InsideApp <support@iapp.ro>
License: MIT License
        
        Copyright (c) 2024 InsideApp
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: anaf,api,efactura,facturare,insideapp,romania,sdk,spv
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: requests>=2.31.0
Requires-Dist: urllib3>=2.0.0
Provides-Extra: dev
Requires-Dist: black>=23.7.0; extra == 'dev'
Requires-Dist: flake8>=6.0.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.11.1; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: types-requests>=2.31.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest-mock>=3.11.1; extra == 'test'
Requires-Dist: pytest>=7.4.0; extra == 'test'
Description-Content-Type: text/markdown

# InsideApp Python SDK

**Python SDK for InsideApp** - complete invoice management and SPV integration. Everything you need for billing in Romania: issue invoices, automatically integrate with ANAF eFactura, and manage the entire process for multiple companies directly from your Python application.

[![PyPI version](https://badge.fury.io/py/insideapp-python-sdk.svg)](https://badge.fury.io/py/insideapp-python-sdk)
[![Python versions](https://img.shields.io/pypi/pyversions/insideapp-python-sdk)](https://pypi.org/project/insideapp-python-sdk/)
[![License](https://img.shields.io/pypi/l/insideapp-python-sdk)](https://opensource.org/licenses/MIT)
[![Downloads](https://pepy.tech/badge/insideapp-python-sdk)](https://pepy.tech/project/insideapp-python-sdk)

## 🚀 Key Features

- **📋 Invoice Management**: Proforma, fiscal invoices, receipts, collections
- **🏛️ Complete SPV Integration**: Automatic eFactura with ANAF  
- **📚 Digital Archive**: All issued and received invoices from SPV
- **👥 Complete Management**: Clients, products, services, bank accounts
- **🏢 Reseller API**: Manage invoicing for multiple companies from your Python app
- **🔧 Useful Tools**: CIF validation, exchange rates, configurations
- **🌍 Geographic Info**: Romanian counties and localities data

## 📋 Changelog & Versioning

All changes and versions are documented in [CHANGELOG.md](CHANGELOG.md).

The project follows [Semantic Versioning](https://semver.org/) and [Keep a Changelog](https://keepachangelog.com/).

## Support & Documentation

- **📧 Email Support**: support@iapp.ro
- **🎫 Technical Support**: [developer.iapp.ro](https://developer.iapp.ro)
- **📞 Contact**: [iapp.ro/contact](https://iapp.ro/contact)
- **📖 Documentation**: [doc.iapp.ro](https://doc.iapp.ro)
- **🔧 API References**: [doc.iapp.ro/swagger](https://doc.iapp.ro/swagger)
- **🤝 Reseller API**: [doc.iapp.ro/reseller](https://doc.iapp.ro/reseller)
- **🔗 Reseller Webhooks**: [doc.iapp.ro/reseller-webhook](https://doc.iapp.ro/reseller-webhook)

## Installation

Install via pip:

```bash
pip install insideapp-python-sdk
```

Or with development dependencies:

```bash
pip install insideapp-python-sdk[dev]
```

## Quick Start

```python
from insideapp import InsideAppClient

# Initialize the client
client = InsideAppClient("your_username", "your_password")

# Get exchange rates
rates = client.curs_valutar()
print(f"EUR rate: {rates['cursuri']['EUR']['curs']} RON")

# Validate a CIF
cif_info = client.info_cif({"cif": "RO123456789"})
if cif_info.get("valid"):
    print(f"Company: {cif_info['denumire']}")

# Get Romanian counties
counties = client.info_judete()
print(f"Total counties: {len(counties)}")

# Get localities for a county
localities = client.info_localitati({"judet": "TM"})
print(f"Localities in Timiș: {len(localities)}")
```

## Issue an Invoice

```python
from datetime import datetime
from insideapp import InsideAppClient

client = InsideAppClient("username", "password")

invoice_data = {
    'email_responsabil': 'your@email.com',
    'client': {
        'tip_client': 'pj',  # 'pf' = individual, 'pj' = company
        'nume': 'SC Example SRL',
        'cui': '12345678',
        'telefon': '0721123456',
        'judet': 'Bucuresti',
        'localitate': 'Sectorul 1', 
        'adresa': 'Str. Example nr. 123',
        'email': 'client@example.com'
    },
    'data_start': datetime.now().strftime('%Y-%m-%d'),
    'data_termen': '30',  # days
    'seria': 'FF',
    'moneda': 'RON',
    'continut': [
        {
            'title': 'IT Consulting',
            'um': 'hour',
            'cantitate': '40',
            'pret': '150',
            'tvavalue': '1140',
            'tvapercent': '19'
        }
    ]
}

response = client.emite_factura(invoice_data)
print(f"Invoice issued: {response['numar']}")
```

## 📁 Example Files

Find complete examples in the `examples/` folder. **See [examples/README.md](examples/README.md) for detailed documentation and running instructions.**

```
examples/
├── curs_valutar.py           # Current exchange rate
├── info_cif.py              # CIF information verification  
├── info_judete.py           # List of Romanian counties
├── info_localitati.py      # Localities for a county
├── FacturiProforme/
│   ├── emite_factura_proforma.py
│   └── ... 
├── FacturiFiscale/
│   ├── emite_factura_fiscala.py
│   └── ...
├── SPV/
│   ├── lista_facturi_emise.py
│   └── ...
└── ... (complete structure mirror of PHP SDK)
```

## API Methods Coverage

The Python SDK provides **1:1 parity** with the PHP SDK, including all **72 public methods**:

### 🌍 General Information
- `curs_valutar()` - Get current exchange rates
- `info_cif(data)` - Validate and get CIF information  
- `info_judete()` - Get list of Romanian counties (42 counties)
- `info_localitati(data)` - Get localities for a specific county

### 📋 Invoice Management
- **Proforma Invoices**: `emite_proforma()`, `view_proforma()`, `view_proforme()`, etc.
- **Fiscal Invoices**: `emite_factura()`, `view_factura()`, `view_facturi()`, etc.
- **Receipts**: `emite_chitanta()`, `view_chitanta()`, `view_chitante()`, etc.

### 🏛️ SPV/eFactura Integration  
- `e_factura_emise()` - List issued invoices in SPV
- `e_factura_furnizori()` - List supplier invoices from SPV
- `e_factura_upload_xml()` - Upload invoice XML to SPV
- `e_factura_upload_status()` - Check upload status

### 👥 Data Management
- **Clients**: `clienti_lista()`, `clienti_adauga()`, `clienti_modifica()`, etc.
- **Products/Services**: `produse_lista()`, `produse_adauga()`, etc.
- **Bank Accounts**: `conturi_bancare_lista()`, `conturi_bancare_adauga()`, etc.
- **Series Configuration**: `serie_lista()`, `serie_adauga()`, etc.

### 🏢 Reseller API
- **Company Management**: `firma_lista()`, `firma_adauga()`, `firma_modifica()`, etc.
- **API Credentials**: `firma_api()`, `firma_api_reset()`
- **eFactura Settings**: `e_factura_vizualizare_setari()`, etc.

## Testing

The SDK includes comprehensive test suite with both unit and integration tests.

### Run Unit Tests
```bash
pytest tests/unit/ -v
```

### Run Integration Tests (requires real API credentials)
```bash
# Set environment variables
export INSIDEAPP_TEST_USERNAME="your_username"
export INSIDEAPP_TEST_PASSWORD="your_password"  
export INSIDEAPP_TEST_EMAIL="your@email.com"
export INSIDEAPP_INTEGRATION_TESTS=true

# Run integration tests
pytest tests/integration/ -v -m integration
```

### Run All Tests with Coverage
```bash
pytest --cov=insideapp --cov-report=html
```

## Error Handling

The SDK provides structured exception handling:

```python
from insideapp import InsideAppClient
from insideapp.exceptions import (
    InsideAppAPIError,
    InsideAppAuthError, 
    InsideAppTimeoutError
)

try:
    client = InsideAppClient("username", "password")
    response = client.info_cif({"cif": "invalid"})
except InsideAppAuthError:
    print("Invalid credentials")
except InsideAppAPIError as e:
    print(f"API error: {e}")
except InsideAppTimeoutError:
    print("Request timed out")
```

## Configuration

### Timeout Settings
```python
# Set timeout during initialization
client = InsideAppClient("username", "password", timeout=600)

# Or change it later
client.set_timeout(300)
```

### Environment Variables for Testing
```bash
INSIDEAPP_TEST_USERNAME=your_api_username
INSIDEAPP_TEST_PASSWORD=your_api_password
INSIDEAPP_TEST_EMAIL=your@email.com
INSIDEAPP_INTEGRATION_TESTS=true
```

## Development

### Setup Development Environment
```bash
# Clone repository
git clone https://github.com/AninuApps/InsideApp-Python.git
cd InsideApp-Python

# Install in development mode
pip install -e .[dev]

# Run tests
pytest

# Run linting
flake8 insideapp/
black insideapp/

# Type checking  
mypy insideapp/
```

### Pre-commit Hooks
```bash
pip install pre-commit
pre-commit install
```

## Requirements

- **Python**: ≥ 3.8
- **Dependencies**: `requests` ≥ 2.31.0
- **Development**: `pytest`, `black`, `flake8`, `mypy`

## Performance

- **Response Times**: < 300ms for most API calls
- **Concurrent Requests**: Thread-safe client
- **Retry Logic**: Automatic retry for transient failures
- **Connection Pooling**: Efficient HTTP session management

## Migration from PHP SDK

The Python SDK maintains 1:1 functional parity with the PHP SDK:

### Method Name Mapping
- PHP: `camelCase` → Python: `snake_case`
- PHP: `emiteFactura()` → Python: `emite_factura()`
- PHP: `clientiLista()` → Python: `clienti_lista()`

### Error Handling  
- PHP: Exceptions → Python: Custom exception hierarchy
- Structured error responses with status codes and details

### Data Structures
- PHP: Associative arrays → Python: Dictionaries
- Same JSON structure for requests and responses

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/new-feature`)
3. Commit changes (`git commit -am 'Add new feature'`)
4. Push to branch (`git push origin feature/new-feature`)
5. Create Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Related Projects

- **[PHP SDK](https://github.com/AninuApps/InsideApp-PHP)** - Original PHP implementation
- **[InsideApp Platform](https://iapp.ro)** - Web platform for invoice management

---

**Note**: This Python SDK provides complete 1:1 parity with the PHP SDK. All examples are tested and functional. We recommend testing in a development environment before production use.

## 🎯 Testing Suggestions

1. **Start with utilities**: `curs_valutar.py`, `info_cif.py`, `info_judete.py`
2. **Test data management**: add clients, products  
3. **Issue proforma invoices**: then convert to fiscal
4. **Explore SPV**: see invoices in Private Virtual Space
5. **Test Reseller API**: if you have reseller account

## 🛠️ Debugging

For debugging, all examples display the complete API response. In case of error:

1. **Check credentials** in your script
2. **Consult error messages** displayed  
3. **Check documentation** at [doc.iapp.ro](https://doc.iapp.ro)
4. **Contact support** at support@iapp.ro