insideapp-python-sdk 1.30.2

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.

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.

🚀 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.

The project follows Semantic Versioning and Keep a Changelog.

Support & Documentation

• 📧 Email Support: [e-mail]
• 🎫 Technical Support: developer.iapp.ro
• 📞 Contact: iapp.ro/contact
• 📖 Documentation: doc.iapp.ro
• 🔧 API References: doc.iapp.ro/swagger
• 🤝 Reseller API: doc.iapp.ro/reseller
• 🔗 Reseller Webhooks: doc.iapp.ro/reseller-webhook

Installation

Install via pip:

pip install insideapp-python-sdk

Or with development dependencies:

pip install insideapp-python-sdk[dev]

Quick Start

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

from datetime import datetime
from insideapp import InsideAppClient

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

invoice_data = {
    'email_responsabil': '[e-mail]',
    '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': '[e-mail]'
    },
    '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 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

pytest tests/unit/ -v

Run Integration Tests (requires real API credentials)

# Set environment variables
export INSIDEAPP_TEST_USERNAME="your_username"
export INSIDEAPP_TEST_PASSWORD="your_password"  
export INSIDEAPP_TEST_EMAIL="[e-mail]"
export INSIDEAPP_INTEGRATION_TESTS=true

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

Run All Tests with Coverage

pytest --cov=insideapp --cov-report=html

Error Handling

The SDK provides structured exception handling:

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

# Set timeout during initialization
client = InsideAppClient("username", "password", timeout=600)

# Or change it later
client.set_timeout(300)

Environment Variables for Testing

INSIDEAPP_TEST_USERNAME=your_api_username
INSIDEAPP_TEST_PASSWORD=your_api_password
INSIDEAPP_TEST_EMAIL=[e-mail]
INSIDEAPP_INTEGRATION_TESTS=true

Development

Setup Development Environment

# 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

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 file for details.

Related Projects

• PHP SDK - Original PHP implementation
• InsideApp Platform - 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
4. Contact support at [e-mail]