> ## Documentation Index
> Fetch the complete documentation index at: https://lopiv2-invenicum-25.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations

> Connect Invenicum with external services and APIs

## Overview

Invenicum integrations allow you to connect your inventory system with external services for enhanced functionality, automation, and data synchronization. Integrations support AI features, messaging, e-commerce platforms, and valuation tools.

## Available Integrations

### Artificial Intelligence

> **Google Gemini**
>
> Enable AI-powered features including:
>
> * Intelligent item descriptions
> * Image analysis and categorization
> * Value estimation assistance
> * Smart search and recommendations
>
> **Configuration**: API key required from Google AI Studio

### Messaging & Notifications

> **Telegram Bot**
>
> Set up automated notifications:
>
> * Low stock alerts
> * New item additions
> * Value changes
> * Custom triggers
>
> **Configuration**: Bot token from @BotFather

> **Email (Resend)**
>
> Professional email notifications:
>
> * Scheduled reports
> * Transaction confirmations
> * Sharing collections
> * Export deliveries
>
> **Configuration**: Resend API key

### E-Commerce & Marketplaces

> **eBay Connector**
>
> Synchronize with eBay marketplace:
>
> * List items directly from inventory
> * Update stock levels automatically
> * Track sold items
> * Import purchase history
>
> **Configuration**: eBay Developer credentials and OAuth

### Valuation Tools

> **PriceCharting**
>
> Access video game pricing data:
>
> * Historical price trends
> * Current market values
> * Loose vs. complete pricing
> * Regional variations
>
> **Configuration**: PriceCharting API key

> **UPCitemdb**
>
> Barcode lookup service:
>
> * Product information by UPC/EAN
> * Price comparison data
> * Product specifications
> * Alternative identifiers
>
> **Configuration**: UPCitemdb API key

### Hardware & Labels

> **QR Code Generator**
>
> Generate and print labels:
>
> * Customizable QR codes
> * Label format templates
> * Batch generation
> * Print configuration
>
> **Configuration**: Label size and format preferences

## Setting Up Integrations

### Integration Configuration Screen

Access integrations from the main menu:

```dart theme={null}
// From integrations_screen.dart:39
@override
void initState() {
  super.initState();
  WidgetsBinding.instance.addPostFrameCallback((_) {
    context.read<IntegrationProvider>().loadStatuses();
  });
}
```

The integration screen displays:

* Available integrations grouped by category
* Connection status (linked/unlinked)
* Quick access to configuration

### Basic Configuration Flow

**1. Select Integration**

Navigate to Settings → Integrations and tap on the integration you want to configure.

**2. Enter Credentials**

A configuration sheet will appear requesting:

* API keys or tokens
* Authentication credentials
* Service-specific settings

```dart theme={null}
// From integrations_provider.dart:78
Future<Map<String, dynamic>?> getConfig(String type) async {
  return await _service.getIntegrationConfig(type);
}
```

**3. Test Connection**

Use the test button to verify connectivity:

```dart theme={null}
// From integrations_provider.dart:37
Future<bool> testConnection(String type, Map<String, dynamic> config) async {
  _isTesting = true;
  _lastErrorMessage = "";
  notifyListeners();
  
  try {
    final result = await _service.testIntegration(type, config);
    if (result['success'] == true) {
      return true;
    } else {
      _lastErrorMessage = result['message'] ?? "Unknown error";
      return false;
    }
  } catch (e) {
    _lastErrorMessage = "Server error";
    return false;
  }
}
```

**4. Save Configuration**

Once the test succeeds, save the integration:

```dart theme={null}
// From integrations_provider.dart:83
Future<bool> saveIntegration(String type, Map<String, dynamic> config) async {
  try {
    await _service.saveIntegration(type, config);
    _statuses[type] = true; // Optimistic update
    notifyListeners();
    return true;
  } catch (e) {
    return false;
  }
}
```

A green checkmark will appear indicating the integration is active.

## Integration Details

### Google Gemini Setup

