Merge pull request #756 from mollie/feature/add-sales-invoices-endpoint

Feature/add sales invoices endpoint

examples/sales-invoices/create-sales-invoice.php

@@ -0,0 +1,51 @@
+<?php
+
+use Mollie\Api\Types\PaymentTerm;
+use Mollie\Api\Types\SalesInvoiceStatus;
+
+/*
+ * Create a sales invoice using the Mollie API.
+ */
+
+try {
+    /*
+     * Initialize the Mollie API library with your API key or OAuth access token.
+     */
+    require "../initialize.php";
+
+    /*
+     * Create a sales invoice
+     */
+    $salesInvoice = $mollie->salesInvoices->create([
+        'currency' => 'EUR',
+        'status' => SalesInvoiceStatus::DRAFT,
+        'vatScheme' => 'standard',
+        'vatMode' => 'inclusive',
+        'paymentTerm' => PaymentTerm::DAYS_30,
+        'recipientIdentifier' => 'XXXXX',
+        'recipient' => [
+            'type' => 'consumer',
+            'email' => '[email protected]',
+            'streetAndNumber' => 'Sample Street 12b',
+            'postalCode' => '2000 AA',
+            'city' => 'Amsterdam',
+            'country' => 'NL',
+            'locale' => 'nl_NL',
+        ],
+        'lines' => [
+            [
+                'description' => 'Monthly subscription fee',
+                'quantity' => 1,
+                'vatRate' => '21',
+                'unitPrice' => [
+                    'currency' => 'EUR',
+                    'value' => '10.00',  // Corrected the format from '10,00' to '10.00' to match typical API expectations
+                ],
+            ],
+        ],
+    ]);
+
+    echo "<p>New sales invoice created with ID: " . htmlspecialchars($salesInvoice->id) . "</p>";
+} catch (\Mollie\Api\Exceptions\ApiException $e) {
+    echo "API call failed: " . htmlspecialchars($e->getMessage());
+}

examples/sales-invoices/delete-sales-invoice.php

@@ -0,0 +1,25 @@
+<?php
+/*
+ * Delete a sales invoice using the Mollie API.
+ */
+
+try {
+    /*
+     * Initialize the Mollie API library with your API key or OAuth access token.
+     */
+    require "../initialize.php";
+
+    /*
+     * Assume we have an invoice ID 'inv_xxx' that we wish to delete.
+     */
+    $invoiceId = 'invoice_xxx';
+
+    /*
+     * Delete the sales invoice
+     */
+    $mollie->salesInvoices->delete($invoiceId);
+
+    echo "<p>Sales invoice deleted with ID: " . htmlspecialchars($invoiceId) . "</p>";
+} catch (\Mollie\Api\Exceptions\ApiException $e) {
+    echo "API call failed: " . htmlspecialchars($e->getMessage());
+}

examples/sales-invoices/list-sales-invoices.php

@@ -0,0 +1,28 @@
+<?php
+/*
+ * List sales invoices using the Mollie API.
+ */
+
+try {
+    /*
+     * Initialize the Mollie API library with your API key or OAuth access token.
+     */
+    require "../initialize.php";
+
+    /*
+     * List the most recent sales invoices
+     *
+     * See: https://docs.mollie.com/reference/v2/sales-invoices-api/list-sales-invoices
+     */
+    echo '<ul>';
+    $salesInvoices = $mollie->salesInvoices->page();
+    foreach ($salesInvoices as $invoice) {
+        echo '<li><b>Invoice ' . htmlspecialchars($invoice->id) . ':</b> (' . htmlspecialchars($invoice->issuedAt) . ')';
+        echo '<br>Status: <b>' . htmlspecialchars($invoice->status) . '</b>';
+        echo '<br>Total Amount: <b>' . htmlspecialchars($invoice->amount->currency) . ' ' . htmlspecialchars($invoice->amount->value) . '</b>';
+        echo '</li>';
+    }
+    echo '</ul>';
+} catch (\Mollie\Api\Exceptions\ApiException $e) {
+    echo "API call failed: " . htmlspecialchars($e->getMessage());
+}

