Sysix · Sysix · Oct 21, 2025 · Oct 15, 2025 · Oct 16, 2025
diff --git a/psalm.xml b/psalm.xml
@@ -18,6 +18,7 @@
     <issueHandlers>
         <PropertyNotSetInConstructor errorLevel="suppress" />
         <DeprecatedMethod errorLevel="suppress" />
+        <DeprecatedTrait errorLevel="suppress" />
         <RedundantPropertyInitializationCheck errorLevel="suppress" />
         <MissingOverrideAttribute errorLevel="suppress" />
         <ClassMustBeFinal>

diff --git a/src/Clients/Traits/DocumentClientTrait.php b/src/Clients/Traits/DocumentClientTrait.php
@@ -5,33 +5,26 @@
 namespace Sysix\LexOffice\Clients\Traits;
 
 use Psr\Http\Message\ResponseInterface;
-use Sysix\LexOffice\Clients\File;
-use Sysix\LexOffice\Utils;
 
+/**
+ * @deprecated use the FileClientTrait instead
+ */
 trait DocumentClientTrait
 {
+    use FileClientTrait;
+
     public function document(string $id, bool $asContent = false, string $acceptHeader = '*/*'): ResponseInterface
     {
-        $response = $this->api
-            ->newRequest('GET', $this->resource . '/' . rawurlencode($id) . '/document')
-            ->getResponse();
+        trigger_error(__METHOD__.' should not be called anymore, in future versions this method WILL not exist', E_USER_DEPRECATED);
 
         if ($asContent === false) {
-            return $response;
-        }
-
-        if ($response->getStatusCode() !== 200) {
-            return $response;
-        }
+            $response = $this->api
+                ->newRequest('GET', $this->resource . '/' . rawurlencode($id) . '/document')
+                ->getResponse();
 
-        $content = Utils::getJsonFromResponse($response);
-
-        if ($content === null || !is_object($content) || !property_exists($content, 'documentFileId') || !is_string($content->documentFileId)) {
             return $response;
         }
 
-        $fileClient = new File($this->api);
-
-        return $fileClient->get($content->documentFileId, $acceptHeader);
+        return $this->file($id, $acceptHeader);
     }
 }
diff --git a/src/Clients/Traits/FileClientTrait.php b/src/Clients/Traits/FileClientTrait.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sysix\LexOffice\Clients\Traits;
+
+use Psr\Http\Message\ResponseInterface;
+
+trait FileClientTrait
+{
+    public function file(string $id, string $acceptHeader = '*/*'): ResponseInterface
+    {
+        $this->api->newRequest('GET', $this->resource . '/' . rawurlencode($id) . '/file');
+
+        return $this->api
+            ->setRequest($this->api->getRequest()->withHeader('Accept', $acceptHeader))
+            ->getResponse();
+    }
+}
diff --git a/tests/Clients/CreditNoteTest.php b/tests/Clients/CreditNoteTest.php
@@ -143,6 +143,8 @@ public function testGetVoucherListClient(): void
 
     public function testDocument(): void
     {
+        $this->expectDeprecationV1Warning('document');
+
         [$api, $stub] = $this->createClientMockObject(CreditNote::class);
 
         $response = $stub->document('resource-id');
@@ -158,38 +160,33 @@ public function testDocument(): void
 
     public function testDocumentContent(): void
     {
-        [$api, $stub] = $this->createClientMultiMockObject(
-            CreditNote::class,
-            [
-                new Response(200, ['Content-Type' => 'application/json'], '{"documentFileId": "fake-id"}'),
-                new Response()
-            ]
-        );
+        $this->expectDeprecationV1Warning('document');
+
+        [$api, $stub] = $this->createClientMockObject(CreditNote::class);
 
         $response = $stub->document('resource-id', true);
 
         $this->assertInstanceOf(ResponseInterface::class, $response);
 
         $this->assertEquals('GET', $api->getRequest()->getMethod());
         $this->assertEquals(
-            $api->apiUrl . '/v1/files/fake-id',
+            $api->apiUrl . '/v1/credit-notes/resource-id/file',
             $api->getRequest()->getUri()->__toString()
         );
     }
 
-    public function testFailedDocumentContent(): void
+    public function testFileContent(): void
     {
-        [, $stub] = $this->createClientMultiMockObject(
-            CreditNote::class,
-            [
-                new Response(500),
-                new Response()
-            ]
-        );
+        [$api, $stub] = $this->createClientMockObject(CreditNote::class);
 
-        $response = $stub->document('resource-id', true);
+        $response = $stub->file('resource-id');
 
         $this->assertInstanceOf(ResponseInterface::class, $response);
-        $this->assertEquals(500, $response->getStatusCode());
+
+        $this->assertEquals('GET', $api->getRequest()->getMethod());
+        $this->assertEquals(
+            $api->apiUrl . '/v1/credit-notes/resource-id/file',
+            $api->getRequest()->getUri()->__toString()
+        );
     }
 }
