General
Its very normal for Distributors to require “clarifying information” when integrating with Suppliers. This can range from “mechanical concerns” (such as: When are established maintenance windows? How do I get notified of outages? Do I need to be whitelisted for access?) and some are more “business concerns” (such as: What might it mean when an order is on General Hold?). It is a best practice for Suppliers to take these kinds of recurring questions and proactively put their answers into an integration guide which can be made available for Distributors.
Some real-world sample integration guides from Suppliers:
Alphabroder: https://www.alphabroder.com/static/pdf/PromostandardsIntegrationGuideV4.pdf
SanMar: https://www.sanmar.com/resources/electronicintegration/integrationofferings (PDF Guides at the bottom right of the page)
Koozie Group Integration and Best Practices:
Data / Business Mapping
Order Status API
It is common for suppliers to have more status codes than is enumerated in the API specification; a brief mapping should be provided so that Distributors know where to expect “known statuses” that are used in daily business practices
PromoStandards StatusID | PromoStandards Status Name | Supplier Statuses Represented |
10 | Order Received | |
11 | Order Entry Hold | |
20 | Order Confirmed | |
30 | Pre-Production | |
40 | General Hold | |
41 | Credit Hold | |
42 | Proof Hold | |
43 | Art Hold | |
44 | Back Order Hold | |
60 | In Production | |
70 | In Storage | |
75 | Partial Shipment | |
80 | Complete | |
99 | Canceled |
Allowed Date Ranges
Maximal days back supported for date-range invoice API requests?
Maximal days back supported for date-range order status API requests?
Maximal days back supported for date-range order shipment notification API requests?
Access Restrictions
What is the process for a Distributor to get credentials?
What information will be required as part of that process?
Are there any geographic restrictions to API’s?
Is there a requirement to whitelist IP numbers?
Is any kind of rate limiting in place?
If so, what are the details of the rate limiting?
Are there any other security/access constraints that a Distributor would need to know?
Maintenance Windows
When are the maintenance windows?
How are Distributors notified of maintenance?
Is there anything a Distributor needs to do to get notified proactively?
Are there any times of the day when API’s are offline due to scheduled processing?
If so, which API’s and what times?