npm package: @quotepro/aq3
Description: Quotepro Retail Website Api (aq3 integration)
Latest version: 1.0.54

# Quotepro Retail Website

The Retail Website API enables third party vendors and customers to have quick and straightforward integration with the Quotepro Retail website. This api provides a JSON formatted view of each page on the website and the ability to post/retrieve JSON data for any given page. Using this package makes it possible for customers to provide custom interfaces to their users while maintaining the core functionality of the quotepro website.

##Dependencies
Angular 6+

##Installation

- Run `npm i @quotepro/aq3 --save`

##Basic Usage

```
import { JsonApiService } from '@quotepro/aq3';

 constructor(
    private api: JsonApiService,
  ) {}

api.init(...);
api.getJson(...);
api.postJson(...);
```

##Included Functions

> Question marks denote optional arguments.

| Function Name         | Description                                                                                                                                                        | Arguments                        |
| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------- |
| **init**              | This function performs the initial setup for use of the json API. It sets in place all the variables needed by the other functions such as baseURL, language, etc. | baseUrl, language?, sid?, affid? |
| **isExpired**         | Checks if the session is expired                                                                                                                                   |                                  |
| **resetTimer**        | Resets the timer on the session timeout and sets it to the specified number of minutes                                                                             | timeoutMinutes                   |
| **initializeSession** | Creates a new session.                                                                                                                                             | sid? timeoutMinutes?, affid?     |
| **getJson**           | Retrieves json information for a specified view/controller and function/action                                                                                     | controller, action?, data?       |
| **postJson**          | Posts json information to a specified view/controller and function/action                                                                                          | controller, action?, data?       |
| **toUrl**             | Generates a url based on the controller and action passed into it.                                                                                                 | controller, action?              |
| **newGuid**           | Generates a new GUID                                                                                                                                               |                                  |  |

It is worth noting that init(), initializeSession(), getJson(), and postJson() will be your bread and butter and the majority of what you use while implementing this API.

### Function Arguments

| Argument Name  | Description                                                                                                                                                                                                                                                                                                             | Type   |
| :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |
| baseUrl        | The url used for all api actions, often denotes what agency is being hit.                                                                                                                                                                                                                                               | string |
| language       | Denotes what language the responses should be in. Accepts "en" or "es"                                                                                                                                                                                                                                                  | string |
| sid            | This is the unique session id used for the duration of the desired interaction. This should be unique per visitor but may be reused for returning visits if the visitor wants to resume their quote. This is a 36 character GUID. It must be a valid GUID and cannot simply be an arbitrary unique 36 character string. | string |
| affid          | Affiliate ID                                                                                                                                                                                                                                                                                                            | number |
| timeoutMinutes | Number of minutes until session times out.                                                                                                                                                                                                                                                                              | number |
| controller     | Denotes which view you would like to post or retrieve data from. For example the vehicles page or the applicant page.                                                                                                                                                                                                   | string |
| action         | Denotes what action you want to post or retrieve from on the selected controller                                                                                                                                                                                                                                        | string |
| data           | An object containing the information you would like to post to the service or relevant information for retrieving from the service. This object often contains the form data that is being posted for each page.                                                                                                        | object |

---

##Json Api Responses
Each response from the JSON api may contain the following elements.

| Variable Name  | Description                                                                                                                                                                                                                                                                                                             |
| :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **sid**        | This is the unique session id used for the duration of the desired interaction. This should be unique per visitor but may be reused for returning visits if the visitor wants to resume their quote. This is a 36 character GUID. It must be a valid GUID and cannot simply be an arbitrary unique 36 character string. |
| **errors**     | An array of errors displayed on the page.                                                                                                                                                                                                                                                                               |
| **nextUrl**    | this is a redirect mechanism for the api. It indicates that the current page has been completed successfully. The api is expecting a subsequent GET statement for the new url.                                                                                                                                          |
| **currentUrl** | This is the current url. Some http clients will follow 3xx redirects automatically. This property can be used to determine if an automatic redirect has occurred. This also typically indicates where to send the subsequent JSON post.                                                                                 |
| **form**       | The form object indicates the data which needs to be filled in for the page. This may also contain child objects.                                                                                                                                                                                                       |
| **fields**     | The fields object provides guidance for displaying the form elements. For example, radio buttons and select fields would include a list of available options.                                                                                                                                                           |
| **viewdata**   | This contains supplemental information which can be used on the page. For example, the Location page returns a list of cities and counties for the given zip code.                                                                                                                                                      |