diff --git a/tests/Clients/DeliveryNoteTest.php b/tests/Clients/DeliveryNoteTest.php
@@ -109,6 +109,8 @@ public function testGetVoucherListClient(): void
 
     public function testDocument(): void
     {
+        $this->expectDeprecationV1Warning('document');
+
         [$api, $stub] = $this->createClientMockObject(DeliveryNote::class);
 
         $response = $stub->document('resource-id');
@@ -124,38 +126,33 @@ public function testDocument(): void
 
     public function testDocumentContent(): void
     {
-        [$api, $stub] = $this->createClientMultiMockObject(
-            DeliveryNote::class,
-            [
-                new Response(200, ['Content-Type' => 'application/json'], '{"documentFileId": "fake-id"}'),
-                new Response()
-            ]
-        );
+        $this->expectDeprecationV1Warning('document');
+
+        [$api, $stub] = $this->createClientMockObject(DeliveryNote::class);
 
         $response = $stub->document('resource-id', true);
 
         $this->assertInstanceOf(ResponseInterface::class, $response);
 
         $this->assertEquals('GET', $api->getRequest()->getMethod());
         $this->assertEquals(
-            $api->apiUrl . '/v1/files/fake-id',
+            $api->apiUrl . '/v1/delivery-notes/resource-id/file',
             $api->getRequest()->getUri()->__toString()
         );
     }
 
-    public function testFailedDocumentContent(): void
+    public function testFileContent(): void
     {
-        [, $stub] = $this->createClientMultiMockObject(
-            DeliveryNote::class,
-            [
-                new Response(500),
-                new Response()
-            ]
-        );
+        [$api, $stub] = $this->createClientMockObject(DeliveryNote::class);
 
-        $response = $stub->document('resource-id', true);
+        $response = $stub->file('resource-id');
 
         $this->assertInstanceOf(ResponseInterface::class, $response);
-        $this->assertEquals(500, $response->getStatusCode());
+
+        $this->assertEquals('GET', $api->getRequest()->getMethod());
+        $this->assertEquals(
+            $api->apiUrl . '/v1/delivery-notes/resource-id/file',
+            $api->getRequest()->getUri()->__toString()
+        );
     }
 }
diff --git a/tests/Clients/DownPaymentInvoiceTest.php b/tests/Clients/DownPaymentInvoiceTest.php
@@ -58,6 +58,8 @@ public function testGetVoucherListClient(): void
 
     public function testDocument(): void
     {
+        $this->expectDeprecationV1Warning('document');
+
         [$api, $stub] = $this->createClientMockObject(DownPaymentInvoice::class);
 
         $response = $stub->document('resource-id');
@@ -73,38 +75,33 @@ public function testDocument(): void
 
     public function testDocumentContent(): void
     {
-        [$api, $stub] = $this->createClientMultiMockObject(
-            DownPaymentInvoice::class,
-            [
-                new Response(200, ['Content-Type' => 'application/json'], '{"documentFileId": "fake-id"}'),
-                new Response()
-            ]
-        );
+        $this->expectDeprecationV1Warning('document');
+
+        [$api, $stub] = $this->createClientMockObject(DownPaymentInvoice::class);
 
         $response = $stub->document('resource-id', true);
 
         $this->assertInstanceOf(ResponseInterface::class, $response);
 
         $this->assertEquals('GET', $api->getRequest()->getMethod());
         $this->assertEquals(
-            $api->apiUrl . '/v1/files/fake-id',
+            $api->apiUrl . '/v1/down-payment-invoices/resource-id/file',
             $api->getRequest()->getUri()->__toString()
         );
     }
 
-    public function testFailedDocumentContent(): void
+    public function testFileContent(): void
     {
-        [, $stub] = $this->createClientMultiMockObject(
-            DownPaymentInvoice::class,
-            [
-                new Response(500),
-                new Response()
-            ]
-        );
+        [$api, $stub] = $this->createClientMockObject(DownPaymentInvoice::class);
 
-        $response = $stub->document('resource-id', true);
+        $response = $stub->file('resource-id');
 
         $this->assertInstanceOf(ResponseInterface::class, $response);
-        $this->assertEquals(500, $response->getStatusCode());
+
+        $this->assertEquals('GET', $api->getRequest()->getMethod());
+        $this->assertEquals(
+            $api->apiUrl . '/v1/down-payment-invoices/resource-id/file',
+            $api->getRequest()->getUri()->__toString()
+        );
     }
 }
