Interprise Web Services

Getting Started

Interprise Web Services (IWS) provides REST APIs for Inteprise Suite. These REST APIs are for developers who need to integrate with Interprise Suite into their applications.

Setup

You're already done with the installation. Before you can start, you need to do some configuration:

  1. Register the IWS Plugin in Interprise Suite.
  2. Generate API key for your application.

Register IWS Plugin

Before you can use IWS you need to register the plugin in Interprise Suite. The plugin allows you to generate API keys that you need.

Open Interprise Suite and navigate to System Manager > Tools > Plugin Manager.


The Plugin Manager opens, click Add Plugin.


Select the plugin file Interprise.Presentation.IWSPlugin.dll in C:\inetpub\wwwroot\Interprise.Web.Services\bin\.


Wait as the plugin registers.


Check the Interprise Web Services (IWS) and Administrator to allow access to administrator exclusively.


Click Ok and wait for the registration to finish. Then restart Interprise Suite to apply the change.

Generate API Key

You can generate API keys using the Interprise Web Services (IWS) Plugin. After you register the IWS Plugin, this utility will appear under System Manager > Tools > Interprise Web Services (IWS)> API User Setup.


Go to File > New.


Select user name and assign API Keys and click Save and Close.


The API Key is now created. Copy the key to your application and start using the API.


Request

IWS API is based on REST.


Endpoint

The endpoint of IWS API is http://api.interprise.co.uk:82/.


Authentication

Basic Authentication is used to authorize API calls. You will need an API key for each API calls you make, please refer to Generate API Key. Although basic authentication uses two (2) parameters, username and password, we only require the username which is the API key (and the password is blank).


Accept Header

Accept header allows the consumer to select a response format to expect. IWS expect the following accept header values:

  • application/json or text/json
  • application/xml or text/xml

When accept header is not provided it defaults to json format.


Pagination

List endpoints always return paged results. The result count is limited by the given page size (default 10). And the result contains links metadata with url of paged data.


The pagination strategy used is page-based and use the following querystring parameters:

  • page[number] - the number of the page
  • page[size] - the size of the page

When these parameters are not provided the defaults are as follows: page[number] is 1 and page[size] is 10.


Sorting

Just like pagination, list endpoints are always sorted. The default sorting is different for each endpoint and is not standardized. To sort the result use sort querystring parameters by passing the attribute name, by default the sort order is ascending, to make it descending prefix - in the attribute name. Example:

  • Ascending - http://api.interprise.co.uk:82//pricing/retail?sort=itemCode
  • Descending - http://api.interprise.co.uk:82//pricing/retail?sort=-itemCode

    Response

    We use HTTP response codes to indicate the status of the API call. Below are the HTTP response codes:

    • 200 (Ok) - API call is a success.
    • 400 (Bad Request) - Request from client is invalid.
    • 401 (Unauthorized) - API Key is invalid or not provided.
    • 404 (Not Found) - The request resulted to a inexistent/null resource.
    • 500-504 (Server Errors) - Server execution failed.

    Codes 2xx indicate a successful API call, 4xx codes indicate an incorrect format/parameter by the caller and 5xx codes indicate a server error.


    Error Handling

    We strongly suggest you to write the API consumer to handle the errors. You should provide features such as logging, retries, notifications, etc.

    Change Log

    Change log is an endpoint that provides recorded changes in the data of a resource. The change are categorize into actions which be can be one of the following:

    • INSERT - action for creating the resource (e.g. create a sales order).
    • UPDATE - action when data was changed (e.g. update pricing).
    • DELETE - action when the resource is deleted (e.g. delete a contact).

    Below are the list of available resources:

    • Customer
    • CustomerShipTo
    • CustomerSpecialPrice
    • CustomerSalesOrder
    • CustomerSalesOrderDetail
    • CustomerSalesOrderWorkflow
    • CustomerItemKitDetail
    • CustomerInvoice
    • CustomerInvoiceDetail
    • CRMContact
    • CRMActivity
    • CRMLead
    • CRMNote
    • InventoryItem
    • InventoryItemDescription
    • InventoryItemPricingDetail
    • InventoryPricingLevel
    • InventorySpecialPricing
    • InventoryItemDepartment
    • InventoryItemWebOption
    • InventoryItemWebOptionDescription
    • InventoryUnitMeasure
    • InventoryCategory
    • InventoryKit
    • InventoryKitDetail
    • InventoryKitPricingDetail
    • InventoryKitDetailDescription
    • InventoryKitOptionGroup
    • InventoryKitOptionGroupDescription
    • InventoryMatrixGroup
    • InventoryMatrixItem
    • InventoryStockTotal
    • InventoryBatchSerial
    • InventoryBatchSerialHistory
    • InventorySupplier
    • InventorySupplierPricingLevel
    • ProjectCosting_CostHeadings_IUK
    • ProjectCosting_Employees_IUK
    • ProjectCosting_ExpectedItems_IUK
    • ProjectCosting_PayRates_IUK
    • ProjectCosting_Preferences_IUK
    • ProjectCosting_Project_IUK
    • ProjectCosting_ProjectCostHeadings_IUK
    • ProjectCosting_ProjectEstimatedMaterials_IUK
    • ProjectCosting_ProjectEstimatedOther_IUK
    • ProjectCosting_ReservedItem_IUK
    • ProjectCosting_ReservedItemDetails_IUK
    • ProjectCosting_Stages_IUK
    • ProjectCosting_TimeSheetExpense_IUK
    • SystemCategoryWebOption
    • SystemCategoryWebOptionDescription
    • SystemCategoryBand
    • SystemCategoryDiscount
    • SystemPaymentTerm
    • SystemPaymentTermGroup
    • SystemShippingCarrier
    • SystemShippingMethod
    • SystemShippingMethodDetail
    • SystemShippingMethodGroup
    • SystemShippingMethodGroupDetail
    • SystemTaxDetail
    • SystemTaxScheme
    • SystemTaxSchemeDetail
    • SupplierPurchaseOrder

    The response from this endpoint differs depending on the action. INSERT shows the newly created resource, UPDATE shows old and new data, and DELETE shows the delete resource.

    For usage of this endpoint please refer to GET changelog/{resource}?from={from}&to={to}

    Testing

    We recommend the Chrome Extension Postman for testing the API.


    Please check Postman Documentation on how to use the tool. Below shows sample API call using Postman.