PBC-2693: Update vertex integration guide.

docs/pbc/all/tax-management/202307.0/vertex/install-vertex.md

@@ -2,13 +2,21 @@
 title: Install Vertex
 description: Find out how you can install Vertex in your Spryker shop
 draft: true
-last_updated: Aug 3, 2023
+last_updated: Sep 13, 2023
 template: howto-guide-template
 related:
   - title: Vertex
     link: docs/pbc/all/tax-management/page.version/vertex/vertex.html
 ---
 
+## Prerequisites
+
+- Before you can integrate Vertex, make sure that your project is ACP-enabled. See [App Composition Platform installation](/docs/acp/user/app-composition-platform-installation.html) for details.
+
+- The Vertex app catalog page lists specific packages which must be installed or upgraded before you can use the Vertex app. To check the list of the necessary packages, in the Back Office, go to **Apps**-> **Vertex**.
+
+Adjust your installation to comply with the listed requirements before proceeding.
+
 ## Integrate ACP connector module for tax calculation
 
 To enable the Vertex integration, use the [spryker/tax-app](https://github.com/spryker/tax-app) ACP connector module.
@@ -22,30 +30,106 @@ Add the following config to `config/Shared/config_default.php`:
 ```php
 // ...
 
+use Generated\Shared\Transfer\ConfigureTaxAppTransfer;
+use Generated\Shared\Transfer\DeleteTaxAppTransfer;
 use Generated\Shared\Transfer\SubmitPaymentTaxInvoiceTransfer;
 
 // ...
 
-$config[MessageBrokerConstants::MESSAGE_TO_CHANNEL_MAP] = [
+$config[MessageBrokerConstants::MESSAGE_TO_CHANNEL_MAP] =
+$config[MessageBrokerAwsConstants::MESSAGE_TO_CHANNEL_MAP] = [
     // ...
-
-    SubmitPaymentTaxInvoiceTransfer::class => 'tax-commands',
+    ConfigureTaxAppTransfer::class => 'tax-commands',
+    DeleteTaxAppTransfer::class => 'tax-commands',
+    SubmitPaymentTaxInvoiceTransfer::class => 'payment-tax-invoice-commands',
 ];
 
-$config[MessageBrokerConstants::CHANNEL_TO_TRANSPORT_MAP] = [
+$config[MessageBrokerConstants::CHANNEL_TO_RECEIVER_TRANSPORT_MAP] = [
     // ...
 
-    'tax-commands' => 'http',
+    'tax-commands' => MessageBrokerAwsConfig::HTTP_CHANNEL_TRANSPORT,
 ];
 
-$config[MessageBrokerAwsConstants::CHANNEL_TO_SENDER_TRANSPORT_MAP] = [
+$config[MessageBrokerConstants::CHANNEL_TO_SENDER_TRANSPORT_MAP] = [
     // ...
 
-    'tax-commands' => 'http',
+    'payment-tax-invoice-commands' => MessageBrokerAwsConfig::HTTP_CHANNEL_TRANSPORT,
 ];
 ```
 
-### 2. (Optional) If you plan to send invoices to Vertex through OMS, configure Payment OMS
+### 2. Configure Calculation Dependency Provider
+
+Add the following to `src/Pyz/Zed/Calculation/CalculationDependencyProvider.php`:
+
+```php
+// ...
+
+use Spryker\Zed\TaxApp\Communication\Plugin\Calculation\TaxAppCalculationPlugin;
+
+// ...
+
+    /**
+     * @param \Spryker\Zed\Kernel\Container $container
+     *
+     * @return array<\Spryker\Zed\CalculationExtension\Dependency\Plugin\CalculationPluginInterface>
+     */
+    protected function getQuoteCalculatorPluginStack(Container $container): array
+    {
+        /** @var array<\Spryker\Zed\Calculation\Dependency\Plugin\CalculationPluginInterface> $pluginStack */
+        $pluginStack = [
+            // ...
+
+            # Please put this plugin after all other tax calculation plugins or instead.
+
+            new TaxAppCalculationPlugin(),
+
+            // ...
+        ];
+
+        return $pluginStack;
+    }
+
+    /**
+     * @param \Spryker\Zed\Kernel\Container $container
+     *
+     * @return array<\Spryker\Zed\CalculationExtension\Dependency\Plugin\CalculationPluginInterface>
+     */
+    protected function getOrderCalculatorPluginStack(Container $container): array
+    {
+        return [
+            // ...
+
+            # Please put this plugin after all other tax calculation plugins or instead.
+            new TaxAppCalculationPlugin(),
+
+            // ...
+        ];
+    }
+
+// ...
+```
+
+{% info_block infoBox "Performance Improvements" %}
+
+Spryker has its own Taxes functionality that is pre-installed to the Checkout via Calculation module. When you decided to use external Tax calculation provider for the performance improvements it worths to disable following plguins:
+
+in `\Pyz\Zed\Calculation\CalculationDependencyProvider::getQuoteCalculatorPluginStack()`:
+
+- TaxAmountCalculatorPlugin
+- ItemTaxAmountFullAggregatorPlugin
+- TaxRateAverageAggregatorPlugin
+- TaxTotalCalculatorPlugin
+
+in `\Pyz\Zed\Calculation\CalculationDependencyProvider::getOrderCalculatorPluginStack()`:
+
+- TaxAmountCalculatorPlugin
+- ItemTaxAmountFullAggregatorPlugin
+- TaxAmountAfterCancellationCalculatorPlugin
+- OrderTaxTotalCalculationPlugin
+
+{% endinfo_block %}
+
+### 3. (Optional) If you plan to send invoices to Vertex through OMS, configure your Payment OMS
 
 The following code sample shows how to configure payment `config/Zed/oms/{your_payment_oms}.xml`.
 
@@ -142,44 +226,13 @@ use Spryker\Zed\TaxApp\Communication\Plugin\Oms\Command\SendPaymentTaxInvoicePlu
 
 ```
 
-### 3. Configure Calculation Dependency Provider
-
-Add the following to `src/Pyz/Zed/Calculation/CalculationDependencyProvider.php`:
-
-```php
-// ...
-
-use Spryker\Zed\TaxApp\Communication\Plugin\Calculation\TaxAppCalculationPlugin;
-
-// ...
-
-    /**
-     * @param \Spryker\Zed\Kernel\Container $container
-     *
-     * @return array<\Spryker\Zed\CalculationExtension\Dependency\Plugin\CalculationPluginInterface>
-     */
-    protected function getQuoteCalculatorPluginStack(Container $container): array
-    {
-        /** @var array<\Spryker\Zed\Calculation\Dependency\Plugin\CalculationPluginInterface> $pluginStack */
-        $pluginStack = [
-            // ...
-
-            // Please put this plugin after all other tax calculation plugins.
-
-            new TaxAppCalculationPlugin(),
-
-            // ...
-        ];
-
-        return $pluginStack;
-    }
+## Integrate the Vertex app
 
-// ...
-```
+Spryker does not have the same data model as Vertex requires to do correct taxes calculation, so the integration requires from the project developers to add some missing information to the Quote object before sending calculation request.
 
-## Integrate the Vertex app
+ [image here]
 
-To integrate the Vertex app, follow the steps below. 
+The diagram shows the data flow of the tax caclulation requiest from Spryker Cart to the Vertex API.
 
 ### 1. Configure Vertex Specific Metadata Transfers
 
@@ -236,13 +289,14 @@ Define specific Vertex Tax Metadata transfers and extend several other transfers
 
 `SaleTaxMetadata` and `ItemTaxMetadata` are designed to be equal to the Vertex Tax Calculation API request body. You can extend them as you need according to the Vertex API structure.
 
-`SaleTaxMetadata` is equal to the Invoicing/Quotation request payload, excluding LineItems.
+`SaleTaxMetadata` equals to the Invoicing/Quotation request payload, excluding LineItems.
 
-`ItemTaxMetadata` is equal to Line Item API Payload.
+`ItemTaxMetadata` equals to Line Item API Payload.
 
 ### 2. Implement Vertex Specific Metadata Extender Plugins
 
 There are several types of expander plugins you have to introduce.
+As a starting point you can take examples provided by Spryker in [this module](https://github.com/spryker/tax-app-vertex). The plugins inside are just for development purposes, the data provided in TaxMetaData fields has to be collected from project database or other sources, e.g. external ERP.
 
 #### Configure Customer Class Code Expander plugins
 
@@ -418,7 +472,11 @@ As a result, the plugin stack can look like this:
 
 namespace Pyz\Zed\TaxApp;
 
-// ...
+// The following plugins are for Marketplace only.
+use Spryker\Zed\MerchantProfile\Communication\Plugin\TaxApp\MerchantProfileAddressCalculableObjectTaxAppExpanderPlugin;
+use Spryker\Zed\MerchantProfile\Communication\Plugin\TaxApp\MerchantProfileAddressOrderTaxAppExpanderPlugin;
+use Spryker\Zed\ProductOfferAvailability\Communication\Plugin\TaxApp\ProductOfferAvailabilityCalculableObjectTaxAppExpanderPlugin;
+use Spryker\Zed\ProductOfferAvailability\Communication\Plugin\TaxApp\ProductOfferAvailabilityOrderTaxAppExpanderPlugin;
 
 class TaxAppDependencyProvider extends SprykerTaxAppDependencyProvider
 {
@@ -434,6 +492,10 @@ class TaxAppDependencyProvider extends SprykerTaxAppDependencyProvider
             new CalculableObjectItemProductOptionWithTaxCodeExpanderPlugin(), // to extend quote item product options with product class codes
             new CalculableObjectItemWithProductClassCodeExpandePlugin(), // to extend quote items with product class codes
             new CalculableObjectItemWithFlexibleFieldsExpanderPlugin(), // to extend quote items with flexible fields
+
+            // The following plugins are for Marketplace only.
+            new MerchantProfileAddressCalculableObjectTaxAppExpanderPlugin(),
+            new ProductOfferAvailabilityCalculableObjectTaxAppExpanderPlugin(),
         ];
     }
 
@@ -449,6 +511,36 @@ class TaxAppDependencyProvider extends SprykerTaxAppDependencyProvider
             new OrderItemProductOptionWithTaxCodeExpanderPlugin(), // to extend order item product options with product class codes
             new OrderItemWithProductClassCodeExpandePlugin(), // to extend order items with product class codes
             new OrderItemWithFlexibleFieldsExpanderPlugin(), // to extend order items with flexible fields
+
+            // The following plugins are for Marketplace only.
+            new MerchantProfileAddressOrderTaxAppExpanderPlugin(),
+            new ProductOfferAvailabilityOrderTaxAppExpanderPlugin(),
+        ];
+    }
+}
+
+```
+
+### 4. Configure Product Offer Stock Dependency Provider (Marketplace only)
+
+As a result, the plugin stack can look like this:
+
+```php
+
+namespace Pyz\Zed\ProductOfferStock;
+
+use Spryker\Zed\ProductOfferStock\ProductOfferStockDependencyProvider as SprykerProductOfferStockDependencyProvider;
+use Spryker\Zed\StockAddress\Communication\Plugin\Stock\StockAddressStockTransferProductOfferStockExpanderPlugin;
+
+class ProductOfferStockDependencyProvider extends SprykerProductOfferStockDependencyProvider
+{
+    /**
+     * @return array<\Spryker\Zed\ProductOfferStockExtension\Dependency\Plugin\StockTransferProductOfferStockExpanderPluginInterface>
+     */
+    protected function getStockTransferExpanderPluginCollection(): array
+    {
+        return [
+            new StockAddressStockTransferProductOfferStockExpanderPlugin(),
         ];
     }
 }