Step 3. Integration Classes

Step 3: Integration Classes

The integration class contains the core logic for communicating with the external platform and mapping data to the Gateway’s standardized format.

Class Location & Naming

Directory: app/Classes/ Naming Convention: PascalCase of service type + Integration

Example: myplatform -> MyplatformIntegration

Structure

<?php

namespace App\Classes;

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

class MyplatformIntegration implements IntegrationInterface
{
    protected $integration;
    protected $config;

    public function __construct($integration)
    {
        $this->integration = $integration;
        $this->config = $integration->configuration;
    }

    // Required methods below...
}

IntegrationInterface

You must implement the App\Contracts\IntegrationInterface contract.

1. getOrders(array $request)

Fetch orders from the platform.

public function getOrders(array $request)
{
    // 1. Get parameters (e.g., status filter)
    $status = $request['params']['order_status'] ?? 'open';

    // 2. Fetch from External API
    $response = Http::withToken($this->config['access_token'])
        ->get('https://api.platform.com/orders', [
            'status' => $status
        ]);

    $ordersData = $response->json()['orders'];

    // 3. Map to standard Order objects
    $orders = [];
    foreach ($ordersData as $orderData) {
        $orders[] = $this->mapOrder($orderData);
    }

    return $orders;
}

2. mapOrder($data)

Convert platform-specific data to standardized App\Classes\Order object.

public function mapOrder($data)
{
    $order = new Order();

    $order->ref_number = $data['id'];
    $order->status = $data['status'];
    $order->date = $data['created_at'];

    // Map Address
    $shipping = new ShippingAddress();
    $shipping->name = $data['shipping_address']['name'];
    $shipping->address1 = $data['shipping_address']['address1'];
    $shipping->city = $data['shipping_address']['city'];
    // ...
    $order->shipping_address = $shipping;

    // Map Items
    foreach ($data['line_items'] as $itemData) {
        $item = new Item();
        $item->sku = $itemData['sku'];
        $item->quantity = $itemData['quantity'];
        $item->price = $itemData['price'];

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

    return $order;
}

3. updateTracking(array $request)

Send tracking number back to platform.

public function updateTracking(array $request)
{
    $orderId = $request['params']['order_ref']; // This matches ref_number
    $tracking = $request['params']['tracking_number'];
    $carrier = $request['params']['carrier'];

    $response = Http::post("https://api.platform.com/orders/{$orderId}/fulfillments", [
        'tracking_number' => $tracking,
        'tracking_company' => $carrier
    ]);

    return [
        'success' => $response->successful(),
        'message' => $response->successful() ? 'Tracking updated' : $response->body()
    ];
}

4. syncInventory(array $request)

Update stock levels.

public function syncInventory(array $request)
{
    $sku = $request['params']['sku'];
    $quantity = $request['params']['quantity'];

    // Often requires looking up product ID by SKU first
    $productId = $this->findProductBySku($sku);

    if (!$productId) {
        return ['success' => false, 'message' => 'Product not found'];
    }

    $response = Http::post("https://api.platform.com/products/{$productId}/inventory", [
        'available' => $quantity
    ]);

    return ['success' => $response->successful()];
}

5. acknowledgeOrders(array $request)

Mark orders as imported/processed (if platform supports it).

public function acknowledgeOrders(array $request)
{
    // Some platforms require explicit acknowledgement
    // If not supported, return true
    return ['success' => true];
}

6. rules($resource)

Define validation rules for actions.

public function rules($resource)
{
    if ($resource === 'get_orders') {
        return [
            'order_status' => 'required|array'
        ];
    }

    return [];
}

---

Data Mapping Reference

Use these standard classes to ensure compatibility with the WMS.

App\Classes\Order

Property	Type	Description
ref_number	string	Unique order ID from platform
date	string	Order creation date
status	string	Original status
items	array	Array of Item objects
shipping_address	object	ShippingAddress object
billing_address	object	BillingAddress object
shipping_service	object	ShippingService object

App\Classes\Item

Property	Type	Description
sku	string	Stock Keeping Unit
quantity	int	Quantity ordered
price	float	Unit price
description	string	Product name

View Conventions and Best Practices