SUMMARY OF AVAILABLE PORTAL SERVICES

Back

 

Contents

 

1. Purpose of this Document
2. Common Requirements for all Portal Services
     2.1 Sample Service Call Code (C#)
3. Summary of Available Portal Services
     3.1 Product Info
Description
Required items for usage
Functions
Class Diagrams
Service WDSL
     3.2 Purchase Orders
Description
Required items for usage
WCF Service Functions
WCF Service WDSL
REST Api Services
Class Diagrams
     3.3 Invoices
Description
Required items for usage
REST Api Services
Class Diagrams

1. Purpose of this Document

This Document is intended to assist a Client to make use of the Parrot Portal Web Services by providing Service Method definitions and sample calling code. This will also help Developers see how it can be used externally and which parameters are required.

2. Common Requirements for all Portal Services

Please note that in order to authenticate to the Parrot Portal, you will require a Username and Password on our Active Directory.

This information will be sent to you and is required for all Portal Service calls, in addition to any specific requirements for each Service listed in this Document.

In most cases, you (as a Client) will use the Basic authentication option when using the Parrot Portal and provide your Active Directory Username and Password as Credentials for connecting to all available Portal Web Services.

2.1 Sample Service Call Code (C#)

Shown below is some quick sample code, demonstrating how to connect using Basic HTTPS Authentication to the Product Info Web Service.

 

Please note that if either of these Credentials are wrong, the service will fail with Invalid Authentication: Username or password is incorrect.

 

3. Summary of Available Portal Services

3.1 Product Info

Description

The product info service allows you to fetch the latest information about Parrot’s Products. This includes the following:

  • Pricing information
  • Product’s Parrot Stock Code and Description
  • The product’s Barcode and any associated Kit Items for the product
  • Any alternative products for the product
  • Recommended Retail Price (RRP)
  • Product Document and Image Links (to Parrot’s Public Web Services)
  • Any current Promotion Info for the Product
  • Can optionally show current Warehouse Stock Levels per Product
  • The product's Publishing Category (this is usually used for eCommerce)

Required items for usage

  • Parrot Internal Customer Code
  • Parrot generated Portal Product Info Password for the specific internal Customer Code

This section will describe the functions that are callable from the Portal Product Info service.

 

* This should be your preferred function for querying for Product Pricing.

This method parameters are shown and described below:

 GetProductInfoForCustomerForMultipleProductsUsingDefaults(IList StockCodes, string CustomerCode, string Password, bool GetSuspendedProducts)
  1. StockCodes: This is an array or List<string> of the StockCodes whose information you wish to retrieve.
  2. CustomerCode: Your unique Customer Code on our system, please make sure to always use this code when sending a request or it will fail.
  3. Password: Your Portal Password provided by Parrot, used to determine if access is allowed through our Portal.
  4. GetSuspendedProducts: Flags if you wish to retrieve active products or suspended products.

GetProductInfoForCustomerForMultipleProducts

 GetProductInfoForCustomerForMultipleProducts(IList StockCodes, string CustomerCode, DateTime? PricingDate, int ChannelID, int PromoMinQuantity, string Password)
  1. StockCodes: This is an array or List of the Stock Codes whose information you wish to retrieve
  2. CustomerCode: Your unique Customer Code on our system, please make sure to always use this code when sending a request or it will fail.
  3. PricingDate: The date the pricing should be for. If you pass in a null value, it will default to getting pricing for today’s date. This is used to determine Pricelist/Promotion pricing.
  4. ChannelID: Leave as 0 for now. Is used by our system to determine if a channel discount applies.
  5. PromoMinQuantity: Is used to determine eligibility for a promotion. Leave as 1 .
  6. Password: Your Portal Password provided by Parrot, used to determine if access is allowed through our Portal.
  7. GetSuspendedProducts: Flags if you wish to retrieve active products or suspended products.

GetProductInfoForCustomerForMultipleProductsUsingDefaultsWithWarehouseStock

 GetProductInfoForCustomerForMultipleProductsUsingDefaultsWithWarehouseStock(IList StockCodes, string CustomerCode, string Password, bool GetSuspendedProducts, IList WarehouseCodes)
  1. StockCodes: This is an array or List of the Stock Codes whose information you wish to retrieve
  2. CustomerCode: Your unique Customer Code on our system, please make sure to always use this code when sending a request or it will fail.
  3. Password: Your Portal Password provided by Parrot, used to determine if access is allowed through our Portal.
  4. GetSuspendedProducts: Flags if you wish to retrieve active products or suspended products.
  5. WarehouseCodes: This is an array or List of Warehouse Codes you wish to receive Stock Information from. Leave as null to fetch ALL available Portal Warehouse Stock levels.

GetWarehouseInfo

This function returns all Warehouses that are available through the Portal, in a List of Results with the Warehouse Codes and their Descriptions. (This function requires no parameters)

GetWarehouseInfo()

IsConnectionUp

This function checks if the Parrot Portal is currently available for access. It simply returns a Boolean indicating if the portal is available for processing requests or not.

IsConnectionUp()

Class Diagrams


Result Object (returned from most methods on this Service)


Product Information Object (with associated objects)

Service WDSL

https://accounts.parrotproducts.biz/Portal/ProductInfo.svc?singleWsdl

3.2 Purchase Orders

Description

This Portal service allows you to place Orders for Products directly to the Parrot System itself. This can be done in several ways, including: 

  • Using the Parrot PurchaseOrder class object
  • Using an xml file from either a File Path or using a FileStream

Required items for usage

  • Parrot External Customer Code
  • Parrot Group Number
  • Parrot ERP User Name and Password

WCF Service Functions

 

This section will describe the functions that are callable from the Portal Purchase Orders service.

AddNew

 

 AddNew(CommonDataDefinitions.Portal.PurchaseOrder NewPurchaseOrder)
  1. NewPurchaseOrder: The Purchase Order class containing all the details for the new Order. (Please refer to the class diagram to see the properties this class has)

AddNewForGroup

 AddNewForGroup(CommonDataDefinitions.Portal.PurchaseOrder NewPurchaseOrder, int TheGroupNumber)
  1. NewPurchaseOrder: Class containing all the details for the new Order
  2. TheGroupNumber: GroupNumber to use alongside the external customer code.

AddNewForGroupOverWritePrice

 AddNewForGroupOverWritePrice(CommonDataDefinitions.Portal.PurchaseOrder NewPurchaseOrder, int TheGroupNumber, bool OverWritePricing)
  1. NewPurchaseOrder: Class containing all the details for the new Order.
  2. TheGroupNumber: Group Number to use alongside the external customer code.
  3. OverWritePricing: Flags if overwrite pricing must be used or not.

AddNewFromFilePath

 AddNewFromFilePath(string TheXmlFilePath);
  1. TheXmlFilePath: Represents the system path to the Xml file which has the details for the Order.

AddNewFromFileStream

 AddNewFromFileStream(Stream TheXmlFileStream)
  1. TheXmlFileStream: Represents a file stream object containing the xml file’s information for creating the new Order.

AddNewForGroupDefaultToDeliveryNote

 AddNewForGroupDefaultToDeliveryNote(PurchaseOrder NewPurchaseOrder, int GroupNumber, bool DefaultToDeliveryNote)
  1. NewPurchaseOrder: Class containing all the details for the new Order.
  2. TheGroupNumber: Group Number to use alongside the external customer code
  3. DefaultToDeliveryNote: Flags that the Portal Order should be e-mailed as and placed with the Delivery Document as a Delivery Note rather than a Tax invoice.

IsConnectionUp

IsConnectionUp()

This function checks if the Purchase Orders service is currently available for access. It simply returns a Boolean indicating if the portal is available for processing requests or not.


WCF Service WDSL

https://accounts.parrotproducts.biz/Portal/PurchaseOrders.svc?singleWsdl


REST Api Service


The Parrot Portal now supports a REST Web Api alongside the WCF Service Functions. This section will showcase how to send a Request and what Response to expect via JSON for all available Api methods (currently only 2).


Add New Purchase Order Web Api


https://accounts.parrotproducts.biz/Portal/api/PurchaseOrders/AddNew


This api method is used to add a new Purchase Order.


Example Request


The full request JSON object below is included in the Body of the HttpRequest as a POST.
Please note that you will be required to include Basic Authentication (NTLM) Headers of a Username and Password we provide you with. This may not be the same as the Parrot UserName and Password included in our request object!


Please note that as of our latest Api release, you may replace the GroupNumber and CustomerExternalCode with a single IntegrationToken. This would be sent to you with your other information as normal. We will only provide Integration Tokens going forward and newer Api services such as Transport Charge Calculations will use it exclusively. Examples of BOTH Requests are shown below:


Fields that will needed to be changed dynamically are tagged with a *
Fields that require us to provide you with appropriate information are tagged with a #


Original Object with no Integration Token (Group Number and Customer External Code required).


{
"UseCompanyDefaultForCurrencyAndDivision": true,
"GroupNumber": 0, #
"DeliveryAddressType": 0,
"DeliveryAddress": null,
"OrderGuid": "" *,
"OrderNumber": "" * ,
"CustomerExternalCode": "" *,
"OrderLines": [
{
"LineNumber": 1,
"StockCode": "BD9131",*
"Quantity": 1,*
"AmountExcl": 0.00,
"UnitAmountExcl": 0.00,
"ExistsAsKitChild": false
},
{
"LineNumber": 2,
"StockCode": "BD9132"*,
"Quantity": 1*,
"AmountExcl": 0.00,*
"UnitAmountExcl": 0.00,*
"ExistsAsKitChild": false
}
],
"AmountExcl": 0.00,
"UserName": "YourProvidedUserNameHere",#
"UserPassword": "YourProvidedPasswordHere",#
"PayMentType": 5,
"MustValidateAmount": true,
"AmountTolerancePercentage": 0.0,
"ErrorEmailAddy": "",
"DeliveryDate": "2020-02-22T08:25:37.7900561+02:00",*
"CheckDeliveryDateChange": true,*
"InternalCustomerCode": "",
"DivisionId": -1,
"Currencies_No": -1,
"ExchangeRate": 1.0
}

Object with Integration Token (Group Number and Customer External Code NOT required).


{
"UseCompanyDefaultForCurrencyAndDivision": true,
"IntegrationToken:":"YourTokenHere"#,
"DeliveryAddressType": 0,
"DeliveryAddress": null,
"OrderGuid": "" *,
"OrderNumber": "" * ,
"OrderLines": [
{
"LineNumber": 1,
"StockCode": "BD9131",*
"Quantity": 1,*
"AmountExcl": 0.00,
"UnitAmountExcl": 0.00,
"ExistsAsKitChild": false
},
{
"LineNumber": 2,
"StockCode": "BD9132"*,
"Quantity": 1*,
"AmountExcl": 0.00,*
"UnitAmountExcl": 0.00,*
"ExistsAsKitChild": false
}
],
"AmountExcl": 0.00,
"UserName": "YourProvidedUserNameHere",#
"UserPassword": "YourProvidedPasswordHere",#
"PayMentType": 5,
"MustValidateAmount": true,
"AmountTolerancePercentage": 0.0,
"ErrorEmailAddy": "",
"DeliveryDate": "2020-02-22T08:25:37.7900561+02:00",*
"CheckDeliveryDateChange": true,*
"InternalCustomerCode": "",
"DivisionId": -1,
"Currencies_No": -1,
"ExchangeRate": 1.0
}

Usually, the Customer External Code maps to your own requesting Branch Code and an Order Guid must be generated your side. The rest of the fields such as the Username and Password requires us to send you information. Your Line may vary with the amount of Products you’re requesting to be ordered. The Error Email Addy specifies if you wish a developer or some other person within the company to receive an email if the Order fails to process.


If you would like to include a Third Party Delivery Address, you must modify the DeliveryAddressType and Delivery Address properties to the below (the rest of the JSON object is omitted to keep the example short):



"DeliveryAddressType": "1",
"DeliveryAddress": {
"CompanyName" : "Parrot Products",
"AdditionalDeliveryInfo" : "Ask for Joe at Reception",
"StreetAddress" : "22 Cleveland Road",
"Suburb" : "Cleveland",
"City" : "Johannsberg",
"PostalCode" : "2094"
}

Expected Http Response Codes


A HTTP Status Code of 400 - Bad Request will be returned when any input data is invalid. A simple JSON Message about the issue will be returned, as shown below:


{
"message": "Header Problems:\r\n1. Address Validation failed and the following problems were found in the Third Party Delivery Address: 1) Please ensure a City name is provided.\r\n"
}

Please note that when the Order is successfully placed, a HTTP Status Code of 200 - Ok will be returned alongside a full object, which will contain a Document Number representing the Parrot Order Number.



Calculate Transport Api Method


This api call is used to an expected Transport Charge without actually placing an Order.


https://accounts.parrotproducts.biz/Portal/api/PurchaseOrders/CalculateTransport


Example Request


The full request JSON object below is included in the Body of the HttpRequest as a POST.
Please note that you will be required to include Basic Authentication (NTLM) Headers of a Username and Password we provide you with, as well as a special Integration Token. An example request is shown below:


{
"integrationToken": "YourTokenGoesHere",
"deliveryAddress": {
"additionalDeliveryInfo": null,
"companyName": "Parrot Products",
"city": "Johannesberg",
"suburb": "Cleveland",
"streetAddress": "22 Cleveland Road",
"postalcode": "2020"
},
"products": [
{
"stockCode": "BD9131",
"quantity": 1
},
{
"stockCode": "BD9131A",
"quantity": 1
}
]
}

Please note that the City and Street Address are requiried for processing, as well as at least 1 product.<.p>

An example error message is shown below (returning a HTTP Status Code of 400 - Bad Request:


{
"message": "The request is invalid.",
"modelState": {
"transportChargeRequest.IntegrationToken": [
"The IntegrationToken field is required."
]
}
}

An example success response, returning the HTTP Status Code of 200- Ok is shown below. Please note that in this scenario, no Transport Charge was expected, so all the values are shown as 0.


{
"problems": null,
"transportChargeExTax": 0.00,
"transportChargeTaxAmount": 0.00,
"transportChargeInclTax": 0.00
}

Class Diagrams

 

Processing Objects

 

 

 

Returned Objects


3.3 Invoices

Description

This Portal service allows you to place Invoices for Products directly to the Parrot System itself. This is done by providing an Invoice Object with valid credentials to the service.

Required items for usage

  • Parrot Customer Intergration Token
  • Parrot ERP User Name and Password

 

This section will describe the functions that are callable from the Portal Invoices service.

AddNew

 

 AddNew(CommonDataDefinitions.Portal.PortalInvoice invoice)
  1. invoice: The Invoice class containing all the details for the new Invoice. (Please refer to the class diagram to see the properties this class has)

REST Api Service

The Parrot Portal only supports a REST Web Api for Invoice functionality. This section will showcase how to send a Request and what Response to expect via JSON for all available Api methods.

Add New Invoice Web Api

https://accounts.parrotproducts.biz/Portal/api/Invoices/AddNew

This api method is used to add a new Invoice.

Example Request

The full request JSON object below is included in the Body of the HttpRequest as a POST. Please note that you will be required to include Basic Authentication (NTLM) Headers of a Username and Password we provide you with. This may not be the same as the Parrot UserName and Password included in our request object!

Fields that will needed to be changed dynamically are tagged with a * Fields that require us to provide you with appropriate information are tagged with a #

Please note by default, we would use the currency associated to each Company in the Parrot ERP System and Vat Rate to Calculate vat totals. You CAN augment the below to add additional currency factors and at request we will provide you the JSON Schematic for this but by default it is assumed the Default Currency and exchange rates are sufficient.

{ 
                "IntegrationToken:":"YourTokenHere"#, 
                "DeliveryAddressType": 0, 
                "DeliveryAddress": null, 
                "InvoiceGuid": ""*, 
                "InvoiceLines": [ 
                {
                    "LineNumber": 1, 
                    "StockCode": "BD9131"*, 
                    "Quantity": 1*, 
                    "LineTotalExcl": 0.00*, 
                    "UnitTotalExcl": 0.00*, 
                }, 
                { 
                    "LineNumber": 2, 
                    "StockCode": "BD9132"*, 
                    "Quantity": 1*, 
                    "LineTotalExcl": 0.00*, 
                    "UnitTotalExcl": 0.00*,
                 } 
                 ], 
                 "TotalExcl": 0.005, 
                 "UserName": "YourProvidedUserNameHere"#, 
                 "UserPassword": "YourProvidedPasswordHere"#, 
                 "PaymentType": 5*, 
                 "ErrorEmailAddress": ""*, 
                 "DeliveryDateUTC": "2019-07-04T13:33:03.969Z"*, 
                } 
            

Please note that the invoice Guid must be generated your side. The rest of the fields such as the Username and Password requires us to send you information. Delivery Date should be provided as UTC without the date shift appended as per ISO 8601. Your Line may vary with the amount of Products you’re requesting to be ordered. The Error Email Address specifies if you wish a developer or some other person within the company to receive an email if the Invoice fails to process.

If you would like to include a Third Party Delivery Address, you must modify the DeliveryAddressType and Delivery Address properties to the below (the rest of the JSON object is omitted to keep the example short):

        "DeliveryAddressType": "1",
        "DeliveryAddress": {
        "CompanyName" : "Parrot Products",
        "AdditionalDeliveryInfo" : "Ask for Joe at Reception",
        "StreetAddress" : "22 Cleveland Road",
        "Suburb" : "Cleveland",
        "City" : "Johannsberg",
        "PostalCode" : "2094"
        }
        

Expected Http Response Codes

A HTTP Status Code of 400 - Bad Request will be returned when any input data is invalid. A simple JSON Message about the issue will be returned, as shown below:

{
        "message": "Header Problems:\r\n1. Address Validation failed and the following problems were found in the Third Party Delivery Address: 1) Please ensure a City name is provided.\r\n"
        }
        

Please note that when the Invoice is successfully placed, a HTTP Status Code of 200 - Ok will be returned alongside a full object, which will contain a Document Number representing the Parrot Invoice Number.

Class Diagrams

 

Returned Objects