This document provides instructions and example code for DocketManager’s ImportQuoteRequest (IOR)API. DocketManager’s IOR allows external systems to send quotes to a DocketManager site. Using a post request DocketManager will parse the required XML and convert the provided information into the DocketManager MIS system.


Integrations Page

Field
Description
Authentication KeyThis key is required to send quotes and orders through the xml.

New Customer Defaults
(currently in beta)
This selection will be used when adding new customers and contacts.

Deposit Type
(currently in beta)
Payments created through the xml import will be placed in an open deposit of this type or will create a new one if no open deposits are found.

Payments can only be made on orders.

Match Stock
(currently in beta)
If set to yes, the stock name from the xml import will be used to find a match to an online name of a stock. If a match is found that stock will be selected on the item. If no match is found the stock name will be shown in a press note.

If set to no, the stock name from the xml import will be shown in a press note.


PostURL

IOR post requests need to be sent to the following url:


Url: [DocketManagerSiteURL]/api/importquoterequest

SampleUrl: https://dmxml.docketmanager.net/api/importquoterequest


Note

Unique quote ID will be amended to "Imported Quote" for Qupte Name

i.e. Imported Quote - 123456790



XML Elements & Attributes


Element

Description

Required

ImportQuoteRequest

Root element
Attribute:Version=”1.0” (required)

*
ServiceInformation

Parent element
Information about the service sending the post request

*
ServiceName

Service Name,Version Number etc.

*
ServiceUrl

URL the request was sent from

*
ServiceTransactionId

Unique Identifier for the request (for auditing purposes)

*
Authentication Key
Unique key that must match your system key.

Located on the integrations page.

Customer

Parent element
Information about the Customer

*
CustomerId

Unique Identifier for the Customer 

If this identifier matches an external identifier on a customer, the quote will be created with that customer. If there is no match, a new customer will be created.
*
Name

Customer name

*
Phone

Customer phone number



Email

Customer email address



ContactName 

Contact name

It will attempt to find a contact belonging to the customer based on a name, phone number and email match and will create a new contact if no full match is found.
*
ContactPhone 

Contact phone number


ContactEmail 

Contact email address

*
ShippingLocation 

Parent element
Shipping Location information

If no billing location is provided, the system will use the default billing location on the contact. If the contact does not have a default billing location, it will use the customer's default billing location.  If the customer does not have a default billing location, the quote billing location will be left blank.  
 If the customer is new, any values provided will be set as the customer's default billing address. 


AddressName

Shipping address name

This is a "name" that described the address
i.e. the customer's name, default shipping address, location 1, etc.

Address 

Shipping address



City 

Shipping city


PostalZipCode 

Shipping postal / zip code



ProvinceState 

Shipping province/state



Country 

Shipping country


ShippingMethod

ShippingType

To set this value on the quote it must be an exact name match to a shipping type in the system. 

BillingLocation

Parent Element
Billing Location information

If no billing location is provided, the system will use the default billing location on the contact. If the contact does not have a default billing location, it will use the customer's default billing location. If the customer does not have a default billing location, the quote billing location will be left blank.
If the customer is new, any values provided will be set as the customer's default billing address.

AddressName

Billing address name

This is a "name" that described the address i.e. the customer's name, default shipping address, location 1, etc. 

Address

Billing address
City

Billing city
PostalZipCode

Billing postal / zip code
ProvinceState

Billing province/state
Country

Billing country
Quote

Parent element
Information pertaining to the quote

*
QuoteId 

Unique Identifier for the quote

*
QuoteDate

Date the quote was placed (M/d/yyyy h:mm:sstt)

*
Name

Quote name
SalesRep
(currently in beta) 

Sales Rep's Name

To set this value on the quote it must be an exact name match to a selectable active user in the system.

GenericNote
Quote generic note


PurchaseOrderNumber

PO number


ShippingTotal 

Shipping total for the quote


SubTotal

Sub total for the quote
Should equal the sum of the Item (ItemTotal+ ShippingTotal)


TaxTotal

Tax total for the quote


TaxPercentage

Tax percentage used to calculate the Tax Total
Allows comma separated list
TaxRate
(currently in beta) 


Tax rate name
Allows comma separated list

To set this value on the quote it must be an exact name match to a an active tax rate in the system. 

GrandTotal 

Grand Total for the quote
Should equal Sub Total+Tax Total


Items

Parent element
List of Items

*
ItemTotal

Item’s total price

This will be the overridden price of the item.


Quantity

Item quantity

This will be the selected quantity on the item.
*
Item Name

Item name

This will amend to the end of the current name of the product.

Item Code

Item product code (Unique Identifier from the requesting service)

Note: A Product with an external identifier (on the Online Tab of the Product) matching this item product code must be present in the DocketManager site receiving the post request.

*
Description

Item description

This will amend to the end of the current description of the product.



StockName

If Match Stock on the integrations page is set to 

No
Can be the Paper stock name and description
e.g. Bond blue 24lb offset

This will be included in the press note.

Yes (currently in beta) 
Name of the stock

To set this value on the item it must be an exact name match to the online name of an active stock 


RunSize
Item run size
Both values are required if used.
e.g. 8.5x11 

Replaces current run size values 

FlatSize
Item flat size
Both values are required if used.
e.g. 8.5x11 

Replaces current flat size values 

FinishSize 

Item finish size
Both values are required if used.
e.g. 8.5x11 

Replaces current finish size values



PressName
(currently in beta)

Item press name

To set this value on the item it must be an exact name match to an active press

ColorProcess 

Print color process
e.g. 4/4

This will be included in the press note. 


ColorName 

Ink color names
e.g. Reflex Blue, Pantone Metallic 8783C

This will be included in the press note. 


ColorCode

