Skip to main content

​
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

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

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

  • Store API keys securely (never share)
  • Use environment-specific keys for testing
  • Regularly rotate credentials
  • Review integration permissions periodically
  • Revoke access for unused integrations
  • Enable only integrations you actively use
  • Monitor API rate limits
  • Use webhooks instead of polling when available
  • Cache integration responses when appropriate
  • Test integrations after configuration changes
  • Set up monitoring for critical integrations
  • Have fallback plans for service outages
  • Keep integration documentation handy

​
Troubleshooting

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

Build docs developers (and LLMs) love

Get started for freeTalk to us