Integrated Vendors

An Integrated Vendor is an external logistics platform — Lalamove, a courier network, a freight aggregator — that Fleet-Ops talks to via its API. When you assign an order to an integrated vendor, Fleet-Ops relays the order to the partner's platform, the partner dispatches their own driver, and status updates stream back via webhooks while the order's lifecycle continues to live inside Fleet-Ops.

This page covers configuring an integrated vendor in the console and the framework Fleet-Ops uses internally to add new providers — so you can wire up your own.

How It Works

When an order is facilitated by an integrated vendor:

1. Fleet-Ops translates the order's payload into the partner's request format and POSTs it to their API
2. The partner platform allocates one of their drivers and returns a vendor-side reference
3. Fleet-Ops stores the reference and continues tracking the order
4. Status updates from the partner arrive at the configured webhook URL and are written back to the Fleet-Ops order

The Fleet-Ops order remains the source of truth — invoicing, customer notifications, and reporting all run from the local order even though execution happens externally.

Built-In Providers

Out of the box, Fleet-Ops ships with a single integrated vendor implementation:

Additional providers can be added either as Fleet-Ops contributions or as extensions installed from the Extension Marketplace.

Connecting an Integrated Vendor

Edit, sandbox-toggle, and delete actions are all available from the integrated vendor's row in the Vendors list. Deleting an integrated vendor fires the provider's onDeleted callbacks, which typically cancel any open orders on the partner's side.

Data Model

The model is Fleetbase\FleetOps\Models\IntegratedVendor. Key fields:

Service types and supported countries are appended dynamically — they come from the resolved provider's bridge classes (see below) rather than being stored on the row.

The Integrated Vendor Framework

Adding a new provider involves three concerns: the bridge (the API client), optional service-type and market (ISO-2 country) classes, and a registry entry declaring how to wire them together.

1. The bridge — your API client

The bridge is a regular PHP class that talks to the partner's HTTP API. The framework instantiates it via the Laravel container with parameters resolved from the integrated vendor row (typically credentials + sandbox flag + market):

namespace Fleetbase\FleetOps\Integrations\Lalamove;

class Lalamove
{
    public function __construct(
        protected string $apiKey,
        protected string $apiSecret,
        protected bool $sandbox = false,
        protected ?string $market = null,
    ) {
        // Configure HTTP client, signing, etc.
    }

    public function setWebhook(string $webhookUrl): void { /* ... */ }
    public function createOrder(array $payload): array     { /* ... */ }
    public function cancelOrder(string $vendorOrderId): void { /* ... */ }
    public function cancelFromFleetbaseOrder(): void       { /* ... */ }
    // ... whatever the provider's API supports
}

2. Service types and market classes (optional)

If the provider exposes a discoverable list of service types (e.g. Motorcycle Express, Van, Truck 4x4) or operates in specific markets, expose those via two static classes:

class LalamoveServiceType
{
    public static function all(): array
    {
        // return [['code' => 'MOTORCYCLE', 'name' => 'Motorcycle'], ...]
    }
}

class LalamoveMarket
{
    public const markets = [/* ... */];

    public static function codes(): array
    {
        return array_map(fn ($m) => $m['code'], self::markets);
    }
}

These are referenced by the registry as svc_bridge and iso2cc_bridge and surface in the console UI as dropdowns when configuring the vendor.

3. Registry entry

Add an entry to Fleetbase\FleetOps\Support\IntegratedVendors::$supported. The registry tells Fleet-Ops:

• The provider's display name and code
• Which API hosts to use (production and sandbox)
• Which classes implement the bridge, service types, and market list
• Which credential and option fields the console form should render
• How to map fields from the saved IntegratedVendor row into bridge constructor parameters
• Which lifecycle callbacks fire on create / update / delete / cancel

[
    'name'             => 'Lalamove',
    'code'             => 'lalamove',
    'host'             => 'https://rest.lalamove.com/',
    'sandbox'          => 'https://rest.sandbox.lalamove.com/',
    'namespace'        => 'v3',
    'bridge'           => Lalamove::class,
    'svc_bridge'       => LalamoveServiceType::class,
    'iso2cc_bridge'    => LalamoveMarket::class,

    // Console form: secrets
    'credentialParams' => [
        ['key' => 'api_key'],
        ['key' => 'api_secret'],
    ],

    // Console form: options
    'optionParams' => [
        [
            'key'         => 'market',
            'options'     => LalamoveMarket::markets,
            'optionValue' => 'code',
            'optionLabel' => 'key',
        ],
    ],

    // How to construct the bridge from a saved IntegratedVendor row
    'bridgeParams' => [
        'apiKey'    => 'credentials.api_key',
        'apiSecret' => 'credentials.api_secret',
        'sandbox'   => 'sandbox',
        'market'    => 'options.market',
    ],

    // Lifecycle hooks — methods called on the bridge for each event
    'callbacks' => [
        'onCreated'  => ['setWebhook' => ['webhook_url']],
        'onUpdated'  => ['setWebhook' => ['webhook_url']],
        'onDeleted'  => ['cancelFromFleetbaseOrder' => []],
        'onCanceled' => ['cancelFromFleetbaseOrder' => []],
    ],
],

The framework handles the rest:

• The provider appears in the + Add Integrated Vendor picker
• The console renders the credential and option fields
• When a row is saved, the host (or sandbox host) and namespace are populated automatically from the registry
• The bridge is instantiated via Laravel's container with parameters resolved from bridgeParams
• Lifecycle callbacks fire when IntegratedVendor model events occur, calling the named methods on the bridge with resolved arguments

Registering from an extension

If you're shipping a provider as a Fleet-Ops extension, append your registry entry to IntegratedVendors::$supported from your service provider's boot() method. Once installed and booted, the new provider appears in the Add Integrated Vendor picker without changes to Fleet-Ops core.

Routing Orders to an Integrated Vendor

When creating an order, set the integrated vendor as the order's facilitator. At dispatch time, Fleet-Ops detects that the facilitator is an integrated vendor and relays the order via the resolved bridge. From this point on:

• The order continues to live in Fleet-Ops with its normal lifecycle
• Status updates posted to the webhook URL are translated into Fleet-Ops activities
• Driver location, ETA, and POD (when supplied by the provider) are surfaced on the live map
• Cancellation in Fleet-Ops cancels via the provider; cancellation on the provider side cancels in Fleet-Ops

Testing an Integration

Use sandbox mode to develop and test:

1. Get sandbox credentials from the provider
2. Create the integrated vendor with Sandbox toggled on
3. Place test orders against the sandbox vendor — the provider's sandbox typically returns simulated drivers and status events
4. When ready, create a separate integrated vendor record with production credentials and sandbox off

Related Pages

• Vendors — the parent vendor entity (covers internal vendors too)
• Extensions — packaging an integrated vendor as an installable extension