AxessLogistique Dart SDK #

A comprehensive Dart SDK for integrating with the AxessLogistique delivery system. This package provides type-safe methods for creating pickups, tracking delivery status, downloading delivery notes, and managing logistics operations in Tunisia.

✨ Features #

🚚 Create Pickups - Schedule new delivery pickups with full address details
📊 Track Status - Get real-time status updates for individual or multiple pickups
📄 Download Documents - Retrieve delivery notes and invoices as PDF files
🌍 Zone Management - Access available delivery zones and regions
🔄 Batch Operations - Handle multiple pickups efficiently
🛡️ Type Safety - Full Dart type safety with comprehensive error handling
🌐 Environment Support - Test and production environment configurations
📱 Cross-Platform - Works with Dart, Flutter, and server-side applications

📦 Installation #

Add this package to your pubspec.yaml:

dependencies:
  axesslogistique_dark_sdk: ^1.0.0

Then run:

dart pub get

For Flutter Projects #

flutter pub add axesslogistique_dark_sdk

🚀 Quick Start #

Basic Usage #

import 'package:axesslogistique_dark_sdk/axesslogistique_dark_sdk.dart';

void main() async {
  // Initialize the client
  final client = AxessLogistiqueClient(
    Environment.test, // Use Environment.prod for production
    'YOUR_API_TOKEN',
  );

  // Create a pickup
  final pickup = await client.createPickup(PickupRequest(
    adresseSource: '123 Rue de la Paix',
    gouvernoratSource: 'Tunis',
    delegationSource: 'Carthage',
    localiteSource: 'Sidi Bou Said',
    nomContactSource: 'Ahmed Ben Ali',
    dateEnlevement: '2024-01-20',
    telContactSource: '+21612345678',
    adresseDestination: '456 Avenue Habib Bourguiba',
    gouvernoratDestination: 'Sfax',
    delegationDestination: 'Sfax Ville',
    localiteDestination: 'Sfax Centre',
    nomResponsableDestination: 'Fatma Ben Salem',
    telContactDestination: '+21687654321',
    nomProduit: 'Smartphone Samsung Galaxy S23',
    description: 'Smartphone neuf avec garantie',
    reference: 'CMD-2024-001',
    quantite: 1,
    fragile: true,
    prixTotal: 2500.0,
    livraisonGratuite: false,
    produitEchange: false,
  ));

  print('Pickup created: ${pickup.trackingNumber}');
}

Complete Example #

See the example directory for a comprehensive usage example.

📚 API Reference #

Environment Configuration #

enum Environment { test, prod }

// Test environment
final testClient = AxessLogistiqueClient(Environment.test, 'your-token');

// Production environment
final prodClient = AxessLogistiqueClient(Environment.prod, 'your-token');

Creating Pickups #

final request = PickupRequest(
  // Source address (required)
  adresseSource: '123 Rue de la Paix',
  gouvernoratSource: 'Tunis',
  delegationSource: 'Carthage',
  localiteSource: 'Sidi Bou Said',
  nomContactSource: 'Ahmed Ben Ali',
  dateEnlevement: '2024-01-20',
  telContactSource: '+21612345678',

  // Destination address (required)
  adresseDestination: '456 Avenue Habib Bourguiba',
  gouvernoratDestination: 'Sfax',
  delegationDestination: 'Sfax Ville',
  localiteDestination: 'Sfax Centre',
  nomResponsableDestination: 'Fatma Ben Salem',
  telContactDestination: '+21687654321',

  // Optional warehouse ID
  idEntrepot: 123,

  // Product details (required)
  nomProduit: 'Product Name',
  description: 'Product description',
  reference: 'REF-123',
  quantite: 1,
  fragile: false,
  prixTotal: 100.0,
  livraisonGratuite: false,
  produitEchange: false,
);

final response = await client.createPickup(request);

Tracking Pickups #

// Get single pickup status
final status = await client.getPickupStatus('TRK123456789');

// Get multiple pickup statuses
final statuses = await client.getManyPickupStatuses([
  'TRK123456789',
  'TRK987654321',
]);

Downloading Documents #

import 'dart:io';

// Download delivery note as PDF
final pdfBytes = await client.downloadBonDeCommande('TRK123456789');

// Save to file
final file = File('delivery_note.pdf');
await file.writeAsBytes(pdfBytes);

Getting Zones #

final zones = await client.getZones();
print('Available zones: ${zones['zones']}');

🔧 Advanced Usage #

Error Handling #

