Scoping out an integration into a new system can be challenging, so we have compiled some quick-start guides for some of the most common scenarios that we encounter day-to-day. These guidelines are intended as a starting point and are not comprehensive specifications for every integration.
Best Practices
Regardless of the type of integration you're writing, here are some common points worth remembering.
The API has a request limit of approximately 60 requests per minute (this is applied at 15 requests per 15-second rolling window). This number includes all calls related to authentication, saving data and requesting data.
Batch your data when importing it. The suggested batch size is roughly 1000 lines per call.
Avoid calling reports for data where possible. Event subscriptions are designed to provide the information you need for the most common integration use-cases. Events that Peoplevox sends to your endpoint do not count toward your API request limits.
Avoid multiple concurrent API connections running in parallel. You should wait for each call to be completed before making the next.
Remove any special characters, symbols or emojis before sending data to the WMS. These can often appear in customer data coming from ecommerce systems.
Integrations should also implement a sensible retry policy for any API calls that fail, based on the nature of that failure.
If an API call fails because of a data or structural issue (e.g., a missing key field, incorrectly structured request, etc.), then a retry will fail for the same reason. These should not be automatically retried and should instead be escalated to a human for manual review to fix the issue before syncing again.
If an API call fails because of a timeout, then the dataset you are trying to interact with is likely too large. This is typically not a failure mode for saving data to the API, but large report requests can encounter timeouts. An identical call being retried a second time is likely to fail for the same reason. These should not be automatically retried as-is. A timeout when retrieving data from a report typically indicates insufficiently restrictive filtering on that report. These should be flagged for a human to manually review so that appropriate filters can be applied to those calls (e.g., a datetime range to limit the scope of data retrieval).
If an API call fails because of a temporary network issue, then a retry may be successful with no structural changes to the request. We suggest using an incremental back-off period for these sorts of retries, and you should also enforce a clear upper limit on the total number of retries. If a call is consistently failing after three attempts, it should be logged for review but not continually retried.
If an API call fails because of API rate limiting, then an automatic retry is likely to make the problem worse. If a request is blocked in this way, the retry should be queued using the incremental back-off policy described above to ensure that the rate of traffic remains within the limit. We strongly recommend that you track how often your integration encounters rate-limiting events, as it is important to review these regularly to identify any changes that may be needed to batch sizes or call frequencies.
Writing an Integration Between Peoplevox and an Ecommerce Platform
Ecommerce platforms are one of the most common systems integrated into Peoplevox. A typical ecommerce integration would support the following features:
Sync product data from the ecommerce system to Peoplevox
Sync sales order and customer data from the ecommerce system to Peoplevox
Sync inventory changes from Peoplevox to the ecommerce system
Sync order fulfilments and tracking data from Peoplevox to the ecommerce platform
Some ecommerce platforms also integrate with the Peoplevox returns process, but the scope of this integration tends to vary. Generally, an ecommerce integration only cares about the quantity of each product available for sale; it typically does not need to know about each individual transaction that led to that figure. Similarly, most ecommerce systems are not designed to support purchasing, so a typical integration would not sync this data.
Feature |
Detail |
Purpose |
SaveData API call |
Item types template |
Used to push product data into Peoplevox |
SaveData API call |
Customers template |
Used to push customer data into Peoplevox |
SaveData API call |
Sales orders template |
Used to push sales order header data into Peoplevox |
SaveData API call |
Sales order items template |
Used to push sales order item line data into Peoplevox |
AvailabilityChanges event subscription |
Used to notify the ecommerce platform of changes in availability for each item in the warehouse |
|
DespatchPackageDespatched event subscription |
Used to notify the ecommerce platform of the goods that have been shipped from the warehouse |
|
DespatchPackageTrackingNumberReceived event subscription |
Used to notify the ecommerce platform when a tracking number is received from the carrier for a given package |
A common variation on this pattern is often to include the use of the Returns event subscription (to notify the ecommerce platform when goods are returned against sales orders). Some platforms may use this to help automate the process for raising credit notes to customers.
Writing an Integration Between Peoplevox and an ERP System
ERP integrations are typically more complex than ecommerce platform integrations, as an ERP often manages a larger proportion of data within the business. A typical ERP integration would support the following features:
Sync product data from the ERP to Peoplevox
Sync sales order and customer data from the ERP to Peoplevox
Sync purchase order and supplier data from the ERP to Peoplevox
Sync ad-hoc inventory transactions (e.g., stock take, removal due to shrinkage, etc.) from Peoplevox to the ERP
Sync sales order fulfilments and tracking data from Peoplevox to the ERP
Sync purchase order receipts from Peoplevox to the ERP
One of the key differences between an ERP and an ecommerce integration is the level of detail that those systems typically require when it comes to inventory updates. Generally, an ecommerce integration wants to obtain the total available figure for sale, whereas an ERP instead cares about the individual changes in inventory and the reasons for those changes.
Similarly, a typical ERP integration synchronises both sales orders and purchase orders (as well as the fulfilment of each), which means that the ERP often already knows about most inventory changes. ERP integrations often synchronise returns data from Peoplevox as well. This is why an ERP integration would typically synchronise only the unplanned inventory changes (i.e., those that the ERP was not already expecting to occur).
The following tools may be useful to an integrator building a basic ERP integration:
Feature |
Detail |
Purpose |
SaveData API call |
Item types template |
Used to push product data into Peoplevox |
SaveData API call |
Customers template |
Used to push customer data into Peoplevox |
SaveData API call |
Sales orders template |
Used to push sales order header data into Peoplevox |
SaveData API call |
Sales order items template |
Used to push sales order item line data into Peoplevox |
SaveData API call |
Suppliers template |
Used to push supplier data into Peoplevox |
SaveData API call |
Purchase orders template |
Used to push purchase order header data into Peoplevox |
SaveData API call |
Purchase order items template |
Used to push purchase order item line data into Peoplevox |
IncrementalChanges event subscription |
Note: This event provides the changes rather than the absolute figures and can be filtered to exclude changes of a particular type. |
Used to notify the ERP of the changes in availability for each item in the warehouse |
DespatchPackageDespatched event subscription |
Used to notify the ERP of the goods that have been shipped from the warehouse against an order |
|
DespatchPackageTrackingNumberReceived event subscription |
Used to notify the ERP when a tracking number is received from the carrier for a given package |
|
GoodsReceived event subscription |
Includes items receipt data whether they are received against a PO |
Used to notify the ERP of goods that are received into the warehouse |
Returns event subscription |
Used to notify the ERP of goods that are returned by customers to the warehouse against a sales order |
The variations between ERP integrations tend to emphasize the differing workflows between businesses. This generally manifests as a change in the trigger for synchronisation (for example, many ERPs have approval mechanisms that prevent purchase orders being submitted to the warehouse until they have been authorised).
Writing an Integration Between Peoplevox and an IPaaS System / Integration Platform
Integrations into dedicated integration platforms are often hard to define because the scope of required functionality depends on either the other connectors available on the platform or the specific purpose of the integration. Often, a connector into an integration platform is a scalable means to achieve one of the two scenarios described above, so those are good places to start.
The added complexity of an integration platform is that the connector with Peoplevox may need to be capable of supporting both types of integration (and potentially others). The decision point for integration partners here is around how the platform needs to obtain inventory updates from Peoplevox.
Some platforms may choose to support both the AvailabilityChanges and the IncrementalChanges and subscribe to the most appropriate one for each Client. Others may subscribe to IncrementalChanges in every case and use that to construct a total inventory figure if required.
Writing an Integration Between Peoplevox and a Carrier System
These integrations are a little different to ERP and ecommerce platform integrations. Integrations with carriers rely on real-time communication to obtain labels and other documentation, so Peoplevox provides a different set of tools for these.
Read more about building carrier integrations here.
Connecting Your Systems Manually
If you're not quite ready to automate your integration just yet, you can use the web app to upload your orders and to export end-of-day inventory and fulfilment files.
To import orders, you will need to create a CSV file with the following columns. If your marketplace system is unable to export the data in this format, you will need to use a spreadsheet program or similar to transform the files from the marketplaces into this format:
SalesOrderNumber (the order number from the marketplace - this will need to be unique across all orders)
RequestedDeliveryDate (the date selected for delivery, or just the current date if that is not available)
Site (the reference of the site in Peoplevox that will fulfil the order)
ShippingAddressLine1
ShippingAddressLine2
ShippingAddressCity
ShippingAddressRegion
ShippingAddressPostcode
ShippingAddressCountry
ContactName (the name of the customer)
ServiceType (the shipping service selected by the customer)
ItemCode (the product SKU)
QuantityOrdered
SalePrice
Next, just navigate to the Integration section of the web app, and then to the Integration Templates tab.
Click on Sales orders, and import this CSV file, then
Click on Sales order items, and import this file