From d1c9965e20b938f29cf486ee08b382bff63ebfaf Mon Sep 17 00:00:00 2001 From: Bohdan Turchyk Date: Mon, 16 Oct 2023 16:41:15 +0300 Subject: [PATCH 01/10] PBC-3110 Added description of data mapping between quote/order objects on Spryker side and Vertex API. --- .../vertex/install-vertex.md | 113 +++++++++++++----- 1 file changed, 85 insertions(+), 28 deletions(-) diff --git a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md index afad1cbe6ec..49935dfc51e 100644 --- a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md +++ b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md @@ -8,8 +8,8 @@ related: - title: Vertex link: docs/pbc/all/tax-management/page.version/vertex/vertex.html redirect_from: - - /docs/pbc/all/tax-management/202307.0/vertex/install-vertex.html - - /docs/pbc/all/tax-management/202400.0/base-shop/vertex/install-vertex.html + - /docs/pbc/all/tax-management/202307.0/vertex/install-vertex.html + - /docs/pbc/all/tax-management/202400.0/base-shop/vertex/install-vertex.html --- @@ -17,16 +17,19 @@ redirect_from: Before integrating Vertex, ensure the following prerequisites are met: -- Make sure your project is ACP-enabled. See [App Composition Platform installation](/docs/acp/user/app-composition-platform-installation.html) for details. +- Make sure 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 that 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**. -Ensure that your installation meets these requirements. +- The Vertex app catalog page lists specific packages that 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**. + Ensure that your installation meets these requirements. - Make sure that your deployment pipeline executes database migrations. ## 1. Integrate ACP connector module for tax calculation -To enable the Vertex integration, you need to integrate the [spryker/tax-app](https://github.com/spryker/tax-app) ACP connector module first. +To enable the Vertex integration, you need to integrate the [spryker/tax-app](https://github.com/spryker/tax-app) ACP +connector module first. To integrate the connector module for the Vertex app, follow the steps below. @@ -134,7 +137,10 @@ use Spryker\Zed\TaxApp\Communication\Plugin\Calculation\TaxAppCalculationPlugin; {% info_block infoBox "Performance improvement" %} -Spryker has its own [Taxes](/docs/pbc/all/tax-management/{{page.version}}/spryker-tax\base-shop/tax-feature-overview.html) feature, which comes pre-installed in the Checkout through the Calculation module. To enhance performance when using an external Tax calculation provider, we recommend disabling the following plugins: +Spryker has its +own [Taxes](/docs/pbc/all/tax-management/{{page.version}}/spryker-tax\base-shop/tax-feature-overview.html) feature, +which comes pre-installed in the Checkout through the Calculation module. To enhance performance when using an external +Tax calculation provider, we recommend disabling the following plugins: in `\Pyz\Zed\Calculation\CalculationDependencyProvider::getQuoteCalculatorPluginStack()`: @@ -150,7 +156,8 @@ in `\Pyz\Zed\Calculation\CalculationDependencyProvider::getOrderCalculatorPlugin - TaxAmountAfterCancellationCalculatorPlugin - OrderTaxTotalCalculationPlugin -Disabling them will also disable Spryker Taxes feature. This means that in case when Vertex is unresponsive or disabled order taxes will not be calculated and their amount will be always 0. +Disabling them will also disable Spryker Taxes feature. This means that in case when Vertex is unresponsive or disabled +order taxes will not be calculated and their amount will be always 0. {% endinfo_block %} @@ -185,7 +192,6 @@ class ShopApplicationDependencyProvider extends SprykerShopApplicationDependency ``` - ### 4. Configure the Message Broker dependency provider Add the following code to `src/Pyz/Zed/MessageBroker/MessageBrokerDependencyProvider.php`: @@ -222,23 +228,23 @@ Configure payment `config/Zed/oms/{your_payment_oms}.xml`as in the following exa ```xml - + - + - + @@ -255,13 +261,13 @@ Configure payment `config/Zed/oms/{your_payment_oms}.xml`as in the following exa tax invoice submitted - + - + - + @@ -271,15 +277,16 @@ Configure payment `config/Zed/oms/{your_payment_oms}.xml`as in the following exa - + - + - + ``` #### Configure the Oms dependency provider + Add the config to `src/Pyz/Zed/Oms/OmsDependencyProvider.php`: ```php @@ -314,11 +321,13 @@ use Spryker\Zed\TaxApp\Communication\Plugin\Oms\Command\SubmitPaymentTaxInvoiceP ## 2. Integrate the Vertex app -Spryker does not have the same data model as Vertex, which is necessary for accurate tax calculations. Therefore, the integration requires project developers to to add some missing information to the Quote object before sending a calculation request. +Spryker does not have the same data model as Vertex, which is necessary for accurate tax calculations. Therefore, the +integration requires project developers to to add some missing information to the Quote object before sending a +calculation request. The following diagram shows the data flow of the tax calculation request from Spryker Cart to the Vertex API. - ![tax-calculation-request](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/tax-management/vertex/install-vertex/tax-calculation-requests.png) +![tax-calculation-request](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/tax-management/vertex/install-vertex/tax-calculation-requests.png) ### 1. Configure Vertex-specific metadata transfers @@ -373,7 +382,8 @@ Define specific Vertex Tax metadata transfers and extend other transfers with th ``` -`SaleTaxMetadata` and `ItemTaxMetadata` are designed to be equal to the Vertex Tax Calculation API request body. You can extend them as you need, following to the Vertex API structure. +`SaleTaxMetadata` and `ItemTaxMetadata` are designed to be equal to the Vertex Tax Calculation API request body. You can +extend them as you need, following to the Vertex API structure. - `SaleTaxMetadata` equals the Invoicing/Quotation request payload, excluding LineItems. @@ -382,7 +392,9 @@ Define specific Vertex Tax metadata transfers and extend other transfers with th ### 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 the [tax-app-vertex](https://github.com/spryker/tax-app-vertex) module. The plugins inside are for development purposes. The data in the TaxMetaData fields has to be collected from the project database or other sources such as external ERP. +As a starting point, you can take examples provided by Spryker in +the [tax-app-vertex](https://github.com/spryker/tax-app-vertex) module. The plugins inside are for development purposes. +The data in the TaxMetaData fields has to be collected from the project database or other sources such as external ERP. #### Configure the Customer Class Code Expander plugins @@ -419,7 +431,6 @@ The following code sample shows how to introduce the following expander plugin: `Pyz/Zed/{YourDesiredModule}/Communication/Plugin/Quote/CalculableObjectCustomerWithVertexCodeExpanderPlugin.php` - ```php Date: Mon, 16 Oct 2023 16:45:22 +0300 Subject: [PATCH 02/10] PBC-3110 Reverted accidental formatting changes --- .../vertex/install-vertex.md | 71 ++++++++----------- 1 file changed, 28 insertions(+), 43 deletions(-) diff --git a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md index 49935dfc51e..ebce6a5da7f 100644 --- a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md +++ b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md @@ -8,8 +8,8 @@ related: - title: Vertex link: docs/pbc/all/tax-management/page.version/vertex/vertex.html redirect_from: - - /docs/pbc/all/tax-management/202307.0/vertex/install-vertex.html - - /docs/pbc/all/tax-management/202400.0/base-shop/vertex/install-vertex.html + - /docs/pbc/all/tax-management/202307.0/vertex/install-vertex.html + - /docs/pbc/all/tax-management/202400.0/base-shop/vertex/install-vertex.html --- @@ -17,19 +17,16 @@ redirect_from: Before integrating Vertex, ensure the following prerequisites are met: -- Make sure your project is ACP-enabled. - See [App Composition Platform installation](/docs/acp/user/app-composition-platform-installation.html) for details. +- Make sure 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 that 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**. - Ensure that your installation meets these requirements. +- The Vertex app catalog page lists specific packages that 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**. +Ensure that your installation meets these requirements. - Make sure that your deployment pipeline executes database migrations. ## 1. Integrate ACP connector module for tax calculation -To enable the Vertex integration, you need to integrate the [spryker/tax-app](https://github.com/spryker/tax-app) ACP -connector module first. +To enable the Vertex integration, you need to integrate the [spryker/tax-app](https://github.com/spryker/tax-app) ACP connector module first. To integrate the connector module for the Vertex app, follow the steps below. @@ -137,10 +134,7 @@ use Spryker\Zed\TaxApp\Communication\Plugin\Calculation\TaxAppCalculationPlugin; {% info_block infoBox "Performance improvement" %} -Spryker has its -own [Taxes](/docs/pbc/all/tax-management/{{page.version}}/spryker-tax\base-shop/tax-feature-overview.html) feature, -which comes pre-installed in the Checkout through the Calculation module. To enhance performance when using an external -Tax calculation provider, we recommend disabling the following plugins: +Spryker has its own [Taxes](/docs/pbc/all/tax-management/{{page.version}}/spryker-tax\base-shop/tax-feature-overview.html) feature, which comes pre-installed in the Checkout through the Calculation module. To enhance performance when using an external Tax calculation provider, we recommend disabling the following plugins: in `\Pyz\Zed\Calculation\CalculationDependencyProvider::getQuoteCalculatorPluginStack()`: @@ -156,8 +150,7 @@ in `\Pyz\Zed\Calculation\CalculationDependencyProvider::getOrderCalculatorPlugin - TaxAmountAfterCancellationCalculatorPlugin - OrderTaxTotalCalculationPlugin -Disabling them will also disable Spryker Taxes feature. This means that in case when Vertex is unresponsive or disabled -order taxes will not be calculated and their amount will be always 0. +Disabling them will also disable Spryker Taxes feature. This means that in case when Vertex is unresponsive or disabled order taxes will not be calculated and their amount will be always 0. {% endinfo_block %} @@ -192,6 +185,7 @@ class ShopApplicationDependencyProvider extends SprykerShopApplicationDependency ``` + ### 4. Configure the Message Broker dependency provider Add the following code to `src/Pyz/Zed/MessageBroker/MessageBrokerDependencyProvider.php`: @@ -228,23 +222,23 @@ Configure payment `config/Zed/oms/{your_payment_oms}.xml`as in the following exa ```xml - + - + - + @@ -261,13 +255,13 @@ Configure payment `config/Zed/oms/{your_payment_oms}.xml`as in the following exa tax invoice submitted - + - + - + @@ -277,16 +271,15 @@ Configure payment `config/Zed/oms/{your_payment_oms}.xml`as in the following exa - + - + - + ``` #### Configure the Oms dependency provider - Add the config to `src/Pyz/Zed/Oms/OmsDependencyProvider.php`: ```php @@ -321,13 +314,11 @@ use Spryker\Zed\TaxApp\Communication\Plugin\Oms\Command\SubmitPaymentTaxInvoiceP ## 2. Integrate the Vertex app -Spryker does not have the same data model as Vertex, which is necessary for accurate tax calculations. Therefore, the -integration requires project developers to to add some missing information to the Quote object before sending a -calculation request. +Spryker does not have the same data model as Vertex, which is necessary for accurate tax calculations. Therefore, the integration requires project developers to to add some missing information to the Quote object before sending a calculation request. The following diagram shows the data flow of the tax calculation request from Spryker Cart to the Vertex API. -![tax-calculation-request](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/tax-management/vertex/install-vertex/tax-calculation-requests.png) + ![tax-calculation-request](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/tax-management/vertex/install-vertex/tax-calculation-requests.png) ### 1. Configure Vertex-specific metadata transfers @@ -382,8 +373,7 @@ Define specific Vertex Tax metadata transfers and extend other transfers with th ``` -`SaleTaxMetadata` and `ItemTaxMetadata` are designed to be equal to the Vertex Tax Calculation API request body. You can -extend them as you need, following to the Vertex API structure. +`SaleTaxMetadata` and `ItemTaxMetadata` are designed to be equal to the Vertex Tax Calculation API request body. You can extend them as you need, following to the Vertex API structure. - `SaleTaxMetadata` equals the Invoicing/Quotation request payload, excluding LineItems. @@ -392,9 +382,7 @@ extend them as you need, following to the Vertex API structure. ### 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 -the [tax-app-vertex](https://github.com/spryker/tax-app-vertex) module. The plugins inside are for development purposes. -The data in the TaxMetaData fields has to be collected from the project database or other sources such as external ERP. +As a starting point, you can take examples provided by Spryker in the [tax-app-vertex](https://github.com/spryker/tax-app-vertex) module. The plugins inside are for development purposes. The data in the TaxMetaData fields has to be collected from the project database or other sources such as external ERP. #### Configure the Customer Class Code Expander plugins @@ -431,6 +419,7 @@ The following code sample shows how to introduce the following expander plugin: `Pyz/Zed/{YourDesiredModule}/Communication/Plugin/Quote/CalculableObjectCustomerWithVertexCodeExpanderPlugin.php` + ```php Date: Mon, 16 Oct 2023 16:54:27 +0300 Subject: [PATCH 03/10] added h1 level title --- .../third-party-integrations/vertex/install-vertex.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md index ebce6a5da7f..04c7083b1f0 100644 --- a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md +++ b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md @@ -628,7 +628,13 @@ class ProductOfferStockDependencyProvider extends SprykerProductOfferStockDepend ``` -#### Quote/Order object to Vertex API mapping + +--- + + +## Appendix A + +### Quote/Order object to Vertex API mapping Mapping of Spryker Quote/Order transfer object to Vertex API request format is described in the following table: @@ -668,4 +674,4 @@ Mapping of Spryker Quote/Order transfer object to Vertex API request format is d | city | city | | | state | mainDivision | should be either not empty or null | | zipCode | postalCode | | -| country.iso2Code | country | | \ No newline at end of file +| country.iso2Code | country | | From 7b0782e64302a46fcae444023cd364f99ee9a2fb Mon Sep 17 00:00:00 2001 From: Bohdan Turchyk Date: Tue, 17 Oct 2023 11:24:21 +0300 Subject: [PATCH 04/10] PBC-3110 Added missing field --- .../vertex/install-vertex.md | 48 +++++++++---------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md index 04c7083b1f0..17ed0961713 100644 --- a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md +++ b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md @@ -638,32 +638,32 @@ class ProductOfferStockDependencyProvider extends SprykerProductOfferStockDepend Mapping of Spryker Quote/Order transfer object to Vertex API request format is described in the following table: -| QuoteTransfer/OrderTransfer object properties | Vertex API field | Comment | -|----------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| -| Current date (Y-m-d) | documentDate | | +| QuoteTransfer/OrderTransfer object properties | Vertex API field | Comment | +|---------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| +| Current date (Y-m-d) | documentDate | | | QuoteTransfer.uuid / OrderTransfer.orderReference / new Uuid4 (if quote.uuid is not present) | documentNumber | | | QuoteTransfer.uuid / OrderTransfer.orderReference / new Uuid4 (if quote.uuid is not present) | transactionId | | -| - | transactionType | always `SALE` | -| - | saleMessageType | depends on the type of operation, `INVOICE` or `QUOTATION` | -| taxMetadata | **Mapped over the final request 1:1** | Metadata is supposed to follow the structure of Vertex API request | -| items[].sku | lineItems[].lineItemId; lineItems[].product.value; lineItems[].vendorSku | lineItems[].lineItemId can be changed if there are multiple items with the same SKU in the request | -| items[].shipment.shippingAddress | lineItems[].customer.destination | | -| billingAddress | lineItems[].customer.administrativeDestination | | -| items[].merchantStockAddresses | lineItems[].seller.physicalOrigin | Multiple addresses are mapped to multiple items in Vertex PBC and Vertex API lineItems[]. | -| - | lineItems[].seller.administrativeOrigin | | -| items[].unitDiscountAmountFullAggregation | lineItems[].discount.discountValue | prices are converted from Spryker’s cent-based format to Vertex decimal format | -| - | lineItems[].discount.discountType | always `DiscountAmount`. Spryker stores discount based on amount, so there is no need for percentage-based discounts. | -| items[].unitPrice (either GROSS or NET depending on the currently selected mode) | lineItems[].unitPrice | prices are converted from Spryker’s cent-based format to Vertex decimal format | -| items[].merchantStockAddresses.quantityToShip | lineItems[].quantity.value | if quantityToShip is less than quantity requested in cart - in this case this item will be mapped to multiple items in Vertex API | -| - | lineItems[].quantity.unitOfMeasure | always `EA` (“each”). Other units of measure are not supported yet. | -| items[].taxMetadata | Mapped over specific lineItem 1:1 | Metadata is supposed to follow the structure of Vertex API request. For lineItems it is mapped over each corresponding item based on lineItemId | -| expenses (only for expenses with type `SHIPMENT_EXPENSE_TYPE`) | lineItems | shipments are treated just like products in Vertex - it’s all a line item | -| expenses.hash | lineItems[].lineItemId | | -| expenses.shipment.shipmentAddress | lineItems[].customer.destination | | -| billingAddress | lineItems[].customer.administrativeDestination | | -| expenses.sumPrice (either GROSS or NET depending on currently selected mode) | lineItems[].extendedPrice | | -| expenses.sumDiscountAmountAggregation | lineItems[].discount.discountValue | prices are converted from Spryker’s cent-based format to Vertex decimal format | -| - | lineItems[].discount.discountType | always `DiscountAmount`. Spryker stores discount based on amount, so there is no need to use percentage-based discounts here. | +| - | transactionType | always `SALE` | +| - | saleMessageType | depends on the type of operation, `INVOICE` or `QUOTATION` | +| taxMetadata | **Mapped over the final request 1:1** | Metadata is supposed to follow the structure of Vertex API request | +| items[].sku | lineItems[].lineItemId; lineItems[].product.value; lineItems[].vendorSku | lineItems[].lineItemId can be changed if there are multiple items with the same SKU in the request | +| items[].shipment.shippingAddress | lineItems[].customer.destination | | +| billingAddress | lineItems[].customer.administrativeDestination | | +| items[].merchantStockAddresses | lineItems[].seller.physicalOrigin | Multiple addresses are mapped to multiple items in Vertex PBC and Vertex API lineItems[]. | +| items[].merchantProfileAddress | lineItems[].seller.administrativeOrigin | | +| items[].unitDiscountAmountFullAggregation | lineItems[].discount.discountValue | prices are converted from Spryker’s cent-based format to Vertex decimal format | +| - | lineItems[].discount.discountType | always `DiscountAmount`. Spryker stores discount based on amount, so there is no need for percentage-based discounts. | +| items[].unitPrice (either GROSS or NET depending on the currently selected mode) | lineItems[].unitPrice | prices are converted from Spryker’s cent-based format to Vertex decimal format | +| items[].merchantStockAddresses.quantityToShip | lineItems[].quantity.value | if quantityToShip is less than quantity requested in cart - in this case this item will be mapped to multiple items in Vertex API | +| - | lineItems[].quantity.unitOfMeasure | always `EA` (“each”). Other units of measure are not supported yet. | +| items[].taxMetadata | Mapped over specific lineItem 1:1 | Metadata is supposed to follow the structure of Vertex API request. For lineItems it is mapped over each corresponding item based on lineItemId | +| expenses (only for expenses with type `SHIPMENT_EXPENSE_TYPE`) | lineItems | shipments are treated just like products in Vertex - it’s all a line item | +| expenses.hash | lineItems[].lineItemId | | +| expenses.shipment.shipmentAddress | lineItems[].customer.destination | | +| billingAddress | lineItems[].customer.administrativeDestination | | +| expenses.sumPrice (either GROSS or NET depending on currently selected mode) | lineItems[].extendedPrice | | +| expenses.sumDiscountAmountAggregation | lineItems[].discount.discountValue | prices are converted from Spryker’s cent-based format to Vertex decimal format | +| - | lineItems[].discount.discountType | always `DiscountAmount`. Spryker stores discount based on amount, so there is no need to use percentage-based discounts here. | ##### Location mapping From 64e786d5420b0f9e0d849441a107c2f95a20bb1f Mon Sep 17 00:00:00 2001 From: Bohdan Turchyk Date: Tue, 17 Oct 2023 12:18:31 +0300 Subject: [PATCH 05/10] PBC-3110 Added missing field; capitalized comments --- .../vertex/install-vertex.md | 54 ++++++++++--------- 1 file changed, 28 insertions(+), 26 deletions(-) diff --git a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md index 17ed0961713..3b87da57170 100644 --- a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md +++ b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md @@ -638,40 +638,42 @@ class ProductOfferStockDependencyProvider extends SprykerProductOfferStockDepend Mapping of Spryker Quote/Order transfer object to Vertex API request format is described in the following table: -| QuoteTransfer/OrderTransfer object properties | Vertex API field | Comment | -|---------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| -| Current date (Y-m-d) | documentDate | | +| QuoteTransfer/OrderTransfer object properties | Vertex API field | Comment | +|----------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| +| Current date (Y-m-d) | documentDate | | | QuoteTransfer.uuid / OrderTransfer.orderReference / new Uuid4 (if quote.uuid is not present) | documentNumber | | | QuoteTransfer.uuid / OrderTransfer.orderReference / new Uuid4 (if quote.uuid is not present) | transactionId | | -| - | transactionType | always `SALE` | -| - | saleMessageType | depends on the type of operation, `INVOICE` or `QUOTATION` | -| taxMetadata | **Mapped over the final request 1:1** | Metadata is supposed to follow the structure of Vertex API request | -| items[].sku | lineItems[].lineItemId; lineItems[].product.value; lineItems[].vendorSku | lineItems[].lineItemId can be changed if there are multiple items with the same SKU in the request | -| items[].shipment.shippingAddress | lineItems[].customer.destination | | -| billingAddress | lineItems[].customer.administrativeDestination | | -| items[].merchantStockAddresses | lineItems[].seller.physicalOrigin | Multiple addresses are mapped to multiple items in Vertex PBC and Vertex API lineItems[]. | -| items[].merchantProfileAddress | lineItems[].seller.administrativeOrigin | | -| items[].unitDiscountAmountFullAggregation | lineItems[].discount.discountValue | prices are converted from Spryker’s cent-based format to Vertex decimal format | -| - | lineItems[].discount.discountType | always `DiscountAmount`. Spryker stores discount based on amount, so there is no need for percentage-based discounts. | -| items[].unitPrice (either GROSS or NET depending on the currently selected mode) | lineItems[].unitPrice | prices are converted from Spryker’s cent-based format to Vertex decimal format | -| items[].merchantStockAddresses.quantityToShip | lineItems[].quantity.value | if quantityToShip is less than quantity requested in cart - in this case this item will be mapped to multiple items in Vertex API | -| - | lineItems[].quantity.unitOfMeasure | always `EA` (“each”). Other units of measure are not supported yet. | -| items[].taxMetadata | Mapped over specific lineItem 1:1 | Metadata is supposed to follow the structure of Vertex API request. For lineItems it is mapped over each corresponding item based on lineItemId | -| expenses (only for expenses with type `SHIPMENT_EXPENSE_TYPE`) | lineItems | shipments are treated just like products in Vertex - it’s all a line item | -| expenses.hash | lineItems[].lineItemId | | -| expenses.shipment.shipmentAddress | lineItems[].customer.destination | | -| billingAddress | lineItems[].customer.administrativeDestination | | -| expenses.sumPrice (either GROSS or NET depending on currently selected mode) | lineItems[].extendedPrice | | -| expenses.sumDiscountAmountAggregation | lineItems[].discount.discountValue | prices are converted from Spryker’s cent-based format to Vertex decimal format | -| - | lineItems[].discount.discountType | always `DiscountAmount`. Spryker stores discount based on amount, so there is no need to use percentage-based discounts here. | +| - | transactionType | Always `SALE` | +| - | saleMessageType | Depends on the type of operation, `INVOICE` or `QUOTATION` | +| taxMetadata | **Mapped over the final request 1:1** | Metadata is supposed to follow the structure of Vertex API request | +| taxMetadata.seller.company | seller.company | Required by Vertex from legal point of view | +| items[].sku | lineItems[].lineItemId; lineItems[].product.value; lineItems[].vendorSku | lineItems[].lineItemId can be changed if there are multiple items with the same SKU in the request | +| items[].shipment.shippingAddress | lineItems[].customer.destination | | +| billingAddress | lineItems[].customer.administrativeDestination | | +| items[].merchantStockAddresses | lineItems[].seller.physicalOrigin | Multiple addresses are mapped to multiple items in Vertex PBC and Vertex API lineItems[]. | +| items[].merchantProfileAddress | lineItems[].seller.administrativeOrigin | | +| items[].taxMetadata.seller.company | lineItems[].seller.company | Required by Vertex from legal point of view | +| items[].unitDiscountAmountFullAggregation | lineItems[].discount.discountValue | Prices are converted from Spryker’s cent-based format to Vertex decimal format | +| - | lineItems[].discount.discountType | Always `DiscountAmount`. Spryker stores discount based on amount, so there is no need for percentage-based discounts. | +| items[].unitPrice (either GROSS or NET depending on the currently selected mode) | lineItems[].unitPrice | Prices are converted from Spryker’s cent-based format to Vertex decimal format | +| items[].merchantStockAddresses.quantityToShip | lineItems[].quantity.value | If quantityToShip is less than quantity requested in cart - in this case this item will be mapped to multiple items in Vertex API | +| - | lineItems[].quantity.unitOfMeasure | Always `EA` (“each”). Other units of measure are not supported yet. | +| items[].taxMetadata | Mapped over specific lineItem 1:1 | Metadata is supposed to follow the structure of Vertex API request. For lineItems it is mapped over each corresponding item based on lineItemId | +| expenses (only for expenses with type `SHIPMENT_EXPENSE_TYPE`) | lineItems | Shipments are treated just like products in Vertex - it’s all a line item | +| expenses.hash | lineItems[].lineItemId | | +| expenses.shipment.shipmentAddress | lineItems[].customer.destination | | +| billingAddress | lineItems[].customer.administrativeDestination | | +| expenses.sumPrice (either GROSS or NET depending on currently selected mode) | lineItems[].extendedPrice | | +| expenses.sumDiscountAmountAggregation | lineItems[].discount.discountValue | Prices are converted from Spryker’s cent-based format to Vertex decimal format | +| - | lineItems[].discount.discountType | Always `DiscountAmount`. Spryker stores discount based on amount, so there is no need to use percentage-based discounts here. | ##### Location mapping | Spryker | Vertex | Comment | |------------------|----------------|------------------------------------| | address1 | streetAddress1 | | -| address2 | streetAddress2 | should be either not empty or null | +| address2 | streetAddress2 | Should be either not empty or null | | city | city | | -| state | mainDivision | should be either not empty or null | +| state | mainDivision | Should be either not empty or null | | zipCode | postalCode | | | country.iso2Code | country | | From 61db863f533f6dbbeb307648f18293aa4a518d4b Mon Sep 17 00:00:00 2001 From: Stanislav Matveyev Date: Tue, 17 Oct 2023 12:36:18 +0300 Subject: [PATCH 06/10] moved taxMetadata.seller under taxMetadata --- .../third-party-integrations/vertex/install-vertex.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md index 3b87da57170..b4dcd017394 100644 --- a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md +++ b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md @@ -651,14 +651,14 @@ Mapping of Spryker Quote/Order transfer object to Vertex API request format is d | items[].shipment.shippingAddress | lineItems[].customer.destination | | | billingAddress | lineItems[].customer.administrativeDestination | | | items[].merchantStockAddresses | lineItems[].seller.physicalOrigin | Multiple addresses are mapped to multiple items in Vertex PBC and Vertex API lineItems[]. | -| items[].merchantProfileAddress | lineItems[].seller.administrativeOrigin | | -| items[].taxMetadata.seller.company | lineItems[].seller.company | Required by Vertex from legal point of view | +| items[].merchantProfileAddress | lineItems[].seller.administrativeOrigin | | | | items[].unitDiscountAmountFullAggregation | lineItems[].discount.discountValue | Prices are converted from Spryker’s cent-based format to Vertex decimal format | | - | lineItems[].discount.discountType | Always `DiscountAmount`. Spryker stores discount based on amount, so there is no need for percentage-based discounts. | | items[].unitPrice (either GROSS or NET depending on the currently selected mode) | lineItems[].unitPrice | Prices are converted from Spryker’s cent-based format to Vertex decimal format | | items[].merchantStockAddresses.quantityToShip | lineItems[].quantity.value | If quantityToShip is less than quantity requested in cart - in this case this item will be mapped to multiple items in Vertex API | | - | lineItems[].quantity.unitOfMeasure | Always `EA` (“each”). Other units of measure are not supported yet. | | items[].taxMetadata | Mapped over specific lineItem 1:1 | Metadata is supposed to follow the structure of Vertex API request. For lineItems it is mapped over each corresponding item based on lineItemId | +| items[].taxMetadata.seller.company | lineItems[].seller.company | Required by Vertex from legal point of view | expenses (only for expenses with type `SHIPMENT_EXPENSE_TYPE`) | lineItems | Shipments are treated just like products in Vertex - it’s all a line item | | expenses.hash | lineItems[].lineItemId | | | expenses.shipment.shipmentAddress | lineItems[].customer.destination | | From fac638c88981bc0fa0f5ec59baa978b629bde84b Mon Sep 17 00:00:00 2001 From: Bohdan Turchyk Date: Tue, 17 Oct 2023 13:48:11 +0300 Subject: [PATCH 07/10] Fixed typo --- .../third-party-integrations/vertex/install-vertex.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md index b4dcd017394..63f8e5da8cf 100644 --- a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md +++ b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md @@ -651,14 +651,14 @@ Mapping of Spryker Quote/Order transfer object to Vertex API request format is d | items[].shipment.shippingAddress | lineItems[].customer.destination | | | billingAddress | lineItems[].customer.administrativeDestination | | | items[].merchantStockAddresses | lineItems[].seller.physicalOrigin | Multiple addresses are mapped to multiple items in Vertex PBC and Vertex API lineItems[]. | -| items[].merchantProfileAddress | lineItems[].seller.administrativeOrigin | | | +| items[].merchantProfileAddress | lineItems[].seller.administrativeOrigin | | | items[].unitDiscountAmountFullAggregation | lineItems[].discount.discountValue | Prices are converted from Spryker’s cent-based format to Vertex decimal format | | - | lineItems[].discount.discountType | Always `DiscountAmount`. Spryker stores discount based on amount, so there is no need for percentage-based discounts. | | items[].unitPrice (either GROSS or NET depending on the currently selected mode) | lineItems[].unitPrice | Prices are converted from Spryker’s cent-based format to Vertex decimal format | | items[].merchantStockAddresses.quantityToShip | lineItems[].quantity.value | If quantityToShip is less than quantity requested in cart - in this case this item will be mapped to multiple items in Vertex API | | - | lineItems[].quantity.unitOfMeasure | Always `EA` (“each”). Other units of measure are not supported yet. | | items[].taxMetadata | Mapped over specific lineItem 1:1 | Metadata is supposed to follow the structure of Vertex API request. For lineItems it is mapped over each corresponding item based on lineItemId | -| items[].taxMetadata.seller.company | lineItems[].seller.company | Required by Vertex from legal point of view +| items[].taxMetadata.seller.company | lineItems[].seller.company | Required by Vertex from legal point of view | | expenses (only for expenses with type `SHIPMENT_EXPENSE_TYPE`) | lineItems | Shipments are treated just like products in Vertex - it’s all a line item | | expenses.hash | lineItems[].lineItemId | | | expenses.shipment.shipmentAddress | lineItems[].customer.destination | | From 0910aca583f40b2f7cc0fba7b173db9dea01b9b6 Mon Sep 17 00:00:00 2001 From: Bohdan Turchyk Date: Fri, 20 Oct 2023 14:56:17 +0300 Subject: [PATCH 08/10] PBC-3110 Added a comment before the table --- .../third-party-integrations/vertex/install-vertex.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md index 63f8e5da8cf..6b8142b19c1 100644 --- a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md +++ b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md @@ -636,7 +636,9 @@ class ProductOfferStockDependencyProvider extends SprykerProductOfferStockDepend ### Quote/Order object to Vertex API mapping -Mapping of Spryker Quote/Order transfer object to Vertex API request format is described in the following table: +While developing custom plugins for more in-depth integration with your projects, you may need to know how Spryker data is mapped to Vertex API requests. + +The table below answers this question and provides the mapping of Spryker Quote/Order transfer object to Vertex API request format. | QuoteTransfer/OrderTransfer object properties | Vertex API field | Comment | |----------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| From 9fde0b7c63f8889b75ea0561da8881d1b78b136b Mon Sep 17 00:00:00 2001 From: Helen Kravchenko Date: Fri, 20 Oct 2023 14:16:00 +0200 Subject: [PATCH 09/10] adjusting the file --- .../vertex/install-vertex.md | 37 +++++++++---------- 1 file changed, 17 insertions(+), 20 deletions(-) diff --git a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md index 6b8142b19c1..a0f3cbbb856 100644 --- a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md +++ b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md @@ -631,43 +631,40 @@ class ProductOfferStockDependencyProvider extends SprykerProductOfferStockDepend --- +### Reference: Quote/Order object to Vertex API mapping -## Appendix A +While developing custom plugins for for a deeper integration with your projects, you may need to know how Spryker data is mapped to Vertex API requests. -### Quote/Order object to Vertex API mapping - -While developing custom plugins for more in-depth integration with your projects, you may need to know how Spryker data is mapped to Vertex API requests. - -The table below answers this question and provides the mapping of Spryker Quote/Order transfer object to Vertex API request format. +The following table reflects the mapping of the Spryker Quote/Order transfer object to the Vertex API request format. | QuoteTransfer/OrderTransfer object properties | Vertex API field | Comment | |----------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| | Current date (Y-m-d) | documentDate | | | QuoteTransfer.uuid / OrderTransfer.orderReference / new Uuid4 (if quote.uuid is not present) | documentNumber | | | QuoteTransfer.uuid / OrderTransfer.orderReference / new Uuid4 (if quote.uuid is not present) | transactionId | | -| - | transactionType | Always `SALE` | -| - | saleMessageType | Depends on the type of operation, `INVOICE` or `QUOTATION` | -| taxMetadata | **Mapped over the final request 1:1** | Metadata is supposed to follow the structure of Vertex API request | -| taxMetadata.seller.company | seller.company | Required by Vertex from legal point of view | -| items[].sku | lineItems[].lineItemId; lineItems[].product.value; lineItems[].vendorSku | lineItems[].lineItemId can be changed if there are multiple items with the same SKU in the request | +| - | transactionType | Always `SALE`. | +| - | saleMessageType | Depends on the type of operation, `INVOICE` or `QUOTATION`. | +| taxMetadata | **Mapped over the final request 1:1** | Metadata is supposed to follow the structure of the Vertex API request. | +| taxMetadata.seller.company | seller.company | Required by Vertex from the legal point of view. | +| items[].sku | lineItems[].lineItemId; lineItems[].product.value; lineItems[].vendorSku | lineItems[].lineItemId can be changed if there are multiple items with the same SKU in the request. | | items[].shipment.shippingAddress | lineItems[].customer.destination | | | billingAddress | lineItems[].customer.administrativeDestination | | -| items[].merchantStockAddresses | lineItems[].seller.physicalOrigin | Multiple addresses are mapped to multiple items in Vertex PBC and Vertex API lineItems[]. | +| items[].merchantStockAddresses | lineItems[].seller.physicalOrigin | Multiple addresses are mapped to multiple items in the Vertex PBC and Vertex API lineItems[]. | | items[].merchantProfileAddress | lineItems[].seller.administrativeOrigin | | -| items[].unitDiscountAmountFullAggregation | lineItems[].discount.discountValue | Prices are converted from Spryker’s cent-based format to Vertex decimal format | +| items[].unitDiscountAmountFullAggregation | lineItems[].discount.discountValue | Prices are converted from the Spryker’s cent-based format to the Vertex decimal format. | | - | lineItems[].discount.discountType | Always `DiscountAmount`. Spryker stores discount based on amount, so there is no need for percentage-based discounts. | -| items[].unitPrice (either GROSS or NET depending on the currently selected mode) | lineItems[].unitPrice | Prices are converted from Spryker’s cent-based format to Vertex decimal format | -| items[].merchantStockAddresses.quantityToShip | lineItems[].quantity.value | If quantityToShip is less than quantity requested in cart - in this case this item will be mapped to multiple items in Vertex API | +| items[].unitPrice (either GROSS or NET depending on the currently selected mode) | lineItems[].unitPrice | Prices are converted from Spryker’s cent-based format to Vertex decimal format. | +| items[].merchantStockAddresses.quantityToShip | lineItems[].quantity.value | If quantityToShip is less than quantity requested in cart - in this case this item will be mapped to multiple items in the Vertex API. | | - | lineItems[].quantity.unitOfMeasure | Always `EA` (“each”). Other units of measure are not supported yet. | -| items[].taxMetadata | Mapped over specific lineItem 1:1 | Metadata is supposed to follow the structure of Vertex API request. For lineItems it is mapped over each corresponding item based on lineItemId | -| items[].taxMetadata.seller.company | lineItems[].seller.company | Required by Vertex from legal point of view | -| expenses (only for expenses with type `SHIPMENT_EXPENSE_TYPE`) | lineItems | Shipments are treated just like products in Vertex - it’s all a line item | +| items[].taxMetadata | Mapped over specific lineItem 1:1 | Metadata is supposed to follow the structure of the Vertex API request. For lineItems it is mapped over each corresponding item based on lineItemId. | +| items[].taxMetadata.seller.company | lineItems[].seller.company | Required by Vertex from the legal point of view. | +| expenses (only for expenses with type `SHIPMENT_EXPENSE_TYPE`) | lineItems | Shipments are treated just like products in Vertex - it’s all a line item. | | expenses.hash | lineItems[].lineItemId | | | expenses.shipment.shipmentAddress | lineItems[].customer.destination | | | billingAddress | lineItems[].customer.administrativeDestination | | | expenses.sumPrice (either GROSS or NET depending on currently selected mode) | lineItems[].extendedPrice | | -| expenses.sumDiscountAmountAggregation | lineItems[].discount.discountValue | Prices are converted from Spryker’s cent-based format to Vertex decimal format | -| - | lineItems[].discount.discountType | Always `DiscountAmount`. Spryker stores discount based on amount, so there is no need to use percentage-based discounts here. | +| expenses.sumDiscountAmountAggregation | lineItems[].discount.discountValue | Prices are converted from the Spryker’s cent-based format to the Vertex decimal format. | +| - | lineItems[].discount.discountType | Always `DiscountAmount`. Spryker stores discount based on amount, so there is no need to use percentage-based discounts. | ##### Location mapping From 943d58b02ba4e230c7d8a7a4f6002694de2b898b Mon Sep 17 00:00:00 2001 From: Helen Kravchenko Date: Fri, 27 Oct 2023 10:34:05 +0200 Subject: [PATCH 10/10] Update install-vertex.md --- .../202400.0/third-party-integrations/vertex/install-vertex.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md index b34a827e2f5..efb1a4bd62e 100644 --- a/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md +++ b/docs/pbc/all/tax-management/202400.0/third-party-integrations/vertex/install-vertex.md @@ -649,7 +649,7 @@ class ProductOfferStockDependencyProvider extends SprykerProductOfferStockDepend ### Reference: Quote/Order object to Vertex API mapping -While developing custom plugins for for a deeper integration with your projects, you may need to know how Spryker data is mapped to Vertex API requests. +While developing custom plugins for deeper integration with your projects, you may need to know how Spryker data is mapped to Vertex API requests. The following table reflects the mapping of the Spryker Quote/Order transfer object to the Vertex API request format.