There are several steps to integrating Ingrid into your ecosystem depending on which products you will be using. This article includes what you need to get started with integration, as well as WMS integration and custom integration.
Generally speaking, adding the products themselves is straightforward, what requires a bit more consideration and planning is how data will flow between Ingrid and the rest of your systems.
1.1 Dataflow in a generalized e-com stack
The diagram above depicts a generalized e-com stack; some setups have more systems and others have fewer and they might be connected in different ways.
Delivery Checkout Widget Integration
Starting from the left-hand side of diagram 1.1 you have your e-com system. Ingrid Delivery Checkout widget is fetched by the e-com and then inserted into the checkout. The e-com will be responsible for keeping Ingrid up to date with data such as cart items and customer information. In turn, the widget will communicate with Ingrid to ensure that the customer is presented with the appropriate delivery options. A more in-depth technical guide on how to integrate the widget is available in SIW API Documentation. Ingrid also provides plugins for a number of e-com platforms described in Ingrid E-com plugins.
Once the purchase has been made a transport order is created in Ingrid. The transport order contains all information necessary for making a shipment booking. Each transport order is associated with a unique identifier called TOS ID. The transport order can be retrieved from Ingrid at any time using the TOS ID. Additionally, it is also common to store some transport data in the e-com system, i.e. selected carrier product.
The next step is to figure out how we book a shipment with the transport data that was produced in the checkout.
Booking a shipment via your TA system
In a regular e-com stack, the TMS is responsible for producing labels and book shipments with carriers. Ingrid offers its own TMS but it is just as common to use a TMS system from another vendor.
In order to create a booking, the transport data produced in the checkout must be communicated to the TMS. There are two common ways of achieving this
- Transfer all required data through intermediary systems, i.e ERP
- Transfer only TOS ID through intermediary systems
Depending on your current setup one solution might be preferable to the other.
Transfer all required data
The classic approach to communicate transport data with the TMS is to move all required data through an intermediary system, usually the ERP and WMS. This is a straightforward approach that is simple to understand but comes with a number of drawbacks.
- You will have to know beforehand which data points are required for booking
- If the required data points change, i.e adding support for sending add-ons, an update to the ERP might be needed
- ERP will have to handle the data
The key takeaway from using this approach is to understand which data points are required for booking and make sure that any intermediary system can handle them.
Transfer only TOS ID
An alternative approach to sending all required data is to send the TOS ID instead. Using the TOS ID any system, provided that they have the credentials, can fetch the transport order and all data necessary for booking. In practice, this usually translates into moving the TOS ID through the ERP and the WMS will fetch transport data from Ingrid and then book the shipment. If Ingrid is used as TA only the TOS ID and a number of parcels are required for booking a shipment since Ingrid.
The benefits of using this approach are
- Smaller integration surface toward ERP
- If the required data points for creating booking changes, any intermediate system does not need to be updated to reflect the change
WMS Integration
Before you start
Fetching Transport orders from Ingrid
When a purchase is completed on the e-commerce platform a transport order is created in Ingrid's system. The transport order contains all necessary data required for making a booking with TMS-system. All transport orders receive a unique transport order id (TOS ID) which can be used at any time to retrieve the associated transport order data.
You can view and/or create transport orders in Ingrid's admin dashboard (IMP) located at either https://mad-stage.ingrid.com or https://mad.ingrid.com depending on the environment.
Retrieve transport order data from Ingrid with the following request.
curl https://api.ingrid.com/v1/siw/sessions_summaries.list?tos_id=01EYRA0ZQ7XTZD4M1JKY65G3FP \
--header 'Authorization: Bearer ...'
Depending on the environment use either api.ingrid.com for production or API-stage.ingrid.com for the stage as host. In the response, you will receive a list of results since a transport order can be reopened multiple times and each result is associated with the TOS ID. The results are stored "latest first" so if you pick the first result you will always have the latest data. More on the result field can be found here and here.
Custom integration
To integrate your e-commerce site with the Ingrid SIW service please visit our Documentation.