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:

// 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

   // 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:

   // 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:

   // 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
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
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:

// 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:

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

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:

// 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

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:

// 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

Extend functionality with custom plugins

Automation

Create automated workflows using integrations

API Reference

Direct API access for integrations