Fuel Integrations

Fleet-Ops fuel integrations connect external fuel card providers, station networks, onsite fuel management systems, and billing APIs to Fleet-Ops. PetroApp ships as the native example integration, and extensions can register additional providers through the same framework.

Fuel integrations are split into three records:

Provider transactions are the import ledger. Fuel Reports are the operational records. Imported provider transactions appear in Fleet-Ops → Management → Fuel Transactions. Matched transactions can create or update linked Fuel Reports, while unmatched transactions remain available for review.

How Extensions Register Providers

An extension registers a provider descriptor from its Laravel service provider. The descriptor tells Fleet-Ops how to display the provider, which credentials to collect, and which adapter class handles API calls.

namespace Vendor\FuelProvider\Providers;

use Fleetbase\FleetOps\Support\FuelProviders\FuelProviderDescriptor;
use Fleetbase\FleetOps\Support\FuelProviders\FuelProviderRegistry;
use Fleetbase\Providers\CoreServiceProvider;
use Vendor\FuelProvider\Support\AcmeFuelProvider;

class AcmeFuelProviderServiceProvider extends CoreServiceProvider
{
    public function register(): void
    {
        $this->callAfterResolving(FuelProviderRegistry::class, function (FuelProviderRegistry $registry) {
            if ($registry->has('acme_fuel')) {
                return;
            }

            $registry->register(new FuelProviderDescriptor([
                'key' => 'acme_fuel',
                'label' => 'Acme Fuel',
                'type' => 'extension',
                'category' => 'Fuel card integration',
                'icon' => 'gas-pump',
                'driver_class' => AcmeFuelProvider::class,
                'description' => 'Imports fuel card transactions from Acme Fuel.',
                'docs_url' => 'https://example.com/docs',
                'required_fields' => [
                    [
                        'name' => 'api_key',
                        'label' => 'API Key',
                        'type' => 'password',
                        'required' => true,
                    ],
                ],
                'capabilities' => ['vehicles', 'transactions', 'stations'],
                'sync_defaults' => [
                    'window_days' => 7,
                    'matching_order' => ['provider_vehicle_id', 'internal_number', 'plate_number', 'vehicle_card_id'],
                    'auto_create_fuel_reports' => true,
                ],
                'setup_instructions' => [
                    'Create or copy an API credential from Acme Fuel.',
                    'Paste the credential into Fleet-Ops and test the connection.',
                    'Choose the default sync window and matching identifiers.',
                ],
            ]));
        });
    }
}

Once the package is installed and its service provider is loaded, the provider appears in Fleet-Ops → Connectivity → Fuel Integrations alongside PetroApp. No Fleet-Ops core config edit is required when the descriptor fits the built-in setup schema.

Adapter Contract

Provider adapters implement Fleetbase\FleetOps\Contracts\FuelProvider. Most adapters should extend Fleet-Ops' base fuel provider class and implement the provider-specific API calls.

Required methods:

public function key(): string;
public function name(): string;
public function authenticate(FuelProviderConnection $connection): array;
public function testConnection(FuelProviderConnection $connection): array;
public function listVehicles(FuelProviderConnection $connection, array $options = []): Collection;
public function listTransactions(FuelProviderConnection $connection, Carbon $from, Carbon $to, array $options = []): Collection;
public function listStations(FuelProviderConnection $connection, array $options = []): Collection;
public function pushTrip(FuelProviderConnection $connection, array $trip): array;
public function syncVehicle(FuelProviderConnection $connection, array $vehicle): array;
public function webhookPayloadToTransaction(FuelProviderConnection $connection, array $payload): ?array;

If a provider does not support optional write-back behavior, return an empty array or null for those methods.

Transaction Normalization

listTransactions() should return a collection of normalized arrays. Fleet-Ops handles idempotent upserts, matching, linked fuel report creation, and import events after the adapter returns normalized payloads.

Important fields:

When a provider does not expose a stable transaction ID, generate a deterministic hash from immutable transaction fields so repeated syncs update the same Fleet-Ops transaction.

Sync Flow

1. Fleet-Ops syncs a provider connection by date window.
2. The adapter returns normalized transactions.
3. Fleet-Ops upserts each FuelProviderTransaction.
4. Fleet-Ops attempts to match the transaction to vehicles, orders, and drivers.
5. Matched transactions can create linked FuelReport records.
6. Unmatched transactions remain in Management → Fuel Transactions for manual matching, review, reprocessing, or ignoring.
7. Events are fired for import, match, unmatched, and fuel-report-created outcomes.

Use FuelProviderTransactionImported, FuelProviderTransactionMatched, FuelProviderTransactionUnmatched, and FuelReportCreatedFromProvider if your extension needs to add client-specific review, reconciliation, or fraud workflows.

Operator Workflow

1. Open Connectivity → Fuel Integrations.
2. Select a provider, enter credentials, test the connection, and save sync settings.
3. Run a manual sync or wait for the scheduled sync window.
4. Review imported provider bills in Management → Fuel Transactions.
5. Match transactions to vehicles, orders, or trips when automatic matching cannot resolve them.
6. Use linked Fuel Reports for operations, analytics, and downstream workflows.