Integration Management

An integration, also called third-party, is a software component that allows different applications or systems to communicate and work together. Integrations enable businesses to connect their platforms with our services.

Key Concepts

Providers vs Integrations

Understanding the distinction between providers and integrations :

An Integration (e.g., "Uber Eats") is linked to a Provider (e.g., OrderProvider with name UBER_EATS). This separation allows:

• Clean display names and branding for the marketplace
• Flexible configuration per integration

Provider Types

Integration Categories

Integrations are organized into categories for the marketplace:

• accounting - Accounting software integrations
• stock - Inventory management
• digital_receipt - Digital receipt providers
• management - Business management tools
• staff_management - Staff and HR tools
• loyalty - Loyalty programs
• order - Order providers (delivery platforms)
• payment - Payment providers
• KDS - Kitchen Display Systems

Admin App: Integration Management

The Admin app (apps/admin) provides comprehensive tools for managing integrations.

Location / Third-Party Tab

This tab displays all providers configured for a specific location:

• Order Providers: Activate/deactivate delivery platforms
• Consumers: Manage API access for third-party services
• Loyalty Providers: Enable/disable loyalty programs
• Payment Providers: Configure payment integrations

From here, you can:

• Activate or deactivate a provider for the location
• Configure provider-specific settings
• Manage API keys and credentials

Third-Party Administration Pages

Base path: /third-parties/

1. Links/Connectors Management

Create and configure the underlying providers (connectors):

2. Integrations Configuration

Path: /third-parties/integrations/configuration/

Manage integrations (the user-facing entities):

When creating/editing an integration, you can:

• Set name, description, and branding (icons, logos)
• Associate a provider (Consumer, OrderProvider, LoyaltyService, or Recipient)
• Assign to categories
• Configure the activation type (API key, webhook, boolean toggle, etc.)

3. Marketplace Management

Path: /third-parties/integrations/marketplace

Control how integrations appear in the backoffice marketplace:

• Set display order within categories
• Show/hide integrations from the marketplace
• Configure integration visibility per category

Technical Architecture

Package Structure

The integration logic lives in the package integration:

packages/integration/src/
├── accounting/           # Accounting provider services functions
├── consumer-key/         # API key generation services functions
├── location/             # Location-level integration queries
│   ├── location.schema.ts
│   └── location.service.ts   # getLocationIntegrationList()
├── third-party/          # Third-party API services
│   ├── v2/
│   │   └── third-party.service.ts  # getV2IntegrationList()
│   └── utils/
├── webhook-integrations/ # Webhook management
├── integrations.ts       # Static integration configuration
└── schema.ts             # Core schemas and types

Database Models

Core Entity Relationships

Here is a simplified overview of the core Integration model and its relationships with providers and categories:

Integration
    ├── Consumer (API consumer)
    ├── OrderProvider (delivery platform)
    ├── LoyaltyService (loyalty provider)
    ├── Recipient (webhook recipient)
    ├── Accounting (accounting provider)
    └── IntegrationCategoryLink[] → IntegrationCategory

Key Models

Here is a summary of the main database models involved in integrations:

Configuration Types

Integrations support different activation mechanisms available for the user when enabling an integration on the backoffice:

API Endpoints

tRPC Router

Location: apps/admin/src/server/trpc/router/integration/integrations.router.ts

Key procedures:

• paginatedIntegrationList - List integrations with pagination
• getMarketPlaceIntegrations - Marketplace-ready integrations
• getConsumerList / getRecipientList / getOrderProviderList / getLoyaltyProviderList - Fetch provider lists
• createIntegration / updateIntegration - CRUD operations
• countIncompleteIntegrations - Track incomplete setups

Third-Party Endpoint (POS)

The POS team expects to display all integrations on the POS, and also display connected integrations for a single location. This page aims to manage the integrations.

The POS fetches integrations via the POS API endpoint : v2/third-party

This returns active/inactive integrations for the location.

Workflow: Adding a New Integration

Step 1: Create the Provider

If the provider doesn't exist yet:

1. Go to the appropriate links page (e.g., /third-parties/links/consumers for a consumer provider)
2. Create the provider with required configuration
3. Set up authentication, scopes, or webhook secrets as needed (e.g., name for consumers, HMAC secret for recipients)

Step 2: Create the Integration

1. Navigate to /third-parties/integrations/configuration/create

2. Create a new integration by filling the mandatory following fields:

   • Name, displayed name and category
   • Description
   • Documentation and website URLs
   • Select the associated provider

3. Assign categories

4. Configure the activation type:

   • For consumers, select API_KEY_GENERATION and link the provider
   • For webhook-based providers, select WEBHOOK_CODE_ACTIVATION and link the recipient provider
   • For simple toggles, select BOOLEAN_ACTIVATION

5. Save the integration

Step 3: Add to Marketplace

1. Go to /third-parties/integrations/marketplace
2. Find your integration in the corresponding category list
3. Set the display order (drag and drop)

Step 4: Enable at Location Level

1. Go to Location settings - Third-party tab
2. Find the integration/provider
3. Activate the integration for the location

User Workflow (Backoffice)

From a user perspective in the backoffice:

1. Discover: Browse the marketplace to find integrations
2. Connect: Click to connect an integration
3. Configure: Provide credentials, API keys, or settings
4. Manage: View status, update settings, or disconnect

Troubleshooting

Integration not appearing in marketplace?

• Check if it's linked to a category in admin
• Verify it's not marked as hidden
• Check marketplace ordering

Integration shows as inactive?

• Verify the provider is properly associated
• Check location-level configuration
• Ensure required configs exist (e.g., OrderProviderConfig for order providers)

Incomplete integrations?

• Visit /third-parties/integrations/configuration/incomplete
• Add missing icons, descriptions, or provider associations