ICIX API v3.0 Introduction
This API allows programmatic interaction with ICIX over HTTPS. This site will explain how to connect to your ICIX org, then execute commands and read the results.
This ICIX API site is for ICIX API v3.0
Recent Updates
Async parameter added. If set to true, the json will be stored and processed asynchronously. Async processing supports larger payloads than synchronous processing.
Error logging added. Errors that occur during API requests are now stored along with the original payload from the client.
Setup - All Versions
String targetUrl = "https://[instance].salesforce.com/services/oauth2/token";
HttpsClient HttpsClient = new DefaultHttpsClient();
HttpsPost post = new HttpsPost(targetUrl);
List<BasicNameValuePair> parametersBody = new ArrayList<BasicNameValuePair>();
parametersBody.add(new BasicNameValuePair("grant_type", "password"));
parametersBody.add(new BasicNameValuePair("username", username));
parametersBody.add(new BasicNameValuePair("password", password));
parametersBody.add(new BasicNameValuePair("client_id", consumerKey));
parametersBody.add(new BasicNameValuePair("client_secret", consumerSecret));
try{
post.setEntity(new UrlEncodedFormEntity(parametersBody, HTTPS.UTF_8));
HttpsResponse response = httpsClient.execute(post);
int code = response.getStatusLine().getStatusCode();
String oauthLoginResponse = EntityUtils.toString(response.getEntity());
Gson gson = new Gson();
String accessToken = gson.fromJson(oauthLoginResponse, SalesForceOauthObject.class).access_token;
return accessToken;
}
catch(Exception e){
e.printStackTrace();
}
return null;
Connect to your ICIX org using the Salesforce OAuth service. This will return your OAuth accessToken.
AddProducts: 1. Parameter CompanyICIXID removed. 2. Required Field RelationshipType added. 3. Required Field Status added. 4. Misc bug fixes 5. Additional validation
AddPurchaseOrders: 1. Command name changed to AddPurchaseOrders from API_PurchaseOrders.AddPurchaseOrders. 2. LineItem.Quantity changed to type String.
Sending a POST Request
URL url = new
URL("https://na30.salesforce.com/services/apexrest/dev_namespace/service_endpoint/");
con = (HttpsURLConnection) url.openConnection();
con.setDoOutput(true);
con.setDoInput(true);
con.setRequestProperty("Method", "POST");
con.setRequestProperty("Authorization", "Bearer " + accessToken);
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
OutputStream os = con.getOutputStream();
Wrapper wrapper = new Wrapper();
RequestSettings settings = new RequestSettings();
settings.Command = "Command.ExampleCommand";
Parameters params = new Parameters();
params.Id = "a0D36000004nmVWEAY";
Connect to your ICIX org using the Salesforce OAuth service. This will return your OAuth accessToken.
Please see JAVA example to the right.
General Information
Https requests to this API should conform to the following: URL: https:// [instance] .salesforce.com/services/apexrest/ [namespace] /pushdata/v3 Method: POST Authorization: Bearer [token] Content-Type: application/json Accept: application/json
Request Body
Example:
{
"settings": {
"Command": "NameOfCommand",
"ApiParameters": "{\"Id\":\"a0D36000004nmVWEAY\"}"
}
}
The request body must be a JSON object named settings with the following fields:
| Field Name | Type | Description |
|---|---|---|
| *Command | String | The name of the API Command you wish to execute. Available below. |
| *ApiParameters | String | A JSON serialized string that represents the required parameters of the API Command you have selected. Expected parameter objects are specified along with each API Command below. |
| Async | Boolean | If this flag is set to “true”, this request will be processed asynchronously. Use this feature to send a larger request body up to 1Mb. |
API Commands
AddProducts
{
"CompanyICIXID": "100" ,
"Products": [
{
"IcixProductName": "Product Name" ,
"Description": "Product Description" ,
"RelationshipType": "Buy" ,
"Status": "Active" ,
"TradingPartnerIdType": "Vendor" ,
"TradingPartnerId": "123" ,
"ProductIdTypesAndValues": {
"SKU": "456"
},
"Attributes": {
"Color": "Blue"
},
"Tags" : [
"Organic"
],
"RelatedProducts" : [
{
"IdType" : "SKU" ,
"ProductId" : "789" ,
"RelationshipType" : "Component" ,
"ExemptFromTesting" : "" ,
"Attributes" : {
"Bundle Count" : "6"
}
}
],
"ProductTestSettings": [{
"Program": "Test Program" ,
"Categories" : [
"Test Category A"
],
"TestLevels": [
"Finished Good"
]
}
]
}
]
}
Adds a list of products
API Parameters
| Field Name | Type | Description |
|---|---|---|
| Products | Object[] (Product[]) |
An array of objects containing the product information. The Product Object is described below. |
Product Object
| Field Name | Type | Description |
|---|---|---|
| *IcixProductName | String | The name of the product |
| Description | String | A description of the product |
| TradingPartnerIdType | String | The Id Type of the Trading Partner related to this product |
| TradingPartnerId | String | The Id of the Trading Partner related to this product. |
| *RelationshipType | String | The type of relationship between your company, the product, and the trading partner. Accepted values are Sell, Buy, Manufacture, Distribute, Verify. |
| *Status | String | The relationship status. Accepted values are Suspended, Active, Inactive, Pending. |
| *ProductIdTypesAndValues | Object | Your Id numbers or codes of the product. An Object with key value pairs where the values are strings. Keys should represent the type of identifier. Values should represent the identifier. See “ Supported ID types for Products ” below for valid types. The Ids are expected to be unique within your organization. |
| RelatedProducts | Object[] (RelatedProduct[]) |
An array of objects containing identifiers of products that are related to this product. The RelatedProduct object is described below. All products referenced must exist prior to this HTTP call. |
| Attributes | Object | Custom attributes for this product. An Object with key value pairs where the values are strings. Keys represent the attribute name. Values represent the attribute value. Attribute names used must be available in the “Attributes” tab of your org. |
| Tags | String[] | Custom Tags for this product. An Array of strings. Tag names used must be available in the “Attributes” tab or you org. |
| ProductTestSettings | Object[] (ProductTestSetting[]) |
A collection of objects that describes the Product Test Programs and Categories this product should be associated with. The ProductTestSetting object is described below. |
RelatedProduct Object
| Field Name | Type | Description |
|---|---|---|
| *IdType | String | Your Id type being referenced. Id Types used must be available in the “Id Types” tab of your org. Use an IdType that that represents a unique value in your organization. |
| *ProductId | String | The Id of the related product |
| *RelationshipType | String | Describes the relationship between this product and the related product. See “ Supported Relationship Types ” below for valid relationship types |
| ExemptFromTesting | Boolean | Specify if this product is exempt from testing of the related product |
| Attributes | Object | Custom attributes for this product relationship. An Object with key value pairs where the values are strings. Keys represent the attribute name. Values represent the attribute value. Attribute names used must be available in the “Attributes” tab of your org. |
Supported Relationship Types
- Component
- Related
- Variant
- Finished Product
ProductTestSetting Object
| Field Name | Type | Description |
|---|---|---|
| *Program | String | The name of the Product Test Program the product should be subscribed to. |
| Categories | String[] | An array of strings. These are the names of the test Categories in the specified Program that the product should be subscribed to. |
| TestLevels | String[] | An array of strings. These are the Program testing levels to apply to the product. |
AddPurchaseOrders
{
"CompanyICIXID": "100",
"PurchaseOrders": [
{
"PurchaseDate": "1/10/2018 12:00 AM",
"OrderNumber": "99",
"OrderStatus": "Closed",
"ShipToCountry": "US",
"TradingPartnerIdType": "Vendor",
"TradingPartnerId": "123",
"LineItems": [
{
"IdType": "SKU",
"ProductId": "1",
"Quantity": "10",
"Status": "Open"
},
{
"IdType": "SKU",
"ProductId": "2",
"Quantity": "100 ",
"Status": "Open"
}
]
}
]
}
Adds a list of purchase orders with line items into ICIX.
API Parameters
| Field Name | Type | Description |
|---|---|---|
| CompanyICIXID | String | The ICIX ID of your company. |
| PurchaseOrders | Object[] (PurchaseOrder[]) |
An array of objects that represents purchase orders. The PurchaseOrder object is described below. |
PurchaseOrder Object
| Field Name | Type | Description |
|---|---|---|
| PurchaseDate | String (Date/Time) |
The date and time of the purchase. The string should be formatted like: “ 11/06/2014 12:00 AM ” |
| DateRequested | String (Date/Time) |
The string should be formatted like: “ 11/06/2014 12:00 AM ” |
| AnticipateDate | String (Date/Time) |
The string should be formatted like: “ 11/06/2014 12:00 AM ” |
| CancelDate | String (Date/Time) |
The string should be formatted like: “ 11/06/2014 12:00 AM ” |
| OrderNumber | String | Your internal identifier for this purchase order. This is a unique identifier. |
| OrderStatus | String | The current status of the order. The supported values are: Open, Cancelled, Closed |
| ShipToCountry | String | Ship to Country for this purchase order. An Array of strings. See Supported Country Codes below for valid Country Names. |
| TradingPartnerIdType | String | The Id type used to reference the Trading Partner this order is related to. |
| TradingPartnerId | String | The Id used to reference the Trading Partner this order is related to. |
| LineItems | Object[] (LineItem[]) |
An array of objects that represents the line items belonging to this purchase order. The LineItem object is described below. |
LineItem Object
| Field Name | Type | Description |
|---|---|---|
| IdType | String | Your Id type being referenced for the product in the line item. |
| ProductId | String | The Id of the product being referenced by the line item. |
| Quantity | String | The quantity purchased of the product referenced by this line item. |
| Status | String | The current status of the order. The supported values are: Open, Cancelled, Closed |
Supported Country Codes
| Label__c / Country Name | Value__c / Country Code |
|---|---|
| Afghanistan | AF |
| Albania | AL |
| Algeria | DZ |
| Andorra | AD |
| Angola | AO |
| Antigua and Barbuda | AG |
| Argentina | AR |
| Armenia | AM |
| Australia | AU |
| Austria | AT |
| Azerbaijan | AZ |
| Bahamas, The | BS |
| Bahrain | BH |
| Bangladesh | BD |
| Barbados | BB |
| Belarus | BY |
| Belgium | BE |
| Belize | BZ |
| Benin | BJ |
| Bhutan | BT |
| Bolivia | BO |
| Bosnia and Herzegovina | BA |
| Botswana | BW |
| Brazil | BR |
| Brunei | BN |
| Bulgaria | BG |
| Burkina Faso | BF |
| Burundi | BI |
| Cambodia | KH |
| Cameroon | CM |
| Canada | CA |
| Cape Verde | CV |
| Central African Republic | CF |
| Chad | TD |
| Chile | CL |
| China, People's Republic of | CN |
| Colombia | CO |
| Comoros | KM |
| Congo, (Congo - Brazzaville) | CG |
| Congo, (Congo - Kinshasa) | CD |
| Costa Rica | CR |
| Cote d'Ivoire (Ivory Coast) | CI |
| Croatia | HR |
| Cuba | CU |
| Cyprus | CY |
| Czech Republic | CZ |
| Denmark | DK |
| Djibouti | DJ |
| Dominica | DM |
| Dominican Republic | DO |
| Ecuador | EC |
| Egypt | EG |
| El Salvador | SV |
| Equatorial Guinea | GQ |
| Eritrea | ER |
| Estonia | EE |
| Ethiopia | ET |
| Fiji | FJ |
| Finland | FI |
| France | FR |
| Gabon | GA |
| Gambia, The | GM |
| Georgia | GE |
| Germany | DE |
| Ghana | GH |
| Greece | GR |
| Grenada | GD |
| Guatemala | GT |
| Guinea | GN |
| Guinea-Bissau | GW |
| Guyana | GY |
| Haiti | HT |
| Honduras | HN |
| Hungary | HU |
| Iceland | IS |
| India | IN |
| Indonesia | ID |
| Iran | IR |
| Iraq | IQ |
| Ireland | IE |
| Israel | IL |
| Italy | IT |
| Jamaica | JM |
| Japan | JP |
| Jordan | JO |
| Kazakhstan | KZ |
| Kenya | KE |
| Kiribati | KI |
| Korea, North | KP |
| Korea, South | KR |
| Kuwait | KW |
| Kyrgyzstan | KG |
| Laos | LA |
| Latvia | LV |
| Lebanon | LB |
| Lesotho | LS |
| Liberia | LR |
| Libya | LY |
| Liechtenstein | LI |
| Lithuania | LT |
| Luxembourg | LU |
| Macedonia | MK |
| Madagascar | MG |
| Malawi | MW |
| Malaysia | MY |
| Maldives | MV |
| Mali | ML |
| Malta | MT |
| Marshall Islands | MH |
| Mauritania | MR |
| Mauritius | MU |
| Mexico | MX |
| Micronesia | FM |
| Moldova | MD |
| Monaco | MC |
| Mongolia | MN |
| Montenegro | ME |
| Morocco | MA |
| Mozambique | MZ |
| Myanmar (Burma) | MM |
| Namibia | NA |
| Nauru | NR |
| Nepal | NP |
| Netherlands | NL |
| New Zealand | NZ |
| Nicaragua | NI |
| Niger | NE |
| Nigeria | NG |
| Norway | NO |
| Oman | OM |
| Pakistan | PK |
| Palau | PW |
| Panama | PA |
| Papua New Guinea | PG |
| Paraguay | PY |
| Peru | PE |
| Philippines | PH |
| Poland | PL |
| Portugal | PT |
| Qatar | QA |
| Romania | RO |
| Russia | RU |
| Rwanda | RW |
| Saint Kitts and Nevis | KN |
| Saint Lucia | LC |
| Saint Vincent and the Grenadines | VC |
| Samoa | WS |
| San Marino | SM |
| Sao Tome and Principe | ST |
| Saudi Arabia | SA |
| Senegal | SN |
| Serbia | RS |
| Seychelles | SC |
| Sierra Leone | SL |
| Singapore | SG |
| Slovakia | SK |
| Slovenia | SI |
| Solomon Islands | SB |
| Somalia | SO |
| South Africa | ZA |
| Spain | ES |
| Sri Lanka | LK |
| Sudan | SD |
| Suriname | SR |
| Swaziland | SZ |
| Sweden | SE |
| Switzerland | CH |
| Syria | SY |
| Tajikistan | TJ |
| Tanzania | TZ |
| Thailand | TH |
| Timor-Leste (East Timor) | TL |
| Togo | TG |
| Tonga | TO |
| Trinidad and Tobago | TT |
| Tunisia | TN |
| Turkey | TR |
| Turkmenistan | TM |
| Tuvalu | TV |
| Uganda | UG |
| Ukraine | UA |
| United Arab Emirates | AE |
| United Kingdom | GB |
| United States | US |
| Uruguay | UY |
| Uzbekistan | UZ |
| Vanuatu | VU |
| Vatican City | VA |
| Venezuela | VE |
| Vietnam | VN |
| Yemen | YE |
| Zambia | ZM |
| Zimbabwe | ZW |
EditTradingPartners
API_TradingPartners.EditTradingPartners
Description: Add information to Trading Partner records in ICIX. Non-universal Ids, Tags, and Attributes can be added to Trading Partners. This process identifies a Trading partner by its name.
API Parameters
| Field Name | Type | Description |
|---|---|---|
| CompanyICIXID | String | The ICIX ID of your company. |
| TradingPartners | Object[] (TradingPartner[]) |
An array of objects that represents Trading Partner information. The TradingPartner object is described below. |
TradingPartner Object
| Field Name | Type | Description |
|---|---|---|
| Name | String | The name of the Trading Partner you are editing. The process identifies the records to be edited by this field. |
| IdTypesAndValues | Object | Your internal identifiers for this Trading Partner. These translate to Non-Universal Ids in ICIX. An Object with key value pairs where the values are strings. The keys represent the type of identifier. The values represent the identifier. |
| Tags | String[] | Custom Tags for this trading partner. An Array of strings. Tag names used must be available in the “Attributes” tab or you org. |
| Attributes | Object | Custom attributes for this trading partner. An Object with key value pairs where the values are strings. Keys represent the attribute name. Values represent the attribute value. Attribute names used must be available in the “Attributes” tab of your org. |
Errors
AddProduct Errors + Resolutions
| Error Message | Resolution |
|---|---|
| No products were supplied | The array “Products” is either null or empty in your json payload. |
| "IcixProductName" is missing | The required field IcixProductName is either blank, whitespace, or null. |
| Product Name [PRODUCT NAME] is exceeding the character limit of 80 characters | Limit product names to 80 characters in length. |
| Value missing for key [KEY] in ProductIdTypesAndValues | A key/value pair in the ProductIdTypesAndValues object has a null or blank key. The key represents the Id Type of the product. |
| An Identifier is required for field "ProductIdTypesAndValues" | The ProductIdTypesAndValues object is null or empty. At least one key/value pair is required. |
| Product not updated/added. The Product.Status :[STATUS]: is not valid | Product.Status is a picklist value. You must choose a valid value that is described in the object above. |
| Product not updated/added. The field Product.Status is required | Product.Status is null, blank, or empty. The field is required and must be a valid value that is described in the object above. |
| Product not updated/added. The Product.RelationshipType : [RELATIONSHIP TYPE] : is not valid | Product.RelationshipType is a picklist value. You must choose a valid value that is described in the object above. |
| Product not updated/added. The field Product.RelationshipType is required | Product.RelationshipType is null, blank, or empty. The field is required and must be a valid value that is described in the object above. |
| The field RelatedProduct.IdType is required | include an Internal Identifier. This field is the Id type of the identifier. |
| The field RelatedProduct.ProductId is required | To reference a related product you must include an Internal Identifier. This field is the Id vaue of the identifier. |
| The field RelatedProduct.RelationshipType is required | RelatedProduct.RelationshipType is null, blank, or empty. |
| There is no Internal Account assigned to this org | Please contact ICIX support to resolve this issue. |
| The ID Type [ID TYPE] is not supported | You have attempted to use an identifier with a type that does not exist in the org. Valid types are available to view in the Id Types tab. |
| The referenced Trading Partner "[ID TYPE]:[ID]" does not exist | The identifier supplied to reference a trading partner does not exist. This refers to internal Ids associated to trading partners. |
| The referenced Product "[ID TYPE]:[ID]" does not exist | This occurs when attempting to add a related product and no product with the supplied product identifier does not exist. |
| The referenced related product type [RELATIONSHIP TYPE] does not exist | RelatedProduct.RelationshipType is a picklist value. You must choose a valid value that is described in the object above. |
| The referenced Test Level: [TEST LEVEL] : does not exist. | ProductTestSetting.TestingLevels is an array of picklist values. You must choose valid values that are described in the object above. |
| The Tag "[TAG]" is not supported" | You have attempted to use a product tag that does not exist in the org. Valid tags are available to view in the Tags tab. |
| The referenced Attribute Type :[ATTRIBUTE]': is not supported | You have attempted to use a product attribute that does not exist in the org. Valid attribute are available to view in the Attribute tab. |
AddPurchaseOrder Errors + Resolutions
| Error Message | Resolution |
|---|---|
| CompanyICIXID is required | The required parameter CompanyICIXID. |
| The CompanyICIXID [ID] does not exist. | The CompanyICIXID that was supplied does not exist in the org. |
| The referenced VendorIdentifier [ID TYPE]:[ID] does not exist | The trading partner identifier provided does not exist in the org. This refers to the internal identifiers for trading partners. |
| No purchase orders were supplied | The PurchaseOrders object is null or empty. |
| Purchase Order not updated/added. The PurchaseOrder.OrderStatus :[ORDER STATUS]: is not valid | PurchaseOrder.OrderStatus is a picklist value. You must choose a valid value that is described in the object above. |
| Line Item not updated/added. The LineItem.Quantity :[QUANTITY]: exceeds the maximum length of 10 | LineItem.Quantity must be an Integer no more than 10 characters in length, in String format |
| Line Item not updated/added. The LineItem.Quantity is required | LineItem.Quantity is either null, blank, or empty. LineItem.Quantity must be an Integer no more than 10 characters in length, in String format |
| Line Item not updated/added. The LineItem.Quantity [QUANTITY] is not valid. | LineItem.Quantity provided is not correctly formatted. LineItem.Quantity must be an Integer no more than 10 characters in length, in String format. |
| Line Item not updated/added. The LineItem.Status :[STATUS]: is not valid | LineItem.Status is a picklist value. You must choose a valid value that is described in the object above. |
| The referenced Product [ID TYPE]:[ID] does not exist | This occurs when attempting to add a line item and no product with the supplied product identifier does not exist. |