examples/sales-invoices/update-sales-invoice.php

@@ -0,0 +1,40 @@
+<?php
+/*
+ * Update a sales invoice using the Mollie API.
+ */
+
+try {
+    /*
+     * Initialize the Mollie API library with your API key or OAuth access token.
+     */
+    require "../initialize.php";
+
+    /*
+     * Assume we have an invoice ID 'inv_xxx' that we wish to update.
+     */
+    $invoiceId = 'invoice_xxx';
+
+    /*
+     * Update the sales invoice
+     */
+    $updatedInvoice = $mollie->salesInvoices->update($invoiceId, [
+        'status' => \Mollie\Api\Types\SalesInvoiceStatus::PAID,
+        'recipientIdentifier' => 'XXXXX',
+        'lines' => [
+            [
+                'id' => 'line_001',
+                'description' => 'Updated subscription fee',
+                'quantity' => 2,
+                'vatRate' => '21',
+                'unitPrice' => [
+                    'currency' => 'EUR',
+                    'value' => '15.00',
+                ],
+            ],
+        ],
+    ]);
+
+    echo "<p>Sales invoice updated with ID: " . htmlspecialchars($updatedInvoice->id) . "</p>";
+} catch (\Mollie\Api\Exceptions\ApiException $e) {
+    echo "API call failed: " . htmlspecialchars($e->getMessage());
+}

phpstan-baseline.neon

@@ -220,6 +220,26 @@ parameters:
 			count: 1
 			path: examples/profiles/update-profile.php
 
+		-
+			message: "#^Variable \\$mollie might not be defined\\.$#"
+			count: 1
+			path: examples/sales-invoices/create-sales-invoice.php
+
+		-
+			message: "#^Variable \\$mollie might not be defined\\.$#"
+			count: 1
+			path: examples/sales-invoices/delete-sales-invoice.php
+
+		-
+			message: "#^Variable \\$mollie might not be defined\\.$#"
+			count: 1
+			path: examples/sales-invoices/list-sales-invoices.php
+
+		-
+			message: "#^Variable \\$mollie might not be defined\\.$#"
+			count: 1
+			path: examples/sales-invoices/update-sales-invoice.php
+
 		-
 			message: "#^Variable \\$mollie might not be defined\\.$#"
 			count: 1

src/Endpoints/SalesInvoiceEndpoint.php

