Implement robust error handling and configuration for Logistics API interactions

- Introduced `LogisticsApiException` to handle connection and request errors with user-friendly messages in French.
- Updated `LogisticsService` to include configurable timeout, connection timeout, retry attempts, and sleep duration for retries.
- Enhanced error handling in Filament pages to catch `LogisticsApiException` and provide clear feedback to users.
- Updated `.env` and `config/logistics.php` to support new configuration options.
- Added logging for failed API requests in `api_request_logs`.
- Created comprehensive API documentation for Logistics endpoints.

tests/Feature/LogisticsServiceTest.php

@@ -1,6 +1,9 @@
 <?php
 
+use App\Exceptions\LogisticsApiException;
 use App\Services\LogisticsService;
+use Illuminate\Http\Client\ConnectionException;
+use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Http;
 
 beforeEach(function () {
@@ -8,6 +11,10 @@ beforeEach(function () {
         'logistics.base_url' => 'http://test-server.local',
         'logistics.api_key' => 'test-api-key',
         'logistics.folder' => 'testfolder',
+        'logistics.timeout' => 30,
+        'logistics.connect_timeout' => 10,
+        'logistics.retry.times' => 1,
+        'logistics.retry.sleep_ms' => 0,
     ]);
 });
 
@@ -123,3 +130,57 @@ it('returns fallback data when API returns empty response', function () {
     expect($result)->toHaveKey('error')
         ->and($result['metadata']['issuccess'])->toBeFalse();
 });
+
+it('throws LogisticsApiException on connection timeout', function () {
+    Http::fake(fn () => throw new ConnectionException('Connection timed out'));
+
+    $service = app(LogisticsService::class);
+    $service->tablesList();
+})->throws(LogisticsApiException::class, "L'API Logistics est injoignable");
+
+it('throws LogisticsApiException on general request failure', function () {
+    Http::fake(fn () => throw new \RuntimeException('Server error'));
+
+    $service = app(LogisticsService::class);
+    $service->tablesList();
+})->throws(LogisticsApiException::class, "La requete vers l'API Logistics a echoue");
+
+it('logs failed requests to api_request_logs as valid JSON', function () {
+    Http::fake(fn () => throw new ConnectionException('Connection timed out'));
+
+    $service = app(LogisticsService::class);
+
+    try {
+        $service->tablesList();
+    } catch (LogisticsApiException) {
+        // expected
+    }
+
+    $this->assertDatabaseHas('api_request_logs', [
+        'endpoint' => 'tables_list',
+        'response_status' => 0,
+    ]);
+
+    $log = DB::table('api_request_logs')->where('endpoint', 'tables_list')->first();
+    $decoded = json_decode($log->response_data, true);
+
+    expect($decoded)->toBeArray()
+        ->and($decoded)->toHaveKey('error');
+});
+
+it('includes endpoint info in LogisticsApiException', function () {
+    Http::fake(fn () => throw new ConnectionException('Connection timed out'));
+
+    $service = app(LogisticsService::class);
+
+    try {
+        $service->artList(['search' => 'test']);
+    } catch (LogisticsApiException $e) {
+        expect($e->endpoint)->toBe('art_list')
+            ->and($e->params)->toBe(['search' => 'test']);
+
+        return;
+    }
+
+    $this->fail('Expected LogisticsApiException was not thrown');
+});