Introduction to building a Custom Integration to Pipe17

The goal of this article is to introduce different ways an external system can be integration into the platform using a custom connector (aka custom integration).

Approaches

1. Custom Integration Framework (Recommended)
2. REST API-based Connection (Legacy)

Custom Integration Framework (Recommended)

Integration based on an officially registered custom connector using the Integration > Add Custom Integration process. The admin registering the connector can specify the type of connector to get a recommended set of grants. Admin can adjust the grants as needed. The platform automatically generates a connector and an integration API Key. The connector as well as the integration are registered for the organization as a private connector. Only this organization can see it, use it. 

Pros

• Best for a tighter, more functional rich integration experience
• Easy steps to register and get a connector API Key from the platform UI and hand over to the integration partner along with the platform API Doc reference and this document
• The access to the API Key is restricted to the data meant for or owned by the integration; no leakage of data possible
• The integration is visible under Integration list on the UI
• All interaction by the external system using this API Key is registered under the respective integration
• All events are registered under the respective integration
• All UI pages that allow filtering data will show this integration as an option
• Integration developer can expose settings and even mappings for org admin to control the behavior; integration code has to read these values and honor them
• Org admin can disable and re-enable integration, export configuration, etc., just like any other integration

Cons

• Level of development effort needed depends on the features the integration wants to expose
• The platform provides a framework to expose settings, and mappings but the real implementation to honor those is still the responsibility of the custom integration code. 
• The integration code has to run outside of the platform

How to integrate using the Custom Integration Framework

Reference the following 8 part series explaining in depth how how one can build a custom integration with varying degree of functionality along with reference (sample) implementation.

1. Chapter 1: Key Concepts for building Custom Connections
2. Chapter 2: Adding a Custom 3PL Connection (aka Integration)
3. Chapter 3: Implementing Connection Code
4. Chapter 4: Implementing Locations Workflow
5. Chapter 5: Implementing Orders & Fulfillment Workflow
6. Chapter 6: Implementing Products Workflow
7. Chapter 7: Implementing Inventory Workflow
8. Chapter 8: Reference Resources

API-based Connection (Legacy)

PLEASE NOTE THIS IS LEGACY WAY OF INTEGRATING WITH PIPE17.

Connection based on a user-created API Key from the UI, under Settings > API Key. The API Key is owned and associated to the user who created the key. The admin can set grants on resource types allowed for this API Key. The admin can also terminate the key, if required.

Pros

• Simple to get started; create an API Key from the platform UI and hand over to the integration partner along with the platform API Doc reference and this document.
• Best if the touch point is very limited

Cons

• The API key has access to all data for the granted resource type; as opposed to only data meant for or owned by that integration; leakage of data possible
• All events by the API Key will show as initiated by the admin who created the API Key
• No footprint of an integration in the customer org; no entity to control under the integration list
• No settings or controls can be presented to the user/admin for this integration
• No way to automatically rotate API Key; it will be a manual process
• API caller has to implement all platform functionality outside of the platform, such as: 
  • Inventory Buffer
  • SKU Mapping
  • Product Channel Sync
  • Shipping Method Mapping

How to integrate using the API-based Connection

Refer to this guide on how to integrate using API base connection.