@@ -0,0 +1,122 @@
+<?php
+
+namespace Mollie\Api\Endpoints;
+
+use Mollie\Api\Exceptions\ApiException;
+use Mollie\Api\Resources\LazyCollection;
+use Mollie\Api\Resources\SalesInvoice;
+use Mollie\Api\Resources\SalesInvoiceCollection;
+
+class SalesInvoiceEndpoint extends CollectionEndpointAbstract
+{
+    protected $resourcePath = "sales-invoices";
+
+    /**
+     * @var string
+     */
+    public const RESOURCE_ID_PREFIX = 'invoice_';
+
+    /**
+     * @return SalesInvoice
+     */
+    protected function getResourceObject(): SalesInvoice
+    {
+        return new SalesInvoice($this->client);
+    }
+
+    /**
+     * Get the collection object that is used by this API endpoint. Every API endpoint uses one type of collection object.
+     *
+     * @param int $count
+     * @param \stdClass $_links
+     *
+     * @return SalesInvoiceCollection
+     */
+    protected function getResourceCollectionObject($count, $_links): SalesInvoiceCollection
+    {
+        return new SalesInvoiceCollection($this->client, $count, $_links);
+    }
+
+    /**
+     * Creates a payment in Mollie.
+     *
+     * @param array $data An array containing details on the payment.
+     *
+     * @return SalesInvoice
+     * @throws ApiException
+     */
+    public function create(array $data = []): SalesInvoice
+    {
+        return $this->rest_create($data, []);
+    }
+
+    /**
+     * Update the given Payment.
+     *
+     * Will throw a ApiException if the payment id is invalid or the resource cannot be found.
+     *
+     * @param string $salesInvoiceId
+     *
+     * @param array $data
+     * @return SalesInvoice
+     * @throws ApiException
+     */
+    public function update($salesInvoiceId, array $data = []): SalesInvoice
+    {
+        if (empty($salesInvoiceId) || strpos($salesInvoiceId, self::RESOURCE_ID_PREFIX) !== 0) {
+            throw new ApiException("Invalid sales invoice ID: '{$salesInvoiceId}'. A sales invoice ID should start with '" . self::RESOURCE_ID_PREFIX . "'.");
+        }
+
+        return parent::rest_update($salesInvoiceId, $data);
+    }
+
+    /**
+     * @param string $salesInvoiceId
+     * @param array $parameters
+     * @return SalesInvoice
+     * @throws ApiException
+     */
+    public function get($salesInvoiceId, array $parameters = []): SalesInvoice
+    {
+        if (empty($salesInvoiceId) || strpos($salesInvoiceId, self::RESOURCE_ID_PREFIX) !== 0) {
+            throw new ApiException("Invalid sales invoice ID: '{$salesInvoiceId}'. A sales invoice ID should start with '" . self::RESOURCE_ID_PREFIX . "'.");
+        }
+
+        return parent::rest_read($salesInvoiceId, $parameters);
+    }
+
+    /**
+     * @param string $salesInvoiceId
+     *
+     * @param array $data
+     * @throws ApiException
+     */
+    public function delete($salesInvoiceId, array $data = []): void
+    {
+        $this->rest_delete($salesInvoiceId, $data);
+    }
+
+    /**
+     * @param string $from The first payment ID you want to include in your list.
+     * @param int $limit
+     *
+     * @return SalesInvoiceCollection
+     * @throws ApiException
+     */
+    public function page($from = null, $limit = null)
+    {
+        return $this->rest_list($from, $limit, []);
+    }
+
+    /**
+     * @param string $from The first resource ID you want to include in your list.
+     * @param int $limit
+     * @param bool $iterateBackwards Set to true for reverse order iteration (default is false).
+     *
+     * @return LazyCollection
+     */
+    public function iterator(?string $from = null, ?int $limit = null, bool $iterateBackwards = false): LazyCollection
+    {
+        return $this->rest_iterator($from, $limit, [], $iterateBackwards);
+    }
+}

src/MollieApiClient.php

@@ -32,6 +32,7 @@
 use Mollie\Api\Endpoints\ProfileEndpoint;
 use Mollie\Api\Endpoints\ProfileMethodEndpoint;
 use Mollie\Api\Endpoints\RefundEndpoint;
+use Mollie\Api\Endpoints\SalesInvoiceEndpoint;
 use Mollie\Api\Endpoints\SessionEndpoint;
 use Mollie\Api\Endpoints\SettlementCaptureEndpoint;
 use Mollie\Api\Endpoints\SettlementChargebackEndpoint;
@@ -122,6 +123,13 @@ class MollieApiClient
      */
     public $customerPayments;
 
+    /**
+     * RESTful Sales Invoice resource.
+     *
+     * @var SalesInvoiceEndpoint
+     */
+    public $salesInvoices;
+
     /**
      * RESTful Settlement resource.
      *
@@ -444,6 +452,7 @@ public function initializeEndpoints()
         $this->profileMethods = new ProfileMethodEndpoint($this);
         $this->profiles = new ProfileEndpoint($this);
         $this->refunds = new RefundEndpoint($this);
+        $this->salesInvoices = new SalesInvoiceEndpoint($this);
         $this->settlementCaptures = new SettlementCaptureEndpoint($this);
         $this->settlementChargebacks = new SettlementChargebackEndpoint($this);
         $this->settlementPayments = new SettlementPaymentEndpoint($this);