Ink color code
PMS Reflex Blue, 8783

This will be included in the press note. 


PressNote

General print/press notes & printing instructions



DepartmentItemName
(currently in beta) 


The name(s) of department items
Allows comma separated list 

To set this value on the item it must be an exact name match to the online name of an active department item

StartNumber
(currently in beta) 

The start number for numbering.

ArtworkNote 

General graphic/artwork notes & instructions



DownloadUrl 

URL to art work file (will be downloaded)



ShipDate
Date the item must ship (M/d/yyyy h:mm:sstt)


DueDate
(currently in beta) 
Date the item is due (M/d/yyyy h:mm:sstt)



OrderDueOption
(currently in beta) 

Order due option name

To set this value on the item it must be an exact name match to an active order due option


* Note the required elements and attributes


Response

Once a post request is sent a simple string response is returned depending on the outcome of the request.


The Response message is sent in the following format.

Success=[True/False]|Message=[ReturnedMessage]


Example Responses:


Succeeded

  • Success =True|Message=This Quote has been successfully imported as Quote# 1279
Failed
  • Success = False|Message = ImportQuoteRequest - Failed: Could not import this quote because Quote# 1279 already exists with the external Quote ID '115067326'. It appears that it has already been imported (ValidationException)
  • Success = False|Message = ImportQuoteRequest - Failed : Failed to deserialize input, this is the error occurred: YAXLib. YAX Attribute Missing Exception:Noattributeswiththisnamefound:'./Version'.


Example XML:


The following is an example of the xml structure which includes all required and optional elements:

<?xml version="1.0" encoding="UTF-8"?> 

<ImportQuoteRequest Version="1.0"> 

<ServiceInformation>

<ServiceName>ExternalService</ServiceName> 

<ServiceUrl>http://google.com</ServiceUrl> 

<ServiceTransactionId>123456</ServiceTransactionId>

<AuthenticationKey>1a2b3c-8f42-4071-b29b-bb929ebcc0e</AuthenticationKey>

</ServiceInformation>

<Customer>

<CustomerId>1</CustomerId>

<Name>Test Customer 1</Name>

<Phone>123-456-7890</Phone>

<Email>democompany@democompany.com</Email>

<ContactName>DemoContact</ContactName>

<ContactPhone>123-456-7890</ContactPhone>

<ContactEmail>democontact@democompany.com</ContactEmail>

</Customer>

<ShippingLocation>

<AddressName>Shipping Address</AddressName>

<Address>123FakeSt.</Address>

<City>SanFrancisco</City>

<PostalZipCode>94124</PostalZipCode>

<ProvinceState>California</ProvinceState>

<Country>USA</Country>

<ShippingMethod>Fedex</ShippingMethod>

</ShippingLocation>

<BillingLocation>

<AddressName>Billing Address</AddressName>

<Address>123FakeSt.</Address>

<City>SanFrancisco</City>

<PostalZipCode>94124</PostalZipCode>

<ProvinceState>California</ProvinceState>

<Country>USA</Country>

</BillingLocation>

<Quote>

<QuoteId>156350719</QuoteId>

<QuoteDate>7/21/2023 01:14:18 PM</QuoteDate>

<PurchaseOrderNumber>1234567890</PurchaseOrderNumber>

<QuoteName> Quote #1234 - Cards</QuoteName>

<SalesRep>Sarah Petty</SalesRep>

<GenericNote>Quote to completed</GenericNote>

<ShippingTotal>19.99</ShippingTotal>

<SubTotal>519.99</SubTotal>

<TaxTotal>39.00</TaxTotal>

<TaxPercentage>7.5</TaxPercentage>

<TaxRate>HST</TaxRate>

<GrandTotal>558.99</GrandTotal>

<Items>

<Item>

<ItemTotal>350.00</ItemTotal>

<Quantity>10000</Quantity>

<ItemName>Biz Cards</ItemName>

<ItemCode>1001</ItemCode>

<Description>Full color business cards</Description>

<StockName>Bond Thick</StockName>

<FinishSize>3.5x2</FinishSize>

<ColorProcess>4/4</ColorProcess>

<ColorName>CMYK</ColorName>

<ColorCode>CMYK</ColorCode>

<PressNote>Run this 12up</PressNote>

<ArtworkNote>No edits required, thanks.</ArtworkNote>

<DownloadUrl>https://dmxml.docketmanager.net/Crm/Customers/CustomerView.aspx?Id=0939f8bb-bb4b-4038-933f-9ce258a48bf3</DownloadUrl>

<ShipDate>7/22/2023</ShipDate>

<DueDate>7/23/2023</DueDate>

</Item>

<Item>

<ItemTotal>150.00</ItemTotal>

<Quantity>1000</Quantity>

<ItemName>Post Card Small</ItemName>

<ItemCode>1002</ItemCode>

<Description>Simple small postcards</Description>

<StockName>PostCard Stock</StockName>

<RunSize>12x18</RunSize>

<FlatSize>6x8</FlatSize>

<FinishSize>6x4</FinishSize>

<PressName>B/W Only</PressName>

<ColorProcess>4/1</ColorProcess>

<ColorName>CMYK,PMS151</ColorName>

<ColorCode>CMYK,151</ColorCode>

<PressNote />

<DepartmentItemName>Postage, Digital Addressing</DepartmentItemName>

<StartNumber>1000</StartNumber>

<ArtworkNote>Please update the sale date information</ArtworkNote>

<DownloadUrl>https://dmxml.docketmanager.net/Crm/Customers/CustomerView.aspx?Id=0939f8bb-bb4b-4038-933f-9ce258a48bf3</DownloadUrl>

<OrderDueOption>10 Days</OrderDueOption>

</Item>

</Items>

</Quote>

</ImportQuoteRequest>