flasho_merchant_sdk

Official Dart/Flutter SDK for the Flasho Merchant API.

Install

Add to your pubspec.yaml:

dependencies:
  flasho_merchant_sdk: ^1.0.0

Then run:

dart pub get
# or
flutter pub get

Quick start

import 'package:flasho_merchant_sdk/flasho_merchant_sdk.dart';

void main() async {
  final flasho = FlashoClient(apiKey: 'flsh_YOUR_KEY');

  // Load everything in one call
  final data = await flasho.account.bootstrap();
  print(data.account.walletBalance); // "10.000"

  // Get a price quote
  final quote = await flasho.pricing.calculate(
    CalculatePriceRequest(
      fromLatitude: 29.3764,
      fromLongitude: 47.9785,
      toLatitude: 29.3117,
      toLongitude: 48.0034,
    ),
  );
  print('Fee: ${quote.price} KWD');

  // Book a delivery
  final delivery = await flasho.deliveries.create(
    CreateDeliveryRequest(
      customerName: 'Ahmed Ali',
      customerNumber: '99887766',
      pickupLatitude: 29.3764,
      pickupLongitude: 47.9785,
      deliveryLatitude: 29.3117,
      deliveryLongitude: 48.0034,
    ),
  );
  print(delivery.orderNumber); // FLH4001
}

Authentication

API key — servers & websites

final flasho = FlashoClient(apiKey: 'flsh_YOUR_KEY');

Generate your key in the Flasho dashboard.

JWT — mobile apps

final flasho = FlashoClient(token: 'placeholder');

final result = await flasho.auth.login(
  email: 'you@example.com',
  password: 'your-password',
);
// Token stored automatically — all calls now use it
print(result.merchant.sellerName);

API reference

flasho.account

Method	Description
bootstrap()	Load account, wallet, branches, pricing, and schedule settings in one call
get()	Merchant profile
listBranches()	Pickup branches
getWallet()	Wallet balance and recent transactions
getPricing()	Distance-based pricing tiers and special zones
getScheduledDeliverySettings()	Check if scheduled delivery is available

flasho.pricing

Method	Description
calculate(request)	Price quote. Set isScheduled: true for the flat scheduled rate

flasho.deliveries

Method	Description
create(request)	Book on-demand, scheduled, or COD delivery
list({status, limit})	List deliveries, newest first
get(id)	Get delivery by ID
poll(id, {interval, timeout, onUpdate})	Poll until terminal state

flasho.auth

Method	Description
login({email, password})	Log in and store JWT automatically

Examples

Cash-on-delivery

final delivery = await flasho.deliveries.create(
  CreateDeliveryRequest(
    customerName: 'Sara Mohammed',
    customerNumber: '66554433',
    pickupLatitude: 29.3764,
    pickupLongitude: 47.9785,
    deliveryLatitude: 29.3117,
    deliveryLongitude: 48.0034,
    collectCash: true,
    totalAmount: '15.750',
  ),
);

Scheduled delivery

final settings = await flasho.account.getScheduledDeliverySettings();
if (!settings.available) throw Exception('Scheduled delivery not enabled');

final delivery = await flasho.deliveries.create(
  CreateDeliveryRequest(
    customerName: 'Ahmed Ali',
    customerNumber: '99887766',
    pickupLatitude: 29.3764,
    pickupLongitude: 47.9785,
    deliveryLatitude: 29.3117,
    deliveryLongitude: 48.0034,
    isScheduled: true,
    scheduledDeliveryAt: DateTime.now().toUtc().add(const Duration(hours: 2)),
  ),
);

Poll until delivered

final finalDelivery = await flasho.deliveries.poll(
  delivery.id,
  interval: const Duration(seconds: 5),
  timeout: const Duration(minutes: 15),
  onUpdate: (d) {
    print('Status: ${d.status.name}');
    if (d.driverName != null) print('Driver: ${d.driverName}');
  },
);

if (finalDelivery.status == DeliveryStatus.delivered) {
  print('Delivered!');
}

Error handling

import 'package:flasho_merchant_sdk/flasho_merchant_sdk.dart';

try {
  final delivery = await flasho.deliveries.create(request);
} on FlashoApiException catch (e) {
  print('API error ${e.statusCode}: ${e.message}');
  if (e.isUnauthorized)    print('Check your API key');
  if (e.isValidationError) print('Invalid request');
  if (e.isNotFound)        print('Not found');
} on FlashoNetworkException catch (e) {
  print('Network error: ${e.message}');
}

Order statuses

pending → requested → accepted → inprogress → pickedup → enroute → delivered

Terminal: delivered · cancelled · rejected · failed

Requirements

• Dart SDK >=3.0.0
• Works on Flutter (iOS, Android, Web, Desktop) and plain Dart

License

MIT