diff --git a/tests/Clients/DunningTest.php b/tests/Clients/DunningTest.php
@@ -4,7 +4,6 @@
 
 namespace Sysix\LexOffice\Tests\Clients;
 
-use GuzzleHttp\Psr7\Response;
 use Psr\Http\Message\ResponseInterface;
 use Sysix\LexOffice\Clients\Dunning;
 use Sysix\LexOffice\Tests\TestClient;
@@ -45,6 +44,8 @@ public function testPursue(): void
 
     public function testDocument(): void
     {
+        $this->expectDeprecationV1Warning('document');
+
         [$api, $stub] = $this->createClientMockObject(Dunning::class);
 
         $response = $stub->document('resource-id');
@@ -60,38 +61,33 @@ public function testDocument(): void
 
     public function testDocumentContent(): void
     {
-        [$api, $stub] = $this->createClientMultiMockObject(
-            Dunning::class,
-            [
-                new Response(200, ['Content-Type' => 'application/json'], '{"documentFileId": "fake-id"}'),
-                new Response()
-            ]
-        );
+        $this->expectDeprecationV1Warning('document');
+
+        [$api, $stub] = $this->createClientMockObject(Dunning::class);
 
         $response = $stub->document('resource-id', true);
 
         $this->assertInstanceOf(ResponseInterface::class, $response);
 
         $this->assertEquals('GET', $api->getRequest()->getMethod());
         $this->assertEquals(
-            $api->apiUrl . '/v1/files/fake-id',
+            $api->apiUrl . '/v1/dunnings/resource-id/file',
             $api->getRequest()->getUri()->__toString()
         );
     }
 
-    public function testFailedDocumentContent(): void
+    public function testFileContent(): void
     {
-        [, $stub] = $this->createClientMultiMockObject(
-            Dunning::class,
-            [
-                new Response(500),
-                new Response()
-            ]
-        );
+        [$api, $stub] = $this->createClientMockObject(Dunning::class);
 
-        $response = $stub->document('resource-id', true);
+        $response = $stub->file('resource-id');
 
         $this->assertInstanceOf(ResponseInterface::class, $response);
-        $this->assertEquals(500, $response->getStatusCode());
+
+        $this->assertEquals('GET', $api->getRequest()->getMethod());
+        $this->assertEquals(
+            $api->apiUrl . '/v1/dunnings/resource-id/file',
+            $api->getRequest()->getUri()->__toString()
+        );
     }
 }
diff --git a/tests/Clients/InvoiceTest.php b/tests/Clients/InvoiceTest.php
@@ -143,6 +143,8 @@ public function testGetVoucherListClient(): void
 
     public function testDocument(): void
     {
+        $this->expectDeprecationV1Warning('document');
+
         [$api, $stub] = $this->createClientMockObject(Invoice::class);
 
         $response = $stub->document('resource-id');
@@ -158,38 +160,33 @@ public function testDocument(): void
 
     public function testDocumentContent(): void
     {
-        [$api, $stub] = $this->createClientMultiMockObject(
-            Invoice::class,
-            [
-                new Response(200, ['Content-Type' => 'application/json'], '{"documentFileId": "fake-id"}'),
-                new Response()
-            ]
-        );
+        $this->expectDeprecationV1Warning('document');
+
+        [$api, $stub] = $this->createClientMockObject(Invoice::class);
 
         $response = $stub->document('resource-id', true);
 
         $this->assertInstanceOf(ResponseInterface::class, $response);
 
         $this->assertEquals('GET', $api->getRequest()->getMethod());
         $this->assertEquals(
-            $api->apiUrl . '/v1/files/fake-id',
+            $api->apiUrl . '/v1/invoices/resource-id/file',
             $api->getRequest()->getUri()->__toString()
         );
     }
 
-    public function testFailedDocumentContent(): void
+    public function testFileContent(): void
     {
-        [, $stub] = $this->createClientMultiMockObject(
-            Invoice::class,
-            [
-                new Response(500),
-                new Response()
-            ]
-        );
+        [$api, $stub] = $this->createClientMockObject(Invoice::class);
 
-        $response = $stub->document('resource-id', true);
+        $response = $stub->file('resource-id');
 
         $this->assertInstanceOf(ResponseInterface::class, $response);
-        $this->assertEquals(500, $response->getStatusCode());
+
+        $this->assertEquals('GET', $api->getRequest()->getMethod());
+        $this->assertEquals(
+            $api->apiUrl . '/v1/invoices/resource-id/file',
+            $api->getRequest()->getUri()->__toString()
+        );
     }
 }