try {
  final pickup = await client.createPickup(request);
  print('Success: ${pickup.trackingNumber}');
} catch (e) {
  if (e.toString().contains('Invalid token')) {
    print('Authentication failed');
  } else if (e.toString().contains('Network')) {
    print('Network error');
  } else {
    print('Unexpected error: $e');
  }
}

Retry Logic #

Future<PickupResponse> createPickupWithRetry(
  AxessLogistiqueClient client,
  PickupRequest request, {
  int maxRetries = 3,
  Duration delay = const Duration(seconds: 2),
}) async {
  for (int attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await client.createPickup(request);
    } catch (e) {
      if (attempt == maxRetries) rethrow;
      await Future.delayed(delay);
    }
  }
  throw Exception('All retry attempts failed');
}

Batch Operations #

Future<List<PickupResponse>> createBatchPickups(
  AxessLogistiqueClient client,
  List<PickupRequest> requests,
) async {
  final responses = <PickupResponse>[];

  for (final request in requests) {
    try {
      final response = await client.createPickup(request);
      responses.add(response);
    } catch (e) {
      print('Failed to create pickup: $e');
    }
  }

  return responses;
}

🌍 Environments #

Environment	Base URL	Description
`Environment.test`	`https://test.axesslogistique.com`	Testing environment
`Environment.prod`	`https://fast.axesslogistique.com`	Production environment

🧪 Testing #

Running Tests #

# Run all tests
dart test

# Run tests with coverage
dart test --coverage=coverage

# Run specific test file
dart test test/axesslogistique_dark_sdk_test.dart

# Run tests in watch mode
dart test --watch

Test Coverage #

The SDK includes comprehensive unit tests covering:

✅ Environment configuration
✅ PickupRequest creation and serialization
✅ PickupResponse deserialization
✅ PickupStatus parsing
✅ Client initialization and configuration
✅ JSON structure validation
✅ Error handling scenarios

🛠️ Development #

Prerequisites #

Dart SDK 3.7.2 or higher
Git

Setup #

# Clone the repository
git clone https://github.com/bujupah/axesslogistique-dart-sdk.git
cd axesslogistique-dart-sdk

# Install dependencies
dart pub get

# Run tests
dart test

# Run example
dart run example/axesslogistique_dark_sdk_example.dart

Code Quality #

# Analyze code
dart analyze

# Format code
dart format .

# Run linter
dart run lints:check

📋 Data Models #

PickupRequest #

class PickupRequest {
  final String adresseSource;
  final String gouvernoratSource;
  final String delegationSource;
  final String localiteSource;
  final String nomContactSource;
  final String dateEnlevement;
  final String telContactSource;
  final String adresseDestination;
  final String gouvernoratDestination;
  final String delegationDestination;
  final String localiteDestination;
  final String nomResponsableDestination;
  final String telContactDestination;
  final int? idEntrepot; // Optional
  final String nomProduit;
  final String description;
  final String reference;
  final int quantite;
  final bool fragile;
  final double prixTotal;
  final bool livraisonGratuite;
  final bool produitEchange;
}

PickupResponse #

class PickupResponse {
  final int id;
  final String trackingNumber;
  final String status;
  final String reference;
  final double prixSousTotal;
  final double fraisTotal;
  final double prixTotal;
  final String destination;
  final String? externalCode; // Optional
  final String expediteur;
}

PickupStatus #

class PickupStatus {
  final String pickupId;
  final String trackingNumber;
  final String statusv1;
  final String status;
  final String? subStatus; // Optional
  final String? livreur; // Optional
  final String? livreurTel; // Optional
  final String? reason; // Optional
  final String? reference; // Optional
  final String clientName;
  final String clientPhone;
  final String updatedAt;
}

🤝 Contributing #

We welcome contributions! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for new functionality
Run the test suite (dart test)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines #

Follow Dart style guidelines
Add tests for new features
Update documentation as needed
Ensure all tests pass before submitting

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support #

Getting Help #

📖 Documentation: Check this README and example files
🐛 Issues: Create an issue on GitHub
💬 Discussions: Use GitHub Discussions for questions
📧 Email: Contact Axess Logistique support

Common Issues #

Issue	Solution
Invalid token error	Check your API token and environment
Network errors	Verify internet connection and API endpoints
Missing required fields	Ensure all required PickupRequest fields are provided
PDF download fails	Check tracking number validity

Made with ❤️ for the Tunisian logistics community

axesslogistique_dark_sdk 1.0.0 axesslogistique_dark_sdk: ^1.0.0 copied to clipboard

Metadata