Integrate the Shipment Glue API
Edit on GitHubThis document describes how to integrate the Shipment feature API into a Spryker project.
Install feature core
Follow the steps below to install the Shipment feature core.
Prerequisites
Install the required features:
FEATURE | VERSION | INTEGRATION GUIDE |
---|---|---|
Glue API: Spryker Core | 202204.0 | Glue API: Spryker Core feature integration |
Shipment | 202204.0 | Shipment feature integration |
Glue API: Checkout | 202204.0 | Install the Checkout Glue API |
Glue API: Glue Application | 202204.0 | Glue API: Glue Application feature integration |
Glue API: Order Management | 202204.0 | Glue API: Order Management feature integration |
1) Install the required modules using Composer
Install the required modules:
composer require spryker/shipments-rest-api:"1.4.0" --update-with-dependencies
Make sure that the following modules have been installed:
MODULE | EXPECTED DIRECTORY |
---|---|
ShipmentsRestApi | vendor/spryker/shipments-rest-api |
2) Set up transfer objects
Generate transfer changes:
console transfer:generate
Make sure that the following changes have been applied in transfer objects:
TRANSFER | TYPE | EVENT | PATH |
---|---|---|---|
RestCheckoutDataTransfer | class | created | src/Generated/Shared/Transfer/RestCheckoutDataTransfer.php |
RestCheckoutRequestAttributesTransfer | class | created | src/Generated/Shared/Transfer/RestCheckoutRequestAttributesTransfer.php |
RestShipmentTransfer | class | created | src/Generated/Shared/Transfer/RestShipmentTransfer.php |
RestCheckoutDataResponseAttributesTransfer | class | created | src/Generated/Shared/Transfer/RestCheckoutDataResponseAttributesTransfer.php |
RestShipmentMethodTransfer | class | created | src/Generated/Shared/Transfer/RestShipmentMethodTransfer.php |
CheckoutResponseTransfer | class | created | src/Generated/Shared/Transfer/CheckoutResponseTransfer.php |
CheckoutErrorTransfer | class | created | src/Generated/Shared/Transfer/CheckoutErrorTransfer.php |
AddressTransfer | class | created | src/Generated/Shared/Transfer/AddressTransfer.php |
ShipmentMethodTransfer | class | created | src/Generated/Shared/Transfer/ShipmentMethodTransfer.php |
ShipmentMethodsTransfer | class | created | src/Generated/Shared/Transfer/ShipmentMethodsTransfer.php |
QuoteTransfer | class | created | src/Generated/Shared/Transfer/QuoteTransfer.php |
StoreTransfer | class | created | src/Generated/Shared/Transfer/StoreTransfer.php |
MoneyValueTransfer | class | created | src/Generated/Shared/Transfer/MoneyValueTransfer.php |
CurrencyTransfer | class | created | src/Generated/Shared/Transfer/CurrencyTransfer.php |
ShipmentTransfer | class | created | src/Generated/Shared/Transfer/ShipmentTransfer.php |
CheckoutDataTransfer | class | created | src/Generated/Shared/Transfer/CheckoutDataTransfer.php |
ExpenseTransfer | class | created | src/Generated/Shared/Transfer/ExpenseTransfer.php |
ItemTransfer | class | created | src/Generated/Shared/Transfer/ItemTransfer.php |
RestShipmentMethodsAttributesTransfer | class | created | src/Generated/Shared/Transfer/RestShipmentMethodsAttributesTransfer.php |
RestShipmentsAttributesTransfer | class | created | src/Generated/Shared/Transfer/RestShipmentsAttributesTransfer.php |
RestShipmentsTransfer | class | created | src/Generated/Shared/Transfer/RestShipmentsTransfer.php |
RestAddressTransfer | class | created | src/Generated/Shared/Transfer/RestAddressTransfer.php |
CountryTransfer | class | created | src/Generated/Shared/Transfer/CountryTransfer.php |
RestErrorCollectionTransfer | class | created | src/Generated/Shared/Transfer/RestErrorCollectionTransfer.php |
RestErrorMessageTransfer | class | created | src/Generated/Shared/Transfer/RestErrorMessageTransfer.php |
ShipmentGroupTransfer | class | created | src/Generated/Shared/Transfer/ShipmentGroupTransfer.php |
ShipmentMethodsCollectionTransfer | class | created | src/Generated/Shared/Transfer/ShipmentMethodsCollectionTransfer.php |
RestOrderShipmentsAttributesTransfer | class | created | src/Generated/Shared/Transfer/RestOrderShipmentsAttributesTransfer.php |
RestOrderAddressTransfer | class | created | src/Generated/Shared/Transfer/RestOrderAddressTransfer.php |
OrderTransfer | class | created | src/Generated/Shared/Transfer/OrderTransfer.php |
RestOrderDetailsAttributesTransfer | class | created | src/Generated/Shared/Transfer/RestOrderDetailsAttributesTransfer.php |
RestOrderItemsAttributesTransfer | class | created | src/Generated/Shared/Transfer/RestOrderItemsAttributesTransfer.php |
ShipmentCarrierTransfer | class | created | src/Generated/Shared/Transfer/ShipmentCarrierTransfer.php |
RestOrderExpensesAttributesTransfer | class | created | src/Generated/Shared/Transfer/RestOrderExpensesAttributesTransfer.php |
GiftCardMetadataTransfer | class | created | src/Generated/Shared/Transfer/GiftCardMetadataTransfer.php |
QuoteTransfer.bundleItems | property | added | src/Generated/Shared/Transfer/QuoteTransfer.php |
ShipmentMethodTransfer.name | property | added | src/Generated/Shared/Transfer/ShipmentMethodTransfer.php |
ExpenseTransfer.idSalesExpense | property | added | src/Generated/Shared/Transfer/ExpenseTransfer.php |
CheckoutErrorTransfer.parameters | property | added | src/Generated/Shared/Transfer/CheckoutErrorTransfer.php |
ShipmentMethodsTransfer.shipmentHash | property | added | src/Generated/Shared/Transfer/ShipmentMethodsTransfer.php |
3) Add translations
Add translations as follows:
- Append glossary according to your configuration:
checkout.validation.item.no_shipment_selected,No shipment selected for the cart item %id%.,en_US
checkout.validation.item.no_shipment_selected,Es wurde keine Lieferung für den Warenkorbartikel %id% ausgewählt.,de_DE
- Import data:
console data:import glossary
Make sure that in the database the configured data has been added to the spy_glossary
table.
4) Set up behavior
Set up the following behaviors.
Enable resources and relationships
Activate the following plugins:
PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE |
---|---|---|---|
ShipmentMethodsByCheckoutDataResourceRelationshipPlugin | If RestCheckoutDataTransfer is provided as payload, adds the shipment-methods resource as relationship. |
Spryker\Glue\ShipmentsRestApi\Plugin\GlueApplication | |
OrderShipmentByOrderResourceRelationshipPlugin | If OrderTransfer is provided as a payload, adds the order-shipments resource as a relationship . |
Spryker\Glue\ShipmentsRestApi\Plugin\GlueApplication | |
ShipmentMethodsByShipmentResourceRelationshipPlugin | IfShipmentGroupTransfer is provided as payload, adds the shipment-methods resource as relationship. |
Spryker\Glue\ShipmentsRestApi\Plugin\GlueApplication | |
ShipmentsByCheckoutDataResourceRelationshipPlugin | Adds shipments resource as relationship if RestCheckoutDataTransfer is provided as payload. |
Spryker\Glue\ShipmentsRestApi\Plugin\GlueApplication |
src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php
<?php
namespace Pyz\Glue\GlueApplication;
use Spryker\Glue\CheckoutRestApi\CheckoutRestApiConfig;
use Spryker\Glue\GlueApplication\GlueApplicationDependencyProvider as SprykerGlueApplicationDependencyProvider;
use Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\ResourceRelationshipCollectionInterface;
use Spryker\Glue\ShipmentsRestApi\Plugin\GlueApplication\ShipmentMethodsByCheckoutDataResourceRelationshipPlugin;
class GlueApplicationDependencyProvider extends SprykerGlueApplicationDependencyProvider
{
/**
* @param \Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\ResourceRelationshipCollectionInterface $resourceRelationshipCollection
*
* @return \Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\ResourceRelationshipCollectionInterface
*/
protected function getResourceRelationshipPlugins(
ResourceRelationshipCollectionInterface $resourceRelationshipCollection
): ResourceRelationshipCollectionInterface {
$resourceRelationshipCollection->addRelationship(
CheckoutRestApiConfig::RESOURCE_CHECKOUT_DATA,
new ShipmentMethodsByCheckoutDataResourceRelationshipPlugin()
);
$resourceRelationshipCollection->addRelationship(
OrdersRestApiConfig::RESOURCE_ORDERS,
new OrderShipmentByOrderResourceRelationshipPlugin()
);
$resourceRelationshipCollection->addRelationship(
ShipmentsRestApiConfig::RESOURCE_SHIPMENTS,
new ShipmentMethodsByShipmentResourceRelationshipPlugin()
);
$resourceRelationshipCollection->addRelationship(
CheckoutRestApiConfig::RESOURCE_CHECKOUT_DATA,
new ShipmentsByCheckoutDataResourceRelationshipPlugin()
);
return $resourceRelationshipCollection;
}
}
- To make sure that
ShipmentMethodsByCheckoutDataResourceRelationshipPlugin
is activated, check that the information from theshipment-methods
resource is returned by sending thePOST https://glue.mysprykershop.com/checkout-data?include=shipment-methods
request. - To make sure that
OrderShipmentByOrderResourceRelationshipPlugin
is activated, make sure that the information from theorder-shipments
resource is returned by sending theGET https://glue.mysprykershop.com/orders?include=order-shipments
request. - To make sure that
ShipmentMethodsByShipmentResourceRelationshipPlugin
is activated, make sure that the information from theshipment-methods
resource is returned by sending theGET https://glue.mysprykershop.com/shipments?include=shipment-methods
request. - To make sure that
ShipmentsByCheckoutDataResourceRelationshipPlugin
is activated, make sure that the information from theshipments
resource is returned by sending thePOST https://glue.mysprykershop.com/checkout-data?include=shipments
request.
Configure mapping
To map the data from requests to QuoteTransfer
, configure the following mappers on the project level:
PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE |
---|---|---|---|
ShipmentQuoteMapperPlugin | Adds a mapper that maps shipment information to QuoteTransfer . |
Spryker\Zed\ShipmentsRestApi\Communication\Plugin\CheckoutRestApi | |
ShipmentRestOrderDetailsAttributesMapperPlugin | Maps the shipments from OrderTransfer to RestOrderDetailsAttributesTransfer . |
Spryker\Glue\ShipmentsRestApi\Plugin\OrdersRestApi | |
ShipmentsQuoteMapperPlugin | Maps the shipments from RestCheckoutRequestAttributesTransfer to QuoteTransfer . |
Spryker\Zed\ShipmentsRestApi\Communication\Plugin\CheckoutRestApi |
src/Pyz/Zed/CheckoutRestApi/CheckoutRestApiDependencyProvider.php
<?php
namespace Pyz\Zed\CheckoutRestApi;
use Spryker\Zed\CheckoutRestApi\CheckoutRestApiDependencyProvider as SprykerCheckoutRestApiDependencyProvider;
use Spryker\Zed\ShipmentsRestApi\Communication\Plugin\CheckoutRestApi\ShipmentQuoteMapperPlugin;
use Spryker\Zed\ShipmentsRestApi\Communication\Plugin\CheckoutRestApi\ShipmentsQuoteMapperPlugin;
class CheckoutRestApiDependencyProvider extends SprykerCheckoutRestApiDependencyProvider
{
/**
* @return \Spryker\Zed\CheckoutRestApiExtension\Dependency\Plugin\QuoteMapperPluginInterface[]
*/
protected function getQuoteMapperPlugins(): array
{
return [
new ShipmentQuoteMapperPlugin(),
new ShipmentsQuoteMapperPlugin(),
];
}
}
src/Pyz/Glue/OrdersRestApi/OrdersRestApiDependencyProvider.php
<?php
namespace Pyz\Glue\OrdersRestApi;
use Spryker\Glue\OrdersRestApi\OrdersRestApiDependencyProvider as SprykerOrdersRestApiDependencyProvider;
use Spryker\Glue\ShipmentsRestApi\Plugin\OrdersRestApi\ShipmentRestOrderDetailsAttributesMapperPlugin;
class OrdersRestApiDependencyProvider extends SprykerOrdersRestApiDependencyProvider
{
/**
* @return \Spryker\Glue\OrdersRestApiExtension\Dependency\Plugin\RestOrderDetailsAttributesMapperPluginInterface[]
*/
protected function getRestOrderDetailsAttributesMapperPlugins(): array
{
return [
new ShipmentRestOrderDetailsAttributesMapperPlugin(),
];
}
}
Configure the shipment method validator plugin and selected shipment method mapper plugin
Activate the following plugins:
PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE |
---|---|---|---|
SelectedShipmentMethodCheckoutDataResponseMapperPlugin | Maps the selected shipment method data to the checkout-data resource attributes. |
Spryker\Glue\ShipmentsRestApi\Plugin\CheckoutRestApi | |
ShipmentMethodCheckoutDataValidatorPlugin | Validates shipment methods. | Spryker\Zed\ShipmentsRestApi\Communication\Plugin\CheckoutRestApi |
src/Pyz/Glue/CheckoutRestApi/CheckoutRestApiDependencyProvider.php
<?php
namespace Pyz\Glue\CheckoutRestApi;
use Spryker\Glue\CheckoutRestApi\CheckoutRestApiDependencyProvider as SprykerCheckoutRestApiDependencyProvider;
use Spryker\Glue\ShipmentsRestApi\Plugin\CheckoutRestApi\SelectedShipmentMethodCheckoutDataResponseMapperPlugin;
class CheckoutRestApiDependencyProvider extends SprykerCheckoutRestApiDependencyProvider
{
/**
* @return \Spryker\Glue\CheckoutRestApiExtension\Dependency\Plugin\CheckoutDataResponseMapperPluginInterface[]
*/
protected function getCheckoutDataResponseMapperPlugins(): array
{
return [
new SelectedShipmentMethodCheckoutDataResponseMapperPlugin(),
];
}
}
src/Pyz/Zed/CheckoutRestApi/CheckoutRestApiDependencyProvider.php
<?php
namespace Pyz\Zed\CheckoutRestApi;
use Spryker\Zed\CheckoutRestApi\CheckoutRestApiDependencyProvider as SprykerCheckoutRestApiDependencyProvider;
use \Spryker\Zed\ShipmentsRestApi\Communication\Plugin\CheckoutRestApi\ShipmentMethodCheckoutDataValidatorPlugin;
class CheckoutRestApiDependencyProvider extends SprykerCheckoutRestApiDependencyProvider
{
/**
* @return \Spryker\Zed\CheckoutRestApiExtension\Dependency\Plugin\CheckoutDataValidatorPluginInterface[]
*/
protected function getCheckoutDataValidatorPlugins(): array
{
return [
new ShipmentMethodCheckoutDataValidatorPlugin(),
];
}
}
To make sure that SelectedShipmentMethodCheckoutDataResponseMapperPlugin
is activated, send the POST https://glue.mysprykershop.com/checkout-data
request endpoint with shipment a method id and check that, in the response, the selectedShipmentMethods
is not empty:
Response sample
{
"data":
{
"type": "checkout-data",
"id": null,
"attributes": {
"addresses": [],
"paymentProviders": [],
"shipmentMethods": [],
"selectedShipmentMethods": [
{
"id": 1,
"name": "Standard",
"carrierName": "Spryker Dummy Shipment",
"price": 490,
"taxRate": null,
"deliveryTime": null,
"currencyIsoCode": "EUR"
}
],
...
}
}
}
To verify that ShipmentMethodCheckoutDataValidatorPlugin
is activated, send the POST https://glue.mysprykershop.com/checkout
request and check that you get the error saying that a shipment method is not found.
Configure the multi-shipment method validator and expander plugins
Activate the following plugins:
PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE |
---|---|---|---|
AddressSourceCheckoutRequestValidatorPlugin | Validates the attributes of given shipments and returns an array of errors if necessary. | Spryker\Glue\ShipmentsRestApi\Plugin\CheckoutRestApi | |
ShipmentDataCheckoutRequestValidatorPlugin | Checks if RestCheckoutRequestAttributesTransfer provides shipment data per item or per order. |
Spryker\Glue\ShipmentsRestApi\Plugin\CheckoutRestApi | |
ItemsCheckoutDataValidatorPlugin | Checks if CheckoutDataTransfer provides shipment data per item and per bundle item. |
Spryker\Zed\ShipmentsRestApi\Communication\Plugin\CheckoutRestApi | |
ItemsReadCheckoutDataValidatorPlugin | Checks if CheckoutDataTransfer provides shipment data per item and bundle item. |
Spryker\Zed\ShipmentsRestApi\Communication\Plugin\CheckoutRestApi | |
ShipmentCheckoutDataExpanderPlugin | Expands RestCheckoutDataTransfer with available shipment methods. |
Spryker\Zed\ShipmentsRestApi\Communication\Plugin\CheckoutRestApi |
src/Pyz/Glue/CheckoutRestApi/CheckoutRestApiDependencyProvider.php
<?php
namespace Pyz\Glue\CheckoutRestApi;
use Spryker\Glue\CheckoutRestApi\CheckoutRestApiDependencyProvider as SprykerCheckoutRestApiDependencyProvider;
use Spryker\Glue\ShipmentsRestApi\Plugin\CheckoutRestApi\AddressSourceCheckoutRequestValidatorPlugin;
use Spryker\Glue\ShipmentsRestApi\Plugin\CheckoutRestApi\ShipmentDataCheckoutRequestValidatorPlugin;
class CheckoutRestApiDependencyProvider extends SprykerCheckoutRestApiDependencyProvider
{
/**
* @return \Spryker\Glue\CheckoutRestApiExtension\Dependency\Plugin\CheckoutRequestValidatorPluginInterface[]
*/
protected function getCheckoutRequestValidatorPlugins(): array
{
return [
new ShipmentDataCheckoutRequestValidatorPlugin(),
new AddressSourceCheckoutRequestValidatorPlugin(),
];
}
}
src/Pyz/Zed/CheckoutRestApi/CheckoutRestApiDependencyProvider.php
<?php
namespace Pyz\Zed\CheckoutRestApi;
use Spryker\Zed\CheckoutRestApi\CheckoutRestApiDependencyProvider as SprykerCheckoutRestApiDependencyProvider;
use Spryker\Zed\ShipmentsRestApi\Communication\Plugin\CheckoutRestApi\ItemsCheckoutDataValidatorPlugin;
use Spryker\Zed\ShipmentsRestApi\Communication\Plugin\CheckoutRestApi\ItemsReadCheckoutDataValidatorPlugin;
use Spryker\Zed\ShipmentsRestApi\Communication\Plugin\CheckoutRestApi\ShipmentCheckoutDataExpanderPlugin;
class CheckoutRestApiDependencyProvider extends SprykerCheckoutRestApiDependencyProvider
{
/**
* @return \Spryker\Zed\CheckoutRestApiExtension\Dependency\Plugin\CheckoutDataValidatorPluginInterface[]
*/
protected function getCheckoutDataValidatorPlugins(): array
{
return [
new ItemsCheckoutDataValidatorPlugin(),
];
}
/**
* @return \Spryker\Zed\CheckoutRestApiExtension\Dependency\Plugin\ReadCheckoutDataValidatorPluginInterface[]
*/
protected function getReadCheckoutDataValidatorPlugins(): array
{
return [
new ItemsReadCheckoutDataValidatorPlugin(),
];
}
/**
* @return \Spryker\Zed\CheckoutRestApiExtension\Dependency\Plugin\CheckoutDataExpanderPluginInterface[]
*/
protected function getCheckoutDataExpanderPlugins(): array
{
return [
new ShipmentCheckoutDataExpanderPlugin(),
];
}
}
To make sure that the plugins are activated, send the POST https://glue.mysprykershop.com/checkout
request with invalid shipments and check that errors are returned.
Related features
Integrate the following related features.
FEATURE | REQUIRED FOR THE CURRENT FEATURE | INTEGRATION GUIDE |
---|---|---|
Glue API: Checkout | ✓ | Install the Checkout Glue API |
Thank you!
For submitting the form