The SAGE® Connect API™ is a full-featured set of application programming interfaces (APIs) for bi-directional integration with SAGE services. Unlike our other tools that are turn-key solutions, the Connect API is designed specifically for developers who are interested in performing direct, real-time integrations with SAGE services. Customers with development capabilities can use the APIs themselves. There are also a number of third-party service providers that will provide integration services on behalf of a SAGE distributor or supplier customer.
The XML API
The recently deprecated Sage XML API request, once an integral tool in accessing product information, has now expired, necessitating a shift in the approach to retrieving crucial details.The advanced API request has been specifically engineered to provide comprehensive product details based on a specified supplier ID. The enhanced functionality of this API not only ensures a seamless transition from the obsolete version but also offers an enriched user experience by delivering a wealth of information related to products associated with a particular supplier.
The Old XML API Format:
The Connect API
The Connect API is designed with a modular architecture, offering users a flexible and customizable experience. Within this framework, various modules have been developed to cater to specific functionalities and services like “Research List”, “Product Search” , “Basic Product Detail” , “Full Product Detail” , “Presentations” , “Order Forms” , “Credit Card Transaction”.
In this new API format, we need to make two API requests to retrieve product data. The first one uses the supplier ID to obtain all product IDs, and the second one is used to get the full product details based on a particular product ID.
New JSON API Format:
Note:
The above credentials are for example purposes only. You will need to use your own credentials.
- The response will be provided in JSON format as well. Specific response fields are detailed in the documentation for each request.
- If an error is encountered, a standard error structure will be returned. The error structure contains an error number (ErrNum field) and an error message (ErrMsg field).
- Server load balancing and redundancy for failover is handled automatically on the service side.
The JSON data should be UTF-8 encoded. This means specifically that all “special” or “extended” characters must be identified in UTF-8 format in order to display correctly. Likewise, the data response from the service will be provided in UTF-8 format.
Key Points Of The Connect API
-
Pricing
Some modules are free and others are paid. Distributors are given a monthly Total Access Credit of 5,000 queries per month per paid Total Access user license on the account. These credits will apply to all fee-based modules, meaning that you will only be charged if the user exceeds the monthly credit. Modules that are fee-based are indicated as such on the dashboard. Note that unused credits do not carry forward.
Please note that all data obtained from the Connect API may only be used by accounts with an active Total Access Subscription or Supplier Advantage Membership.
-
Query Limits
You can configure a monthly query limit for each user. These limits will only apply to queries for fee-based modules. By default, the query limits are set to 5,000 so that there will not be any charges for usage without your express authorization (by increasing the query limit). You can view and edit query limits from a sage account.
Please note that all data obtained from the Connect API may only be used by accounts with an active Total Access Subscription or Supplier Advantage Membership.
-
Preparing Your Application
The Connect API uses normal HTTPS posts with JSON payloads to send requests and receive responses. This will happen in a separate back channel from your application. For example, if you are powering a website with SAGE data, you would perform a separate HTTPS post to our service from your web server, obtain the results, and then format those results in the response to the web user.
You can use any programming language and component that you wish to implement the connection to the Connect API. Implementations are possible with Javascript, .NET, ASP, Visual Basic, Perl, C/C++, and any other language that is capable of creating an HTTPS post. Connections are made over the standard HTTPS port (port 443) using encryption. Based on current security recommendations and best practices, connections must be encrypted using TLS 1.1 or 1.2 (not SSL or TLS 1.0).
The requests should be submitted as posts to the following address:
https://www.promoplace.com/ws/ws.dll/ConnectAPI
-
Authentication
Each request sent to the server must be accompanied with an Account #, Login ID, and the associated authentication key. This information is used to identify the request for authentication, access control and logging purposes.
-
Caching
In most cases, we recommend that you access the service in real-time and do not cache data. This is generally the easiest way to implement the services and also ensures that you have the most up-to-date information in your integrated application. However, in advanced implementations or integrations that are going to have high activity, you may want to consider caching the data to reduce the number of requests sent to the service.
-
Network and Performance
The SAGE Connect API operates from SAGE’s wholly-owned and operated network centers. We have redundant connections to the Internet, redundant servers and other equipment, redundant power systems, and a variety of other equipment to help ensure reliability and performance. Our networks are monitored 24/7/365 for reliability, performance, and security issues. Our systems are upgraded often for increased performance.
The connection to the Connect API operates separately from the connection between your user and your server. Essentially, your user’s connection is put “on hold” while your server communicates with the Connect API and receives a response. Therefore, it is important that your server be hosted at a location that has a very good connection to the Internet.
Wrapping Up
The transition from the deprecated Sage XML API to the versatile Connect API offers developers a powerful and customizable tool for seamless integration with SAGE services. The modular architecture, transparent pricing, and monthly Total Access Credits ensure cost-effective and flexible usage. Clear guidelines on query limits, authentication, and network performance contribute to a secure and reliable integration process.
With the Connect API, developers gain access to enhanced functionality and a robust, redundant network infrastructure, marking a significant step forward in simplifying and optimizing real-time interactions with SAGE services.