> **Obtaining API Key**
>
> 1. Visit [Google AI Studio](https://makersuite.google.com/app/apikey)
> 2. Create a new API key or use an existing one
> 3. Copy the key
> 4. Paste it into the Gemini integration configuration in Invenicum
> 5. Test the connection to verify

> **Features Enabled**
>
> With Gemini integrated:
>
> * **Smart Descriptions**: Generate item descriptions from images
> * **Categorization**: Auto-suggest categories and tags
> * **Value Estimation**: AI-assisted price recommendations
> * **Search Enhancement**: Natural language queries

### Telegram Bot Configuration

**1. Create Bot**

1. Open Telegram and search for @BotFather
2. Send `/newbot` command
3. Follow prompts to name your bot
4. Receive bot token

**2. Configure Alerts**

In Invenicum, specify:

* Which events trigger notifications
* Alert frequency
* Message templates
* Target chat IDs

**3. Start Bot**

Send a message to your bot to activate it, then enable notifications in Invenicum.

### Email Integration (Resend)

> **Resend Setup**
>
> 1. Sign up at [Resend.com](https://resend.com)
> 2. Create an API key in the dashboard
> 3. Verify your sending domain (or use Resend's test domain)
> 4. Configure sender email address
> 5. Add the API key to Invenicum

> **Email Features**
>
> * **Reports**: Schedule daily, weekly, or monthly inventory reports
> * **Alerts**: Receive notifications for threshold events
> * **Sharing**: Email collection summaries to collaborators
> * **Exports**: Receive CSV/Excel exports via email

## API Integrations

Integrations communicate with external services through the backend API:

```dart theme={null}
// From integrations_service.dart:10
Future<Map<String, dynamic>> testIntegration(
  String type,
  Map<String, dynamic> config,
) async {
  try {
    final response = await _dio.post(
      '/integrations/test',
      data: {'type': type, 'config': config},
    );
    return response.data;
  } on DioException catch (e) {
    return {
      'success': false,
      'message': e.response?.data['message'] ?? 'Connection error',
    };
  }
}
```

### Integration Status

Check which integrations are active:

```dart theme={null}
// From integrations_service.dart:38
Future<Map<String, bool>> getIntegrationStatuses() async {
  final response = await _dio.get('/integrations/status');
  final Map<String, dynamic> rawMap = response.data['data'];
  return rawMap.map((key, value) => MapEntry(key, value as bool));
}
```

Status is displayed with visual indicators on the integrations screen.

## Setting Up Webhooks

Some integrations support webhooks for real-time event notifications:

**1. Generate Webhook URL**

In the integration configuration, generate a unique webhook URL for your account.

**2. Configure External Service**

Copy the webhook URL and add it to the external service's webhook settings.

**3. Select Events**

Choose which events should trigger the webhook:

* Item created
* Item updated
* Item deleted
* Value changed
* Stock threshold crossed

**4. Verify Delivery**

Use the test webhook feature to ensure events are being received.

> [!NOTE]
>
> Webhooks are processed asynchronously to ensure system performance. There may be a slight delay between the event and the webhook delivery.

## OAuth Flows

Some integrations (like eBay) require OAuth authentication:

**1. Initiate OAuth**

Click "Connect with OAuth" in the integration configuration.

**2. Authorize Access**

You'll be redirected to the service's authorization page. Log in and grant permissions.

**3. Callback Processing**

After authorization, you'll be redirected back to Invenicum. The integration will automatically complete the setup.

**4. Token Refresh**

OAuth tokens are automatically refreshed when needed. You won't need to re-authorize unless you revoke access.

## Managing Integrations

### Unlinking an Integration

To disconnect an integration:

```dart theme={null}
// From integrations_provider.dart:60
Future<bool> unlinkIntegration(String type) async {
  try {
    await _service.deleteIntegration(type);
    _statuses[type] = false;
    notifyListeners();
    return true;
  } catch (e) {
    debugPrint("Error unlinking: $e");
    return false;
  }
}
```

1. Open the integration configuration
2. Select "Disconnect" or "Unlink"
3. Confirm the action
4. The integration status will update to inactive

### Reconfiguring Integrations

To update integration settings:

1. Open the integration (even if already linked)
2. Modify configuration values
3. Test the new configuration
4. Save to apply changes

> [!WARNING]
>
> Changing API keys or credentials will immediately affect all features using that integration. Test thoroughly before saving.

## Best Practices

> **Security**
>
> * Store API keys securely (never share)
> * Use environment-specific keys for testing
> * Regularly rotate credentials
> * Review integration permissions periodically
> * Revoke access for unused integrations

> **Performance**
>
> * Enable only integrations you actively use
> * Monitor API rate limits
> * Use webhooks instead of polling when available
> * Cache integration responses when appropriate

> **Reliability**
>
> * Test integrations after configuration changes
> * Set up monitoring for critical integrations
> * Have fallback plans for service outages
> * Keep integration documentation handy

## Troubleshooting

> **Connection Test Failed**
>
> **Possible causes:**
>
> * Invalid API key or credentials
> * Network connectivity issues
> * Service is temporarily down
> * Incorrect configuration format
>
> **Solutions:**
>
> * Verify credentials are correct and active
> * Check your internet connection
> * Review the service's status page
> * Consult integration-specific documentation

> **Integration Works Intermittently**
>
> **Possible causes:**
>
> * Rate limiting by the external service
> * Token expiration (OAuth)
> * Network instability
>
> **Solutions:**
>
> * Check rate limits in service documentation
> * Re-authorize OAuth integrations
> * Monitor network stability
> * Contact support if issues persist

> **Webhook Not Receiving Events**
>
> **Possible causes:**
>
> * Incorrect webhook URL
> * Event type not configured
> * Webhook disabled in external service
> * Firewall blocking requests
>
> **Solutions:**
>
> * Verify webhook URL is correct
> * Check event configuration on both sides
> * Ensure webhook is enabled
> * Review firewall and security settings

## Integration Constants

Integration IDs used in the system:

```dart theme={null}
// Integration type identifiers
static const String gemini = 'gemini';
static const String telegram = 'telegram';
static const String email = 'email';
static const String ebay = 'ebay';
static const String priceCharting = 'priceCharting';
static const String upcitemdb = 'upcitemdb';
static const String qrLabels = 'qrLabels';
```

Reference these IDs when working with the integration API programmatically.

## Next Steps

> **[Plugins](https://lopiv2-invenicum-25.mintlify.site/advanced/plugins.md)**
>
> Extend functionality with custom plugins

> **[Automation](https://lopiv2-invenicum-25.mintlify.site/automation/workflows)**
>
> Create automated workflows using integrations

> **[API Reference](https://lopiv2-invenicum-25.mintlify.site/api/extensions/integrations.md)**
>
> Direct API access for integrations


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.