Integration Development

Integration Development

Learn how to create custom integrations for e-commerce platforms in the Gateway. This guide covers the complete process from seeder configuration to integration class implementation.

Overview

Creating a Gateway integration involves three main steps:

1. Seeders Configuration

Define integration parameters and resources in ServicesSeeder.php and AppServicesSeeder.php.

2. OAuth2 Setup

Implement OAuth2 authorization if your platform requires it, using AuthorizationServiceTrait.

3. Integration Classes

Create the integration class implementing IntegrationInterface with required methods.

Architecture

graph TD
    A[E-commerce Platform] -->|OAuth2| B[Gateway]
    B -->|Background Jobs| C[Integration Class]
    C -->|API Calls| A
    C -->|Map Data| D[Standard Classes]
    D -->|Send to| E[WMS/App]

    F[ServicesSeeder] -->|Configure| B
    G[AppServicesSeeder] -->|Define Resources| B

Integration Components

Component	Purpose	File Location
Service Seeder	Define integration metadata & parameters	database/seeders/ServicesSeeder.php
App Service Seeder	Define resources & subscriptions	database/seeders/AppServicesSeeder.php
Authorization Trait	Implement OAuth2 flows	app/Traits/AuthorizationServiceTrait.php
Integration Class	Core integration logic	app/Classes/{Platform}Integration.php
Data Mapping Classes	Standardized data structures	app/Classes/{Order,Item,Address}.php

Quick Start

1. Add Service Configuration

database/seeders/ServicesSeeder.php

[
    'name' => 'MyPlatform',
    'type' => 'myplatform',
    'oauth_required' => true,
    'params' => [
        [
            'name' => 'api_key',
            'type' => 'text',
            'label' => 'API Key',
            'required' => true
        ]
    ]
]

2. Define Resources

database/seeders/AppServicesSeeder.php

[
    'service_type' => 'myplatform',
    'resources' => [
        [
            'name' => 'get_orders',
            'label' => 'Import Orders',
            'schedulable' => true
        ]
    ]
]

3. Create Integration Class

app/Classes/MyPlatformIntegration.php

class MyPlatformIntegration implements IntegrationInterface
{
    public function getOrders(array $request)
    {
        // Fetch orders from platform API
    }

    public function mapOrder($orderData)
    {
        // Map to Gateway Order class
    }

    // ... other required methods
}

Required Methods

All integrations must implement 6 required methods from IntegrationInterface:

Method	Purpose	Returns
getOrders()	Fetch orders from platform	Array of mapped orders
mapOrder()	Convert platform order to Gateway format	Order object
acknowledgeOrders()	Mark orders as acknowledged	Status response
updateTracking()	Send tracking updates	Status response
syncInventory()	Sync inventory levels	Status response
rules()	Validation rules	Array of validation rules

View complete IntegrationInterface →

Standardized Data Classes

All integrations use standardized Gateway classes:

• Order - Order data
• Item - Line item data
• Address - Base address class
• ShippingAddress - Shipping address
• BillingAddress - Billing address
• ShippingService - Shipping options
• Product - Product/inventory data
• Shipment - Tracking data

Learn about data mapping →

Development Workflow

1. Research Platform API

   • Review API documentation
   • Identify authentication method
   • Map API endpoints to Gateway resources

2. Configure Seeders

   • Add service in ServicesSeeder.php
   • Define resources in AppServicesSeeder.php
   • Run migrations: php artisan db:seed

3. Implement OAuth2 (if required)

   • Add authorization methods
   • Implement missingParameters()
   • Implement addParametersRequest()

4. Create Integration Class

   • Implement required methods
   • Map platform data to Gateway classes
   • Add error handling

5. Test Integration

   • Install via Gateway UI
   • Test order import
   • Test tracking updates
   • Verify data mapping

6. Deploy

   • Commit code
   • Deploy to staging
   • Run seeders
   • Test with real account

Best Practices

1. Follow Naming Conventions

✅ Service Type: lowercase, no spaces (shopifyv2, amazon, woocommerce)

✅ Integration Class: PascalCase + Integration (ShopifyV2Integration)

✅ Resource Names: snake_case (get_orders, update_tracking)

2. Use Spec-based Parameters

[
    'name' => 'order_status',
    'type' => 'multiselect',
    'label' => 'Order Status',
    'required' => true,
    'items' => [
        ['value' => 'open', 'label' => 'Open'],
        ['value' => 'closed', 'label' => 'Closed']
    ]
]

3. Implement Robust Error Handling

try {
    $orders = $this->apiClient->get('orders');
} catch (\Exception $e) {
    Log::error("Failed to fetch orders: " . $e->getMessage());
    return ['error' => $e->getMessage()];
}

4. Use Token Auto-refresh

if ($this->accessToken->expires_at < now()->addMinutes(5)) {
    $this->refreshAccessToken();
}

Examples

View existing integrations for reference:

• Shopify V2: app/Classes/ShopifyV2Integration.php
• Amazon: app/Classes/AmazonIntegration.php
• WooCommerce: app/Classes/WooCommerceIntegration.php

Next Steps

• Step 1: Configure Seeders
• Step 2: Implement OAuth2
• Step 3: Create Integration Class
• View Development Conventions
• Follow Complete Tutorial