- You may also see "\$id" elements. These are a reference counting mechanism of the JSON.Net library and should be ignored. This should not be confused with "Id" elements which are necessary to ensure the referential integrity of the data session. Id" elements, when present, should be returned on subsequent POSTs unmodified.
- In order to preserve the user's session the sid must always be included in the query string. Any request body passed on a GET request will be ignored.
- Your integration should be designed to handle new fields that are added to our JSON api and to default any missing fields which may be omitted where the fields is either empty or null.
- Date fields will be transmitted either as "mm/dd/yyyy" or as "/Date(ticks)/" per Microsoft's convention for JSON date transmission.

---

##Use Examples

A few examples will be provided below, more examples can be seen in the full documentation found [here.](https://drive.google.com/file/d/1oJHA3w9IHHL6C_O1JvRmOD4vytVSddVU/view?usp=sharing 'here.')

### Setup/Initialization

###### Request

```
import { JsonApiService } from '@quotepro/aq3';

 constructor(
    private api: JsonApiService,
  ) {}

api.initializeSession();
```

### Using Post Json to Post Information From The Applicant Page

###### Request

```
import { JsonApiService } from '@quotepro/aq3';

 constructor(
    private api: JsonApiService,
  ) {}

api.postJson("Location", "Index", {
	address: "820 N Orleans",
	city: "Chicago",
	county: "Cook",
	email: "test@gmail.com",
	firstName: "John",
	howHeard: "",
	id: 6631,
	lastName: "Doe",
	phone: "(444) 444-4444",
	disableValidation: false,
	quote: {
		agreeNonOwner: false,
		currentlyInsured: false,
		nonOwner: false,
		noPrior: "6",
		paperLessDisc: false,
		yearsInsured: 1
	}
	state:"IL"
	zipCode:"60610"
}).subscribe(response => console.log(response));
```

###### Response

```
{
	$id: "1"
	nextUrl: "https://localhost/DemoAgent/en/Vehicle"
	sid: "c0df66f6-2115-4453-8c09-da2731a62e90"
}
```

> This is what the response of a successful post looks like. If the response looks different then this or returns with html then there was an issue with the post.

### Using Get Json To Create a Vehicle Retrieve Fields For The Vehicles Page

###### Request

```
import { JsonApiService } from '@quotepro/aq3';

 constructor(
    private api: JsonApiService,
  ) {}

api.getJson("Vehicle", "Create", { id: 0 }).subscribe(response => console.log(response));
```

###### Response

> Please note that this response has been truncated for readability and is merely meant to serve as an example of what would come back from a successful request.

```
{
currentUrl: "/DemoAgent/en/Vehicle/Create?json=1&blogs=1&id=0&sid=c0df66f6-2115-4453-8c09-da2731a62e90"
form: {
	actualValue:null
	addAnotherVehicle:false
	annualMiles:10000
	costNew:null
	dailyMiles:20
	engine:null
	fullLookup:false
	id:0
	imsControl:null
	isLastVehicle:true
	isoVinNumber:null
	lengthOwned:30
	lhaddress1:null
	lhaddress2:null
}
fields: {
	actualValue: {control: "input", type: "hidden", label: "Actual Value", ...}
	addAnotherVehicle: {control: "input", type: "hidden", label: "Would you like to add 		another vehicle?", ...}
	annualMiles: {control: "input", type: "number", label: "Annual Miles", ...}
	costNew: {control: "input", type: "hidden", label: "Cost of Vehicle New?", ...}
	dailyMiles: {control: "input", type: "number", label: "Daily Miles", ...}
	engine: {control: "select", label: "Engine", options: Array(0), ...}
	fullLookup: {control: "input", type: "hidden", label: "Full Lookup", ...}
	id: {control: "input", type: "hidden", label: "Id", ...}
	imsControl: {control: "input", type: "hidden", label: "Ims Control", ...}
	isLastVehicle: {control: "input", type: "hidden", label: "Is Last Vehicle", ...}
	isoVinNumber: {control: "input", type: "hidden", label: "Iso Vin Number", ...}
	lengthOwned: {control: "select", label: "Length Owned", options: Array(7), ...}
	lhaddress1: {control: "input", type: "text", label: "Lien Holder Street", ...}
	lhaddress2: {control: "input", type: "text", label: "Lien Holder Street", ...}
	lhname: {control: "input", type: "text", label: "Lien Holder Name", ...}
	lhstate: {control: "input", type: "text", label: "Lien Holder State", ...}
	lhzipcode: {control: "input", type: "text", label: "Lien Holder Zip", ...}
	lienHolder: {control: "input", type: "radio", label: "Enter Lien Holder", ...}
	make: {control: "select", label: "Make", options: Array(0), ...}
	...
}
sid:"c0df66f6-2115-4453-8c09-da2731a62e90"
viewdata: {}
}
```