Complete Tutorial

Tutorial: Building a “StoreBuilder” Integration

This tutorial walks you through creating a complete integration for a fictional e-commerce platform called StoreBuilder.

Prerequisites

• A local Gateway environment
• Access to the Gateway code

---

Step 1: Configuration (Seeders)

First, we register the service and its resources.

1.1 Register Service

Edit database/seeders/ServicesSeeder.php:

[
    'name' => 'StoreBuilder',
    'type' => 'storebuilder',
    'logo' => 'logos/storebuilder.png',
    'oauth_required' => false, // Simple API Key auth
    'active' => true,
    'params' => [
        [
            'name' => 'store_url',
            'type' => 'text',
            'label' => 'Store URL',
            'required' => true
        ],
        [
            'name' => 'api_key',
            'type' => 'password', // Masked secret
            'label' => 'API Key',
            'required' => true
        ]
    ]
]

1.2 define Resources

Edit database/seeders/AppServicesSeeder.php:

[
    'service_type' => 'storebuilder',
    'resources' => [
        [
            'name' => 'get_orders',
            'label' => 'Import Orders',
            'schedulable' => true,
            'params' => [
                [
                    'name' => 'status',
                    'type' => 'select',
                    'label' => 'Import Status',
                    'items' => [
                        ['value' => 'paid', 'label' => 'Paid'],
                        ['value' => 'fulfilled', 'label' => 'Fulfilled']
                    ]
                ]
            ]
        ]
    ]
]

1.3 Apply Changes

php artisan db:seed --class=ServicesSeeder
php artisan db:seed --class=AppServicesSeeder

---

Step 2: Create Integration Class

Create app/Classes/StorebuilderIntegration.php.

<?php

namespace App\Classes;

use App\Contracts\IntegrationInterface;
use App\Classes\Order;
use App\Classes\Item;
use App\Classes\ShippingAddress;
use Illuminate\Support\Facades\Http;

class StorebuilderIntegration implements IntegrationInterface
{
    protected $integration;
    protected $apiKey;
    protected $baseUrl;

    public function __construct($integration)
    {
        $this->integration = $integration;
        $this->apiKey = $integration->configuration['api_key'];
        $this->baseUrl = $integration->configuration['store_url'];
    }

    /**
     * RESOURCE: get_orders
     */
    public function getOrders(array $request)
    {
        // 1. Prepare request
        $status = $request['params']['status'] ?? 'paid';

        // 2. Call API
        $response = Http::withHeaders(['X-API-Key' => $this->apiKey])
            ->get("{$this->baseUrl}/api/v1/orders", [
                'status' => $status,
                'limit' => 50
            ]);

        if ($response->failed()) {
            throw new \Exception("StoreBuilder API fail: " . $response->body());
        }

        // 3. Map Orders
        $orders = [];
        foreach ($response->json()['data'] as $orderData) {
            $orders[] = $this->mapOrder($orderData);
        }

        return $orders;
    }

    /**
     * MAPPER
     */
    public function mapOrder($data)
    {
        $order = new Order();
        $order->ref_number = (string) $data['id'];
        $order->status = $data['status'];
        $order->date = $data['created_at'];

        // Map Address
        $shipping = new ShippingAddress();
        $shipping->name = $data['customer']['name'];
        $shipping->address1 = $data['shipping']['address_1'];
        $shipping->city = $data['shipping']['city'];
        $shipping->state = $data['shipping']['state'];
        $shipping->zip = $data['shipping']['zip'];
        $shipping->country = $data['shipping']['country'];
        $shipping->phone = $data['customer']['phone'];
        $order->shipping_address = $shipping;

        // Map Items
        foreach ($data['items'] as $itemData) {
            $item = new Item();
            $item->sku = $itemData['product_sku'];
            $item->quantity = $itemData['qty'];
            $item->price = $itemData['unit_price'];
            $item->description = $itemData['product_name'];

            $order->items[] = $item;
        }

        return $order;
    }

    // ... Implement other required methods (return empty placeholders if unused)
    public function updateTracking(array $request) { return ['success' => true]; }
    public function syncInventory(array $request) { return ['success' => true]; }
    public function acknowledgeOrders(array $request) { return ['success' => true]; }

    public function rules($resource)
    {
        return [];
    }
}

---

Step 3: Test Integration

1. Go to Gateway UI -> Integrations.
2. Click Add Integration.
3. Select StoreBuilder.
4. Enter test credentials (URL, API Key).
5. Click Save.
6. Once created, click Actions -> Import Orders.
7. Check the logs and see if orders were imported into the Gateway.

---

Conclusion

You have successfully created a basic integration! From here you can:

• Add OAuth2 authentication
• Implement inventory syncing
• Add tracking updates
• Add unit tests