SalesPad GP

Web API Example Usage (with Postman)

_________________________________________________________________________________________________

Table of Contents

Notes ....................................................................................................................................................................................... 1
Postman Rest Client ............................................................................................................................................................... 1
Creating a Session / Logging In............................................................................................................................................ 2
Retrieve a Customer ............................................................................................................................................................... 4
Create a Customer .................................................................................................................................................................. 5
Create a Sales Document ....................................................................................................................................................... 8
Create a Sales Line Item ....................................................................................................................................................... 10
Updating a Sales Document ................................................................................................................................................. 11
Forwarding a Sales Document .............................................................................................................................................. 13
Deleting a Sales Document................................................................................................................................................... 14
Deleting a Session / Logging Out ....................................................................................................................................... 15

_________________________________________________________________________________________________

Notes

For purposes of this demonstration, the SalesPad WebAPI is installed locally on port 5501. This means that all
example requests shown will start with http://localhost:5501. If following along with this documentation,
replace this with the server name and port number for your particular installation.
References to the API Help Page are referring the help page which can be found at your installation location
/Help (in our case, http://localhost:5510/Help).
SalesPad WebAPI supports JavaScript Object Notation (JSON). For more information on JSON, check out
http://www.json.org/

Postman Rest Client

SalesPad developers have found a tool named Postman to be indispensable in testing and developing the SalesPad
WebAPI. Postman is a Chrome App, but can be run as a desktop application as well. You can download the Chrome
App here, or the Packaged App here.

You may use any tools / code of your choice to send requests to the SalesPad WebAPI, but for the purposes of this
demonstration we will be using Postman.

_________________________________________________________________________________________________
www.salespad.net (616) 245-1221 SalesPad WebAPI Example Usage Updated February 2015 | Page 1
Creating a Session / Logging In

NOTE: You must create a session before attempting to request anything from the API. If you do not send a valid Session-
ID with subsequent requests, your requests will be denied. (It is also assumed that you will use a user account that has
admin (or all) permissions for all request types.)

To create a session, you must send a request to GET api/Session. This request must contain an Authorization header
for Basic Authentication (as specified on the API help page): Username and password should be in the format
of username:password, using the colon as separator, prefixed with the keyword Basic and encoded in Base64.

In Postman, this is a simple process, as a Basic Auth tab is provided which will prompt you for Username and Password,
and do the rest for you. Enter your user information, then click Refresh headers. This will create an Authorization
header with the appropriate value:

Next, enter your server name, port, and api/session (in our case, http://localhost:5501/api/session), make sure the
Http Request Method is GET, and click Send:

_________________________________________________________________________________________________
www.salespad.net (616) 245-1221 SalesPad WebAPI Example Usage Updated February 2015 | Page 2
The response should pop up below, and look something like this (If it doesnt look as nice, make sure the Pretty tab is
selected):

The response will contain information about the user, such as the SecurityGroup it belongs to, Object and Property
Permissions, Group Permissions, and any User-Customer associations. However, in our case, all we really care about is
the SessionID value given, as this is our ticket to make further requests. This value must be used with a Session-ID
header for all following requests:

_________________________________________________________________________________________________
www.salespad.net (616) 245-1221 SalesPad WebAPI Example Usage Updated February 2015 | Page 3
Retrieve a Customer

To retrieve Customer information, we can send a GET request to api/Customer endpoint. The API Help Page shows us
that there are two kinds of GET requests we can make one using OData, and one using the Primary Keys of the Object
(in this case, the Customer_Num):

For our example, we will retrieve Customer Aaron Fitz Electrical, from the Sample Company setup provided by
Dynamics GP.

We can do this using either endpoint:

GET api/Customer/AARONFIT0001
OR
GET api/customer?$filter=Customer_Num eq 'AARONFIT0001'
For the OData enabled endpoint, we simply filter to customers where the Customer_Num is AARONFIT0001, and we end
up with the same results. (See the API GettingStarted page for more information on OData).

For this request, you can use the Normal tab in Postman, as we dont need the Basic Authentication anymore. Begin by
copying the SessionID value provided by the GET api/Session request, and paste it as the value for a Session-ID
header (as shown previously). Then enter the URL you wish to use:

_________________________________________________________________________________________________
www.salespad.net (616) 245-1221 SalesPad WebAPI Example Usage Updated February 2015 | Page 4
Again, make sure the Http Request Method is GET, and click Send. A successful response should look like the following:

All other GET requests should be made in a similar manner, using the SessionID created by the initial GET api/Session
request. See the API Help Page for all available endpoints.

Create a Customer

To create a new Customer, we will use the POST Http Request Method. When you change this in Postman, an additional
area for sending content with the request will pop up. We want to use the raw type, and it looks best when formatted as
JSON.
(When you select JSON, you may notice that Postman will add an additional Content-Type header of application/json.
Feel free to delete it or leave it as you see fit. This is normally what would describe the request body type, but since
SalesPad WebAPI only supports JSON, it is not necessary (but also does not hurt anything).)

_________________________________________________________________________________________________
www.salespad.net (616) 245-1221 SalesPad WebAPI Example Usage Updated February 2015 | Page 5
NOTE: Generally, a SalesPad Object can be created with as little as the Primary Key(s). However, we encourage you to
provide as much information as possible for better accuracy and fewer errors.
For example, we can create a Customer by only giving the Customer Number we wish to use:

{
"Customer_Num": "TestCustomer",
}

_________________________________________________________________________________________________
www.salespad.net (616) 245-1221 SalesPad WebAPI Example Usage Updated February 2015 | Page 6
However, you will notice that this Customer will not have any properties filled out (except for a few defaults). So you will
not likely be able to do anything useful with this Customer until you have updated it with more information.

NOTE: For Customers, SalesDocuments, and SalesLineItems, auto-numbering can be accomplished by NOT providing
the Primary Key you wish to be created for you. For example, we can POST a customer with just a name, and we will see
that the Primary Key (Customer_Num) property is automatically generated:

{
"Customer_Name": "Testing Customer Number Generation",
}

A successful response should look similar to the following:

_________________________________________________________________________________________________
www.salespad.net (616) 245-1221 SalesPad WebAPI Example Usage Updated February 2015 | Page 7
See the API Help Page for JSON samples which include all available properties for POSTing each Object type:

Create a Sales Document

Creating a Sales Document is similar to creating a Customer. The minimum required properties are Sales_Doc_ID,
Sales_Doc_Type, and Customer_Num. (You may provide your own Sales_Doc_Num, or else it will be automatically
generated for you.)

{
"Sales_Doc_ID": "STDORD",
"Sales_Doc_Type": "ORDER",
"Customer_Num": "AARONFIT0001",
}

_________________________________________________________________________________________________
www.salespad.net (616) 245-1221 SalesPad WebAPI Example Usage Updated February 2015 | Page 8
Make sure that the Http Request Method is set to POST:

As you can see, since we have not supplied a Sales_Doc_Num value, the response shows that the Sales Document
Number has been automatically generated for us:

_________________________________________________________________________________________________
www.salespad.net (616) 245-1221 SalesPad WebAPI Example Usage Updated February 2015 | Page 9
Create a Sales Line Item

You can create Sales Line Items in multiple ways:

You can add them to the LineItems property in Sales Document when POSTing the document (each Line Item
Object in the LineItems array should at least contain the minimum required properties listed in the following
point):

{
. . .
"LineItems": [
{
. . .
},
{
. . .
}
],
. . .
}

Or you can use the SalesLineItem endpoints to create Sales Line Items one at a time. Minimum required
properties are Sales_Doc_Type, Sales_Doc_Num, and Item_Number. Line_Num and Component_Seq_Num can be
provided, otherwise they will be automatically generated:

{
"Sales_Doc_Type": "ORDER",
"Sales_Doc_Num": "ORDST2242",
"Item_Number": "A100",
}

_________________________________________________________________________________________________
www.salespad.net (616) 245-1221 SalesPad WebAPI Example Usage Updated February 2015 | Page 10
The document and line items will be automatically updated with price, etc.

Updating a Sales Document

Updating Sales Document (or any other Object) properties is straight-forward. Simply look up the Object you wish to
update, and send a PUT request to the specified URL with the properties you wish to update and their new values.

For example, to update a Sales Document, we can look up the PUT request URL format in the API Help Page:

_________________________________________________________________________________________________
www.salespad.net (616) 245-1221 SalesPad WebAPI Example Usage Updated February 2015 | Page 11
We can see that we have to send the Sales_Doc_Type and Sales_Doc_Num Primary Keys so that the API knows which
object to update. In Postman, change the Http Request Method to PUT, fill in the URL, and supply the properties you wish
to update. In our example, we will update the Customer_PO_Num:

{
"Customer_PO_Num": "New PO 1234",
}

In the response, you can see that the Customer_PO_Num has been updated:

_________________________________________________________________________________________________
www.salespad.net (616) 245-1221 SalesPad WebAPI Example Usage Updated February 2015 | Page 12
Forwarding a Sales Document

Provided that you have workflow set up in SalesPad, it is easy to forward documents, as shown in the API Help Page:

In Postman, make sure the Http Request Method is set to PUT, and fill in the URL with the document you wish to forward
(Note that no body is required in this request):

If successful, you will see a response similar to the following:

_________________________________________________________________________________________________
www.salespad.net (616) 245-1221 SalesPad WebAPI Example Usage Updated February 2015 | Page 13
If the document is already in the last queue, you will likely get a message similar to the following:

Deleting a Sales Document

Deleting a Sales Document (or any other Object) is also straight-forward. Simply use the API Help Page to look up the
Object you wish to delete, and send a DELETE request to the specified URL.

In Postman, flip the Http Request Method to DELETE, and fill in the URL with the Object you wish to delete (Note that no
body is required in this request):

_________________________________________________________________________________________________
www.salespad.net (616) 245-1221 SalesPad WebAPI Example Usage Updated February 2015 | Page 14
If successful, the response message should look like the following:

Deleting a Session / Logging Out

It is a good idea to delete your session when finished making requests. SalesPad WebAPI will automatically delete
sessions older than 15 minutes, but during that time period you will still be logged in, and consuming a seat of SalesPad.
Deleting your session will also delete any document locks you may have acquired during your session.

To delete your session, simply make a request to DELETE api/Session, with the Session-ID header as usual (again, no
body is required):

_________________________________________________________________________________________________
www.salespad.net (616) 245-1221 SalesPad WebAPI Example Usage Updated February 2015 | Page 15
If successful, you should get a response similar to the following:

_________________________________________________________________________________________________
www.salespad.net (616) 245-1221 SalesPad WebAPI Example Usage Updated February 2015 | Page 16