XML Gateway Guide

What is the Northamber Gateway XML Feed?

Northamber's Gateway allows anyone set up with a Gateway account to submit XML over HTTPS to do the following:

• submit bulk orders
• check price & availability
• check the status of orders
• get invoice details

What is HTTPS?

Hypertext Transfer Protocol over Secure Socket Layer or HTTPS provides authentication and encrypted communication and is widely used on the World Wide Web for security-sensitive communication such as payment transactions and corporate information systems.

How do I set up my XML feed?

In order to use the Gateway service, you first need to set up a Gateway account with Northamber. If you would like to set up an account, click here to contact Technical Support.

Once an account is set up, all data submissions are made to:

https://www.northamber.com/gateway/gateway.php

You can use the following submission methods to submit data to Northamber:

• XmlHttp via HTTPS POST - You can use XmlHttp to submit data using HTTPS POST (i.e. form submission). Click here for example XmlHttp Request code.
• File Upload - You can use the file upload button on the Gateway File Upload page to submit XML files.Click here to go to the Gateway XML File Upload page.

How do I place orders through Northamber's Gateway?

You can use an OrderRequest to place orders with Northamber. If successful, an OrderResponse will be returned, indicating that the data has been submitted successfully. Otherwise, you will receive aTransactionError response.

	<?xml version="1.0" encoding="utf-8"?>
	<OrderRequest version="1.0" xml:lang="en-GB">
		<TransactionHeader username="" password="" />
		<OrderDetails customerPOId="" statusId="" backOrder="" shippingCode="" shipComplete="">
			<BillTo>
				<Address>
					<CustomerName></CustomerName>
					<AddressLine1></AddressLine1>
					<AddressLine2></AddressLine2>
					<AddressLine3></AddressLine3>
					<City></City>
					<County></County>
					<PostCode></PostCode>
					<Country></Country>
					<Email></Email>
				</Address>
			</BillTo>
			<ShipTo>
				<Address>
					<!-- - Optional fields, uncomment to use
					<DeliveryInstruction1></DeliveryInstruction1>
					<DeliveryInstruction2></DeliveryInstruction2>
					<DeliveryInstruction3></DeliveryInstruction3>
					<!- -->
					<CustomerName></CustomerName>
					<AddressLine1></AddressLine1>
					<AddressLine2></AddressLine2>
					<AddressLine3></AddressLine3>
					<City></City>
					<County></County>
					<PostCode></PostCode>
					<Country></Country>
					<!-- - Optional fields, uncomment to use
					<Email></Email>
					<!- -->
				</Address>
			</ShipTo>
			<!-- - Optional section, uncomment to use
			<ExtendedOrderInfo>
					<EndUserPhone></EndUserPhone>
					<EndUserName></EndUserName>
					<EndUserOrderNo></EndUserOrderNo>
			</ExtendedOrderInfo>
			<!- -->
			<ProductLines>
				<Item lineNumber="" quantity="">
					<SupplierPartID></SupplierPartID>
					<UnitPrice currency="GBP"></UnitPrice>
				</Item>
			</ProductLines>
		</OrderDetails>
	</OrderRequest>

Note: ExtendedOrderInfo is only required if the functionality has been agreed with your account manager, please enquire with them about what we can do with this information.

The OrderResponse is a simple acknowledgement for receiving of the order message. It does not confirm the placing of the order – it only confirms the receipt of the order and returns a result code back to the purchasing system.

To request more detailed information about a submitted order, you will need to submit an OrderStatusRequest.

OrderRequest Elements & Attributes

OrderRequest Delivery Codes

1. Orders should be placed before 5.30pm to guarantee next day delivery. Orders placed after that will be delivered the following business day. Use the Saturday (SAT) option if you want next day delivery on a Friday.
2. Next Day AM/PM deliveries must be placed before 5pm and cannot be placed on Saturdays or Sundays. Orders placed on a Friday will arrive in the chosen time slot on the following Monday (Tuesday, if Bank Holiday). Use the Saturday (SAT) option if you want next day delivery on a Friday.
3. Saturday deliveries can only be placed on Fridays before 5pm. Orders must be to the UK mainland only.

• Example XML OrderRequest
• Example OrderResponse
• Example TransactionError

How can I check price & availability?

You can use an PNARequest to check the price and availability of a product. If successful, aPNAResponse will be returned. Otherwise, you will receive a TransactionError response.

	<?xml version="1.0" encoding="utf-8"?>
	<PNARequest version="1.0" xml:lang="en-GB">
		<TransactionHeader username="" password=""/>
		<PNAList>
			<PNAItem supplierPartId="" manufacturerPartNumber="" />
		</PNAList>
	</PNARequest>
	

For each item, you can submit either a Northamber part number (supplierPartId) or a manufacturer part number (manufacturerPartNumber). If both are supplied, then the supplierPartId will be used.

If the part number is not recognised, then no result will be returned for that item.

PNARequest Elements & Attributes

• Example XML PNARequest
• Example PNAResponse
• Example TransactionError

How can I check the status of an order?

You can use an OrderStatusRequest to check the status of orders. If successful, anOrderStatusResponse will be returned. Otherwise, you will receive a TransactionError response.

	<?xml version="1.0" encoding="utf-8"?>
	<OrderStatusRequest version="1.0" xml:lang="en-GB">
		<TransactionHeader username="" password="" />
		<Orders>
			<Order customerPOId="" supplierOrderId="" />
		</Orders>
	</OrderStatusRequest>
	

• Example XML OrderStatusRequest
• Example OrderStatusResponse
• Example TransactionError

How can I check invoice details?

You can use an InvoiceRequest to obtain invoice details. If successful, an InvoiceResponse will be returned. Otherwise, you will receive a TransactionError response.

There are multiple methods available to help you fetch exactly what you need.

Option 1 - By Reference

You can supply multiple Invoice references within an <Invoices> section, making sure to provide at least one form of reference from this list:

• the Northamber Invoice ID (supplierInvoiceId)
• the Northamber Order ID (supplierOrderId)
• your own Customer Reference Number (customerPOId):

	<?xml version="1.0" encoding="utf-8" ?>
	<InvoiceRequest version="1.0" xml:lang="en-GB">
		<TransactionHeader username="" password="" />
		<Invoices>
			<Invoice customerPOId="ExampleRef" />
			<Invoice supplierInvoiceId="ExampleInvoiceID" />
			<Invoice supplierOrderId="ExampleOrderID" />
		</Invoices>
	</InvoiceRequest>

Option 2 - Order Date Range

You can specify an order date range using a <DateRange> section and specifying orderDateStart and orderDateEnd:

	<?xml version="1.0" encoding="utf-8" ?>
	<InvoiceRequest version="1.0" xml:lang="en-GB">
		<TransactionHeader username="" password="" />
		<DateRange orderDateStart="2017/05/20" orderDateEnd="2017/05/24" />
	</InvoiceRequest>
	

Option 3 - Invoice Date Range

You can specify an invoice date range using a <DateRange> section and specifying invoiceDateStart and invoiceDateEnd:

	<?xml version="1.0" encoding="utf-8" ?>
	<InvoiceRequest version="1.0" xml:lang="en-GB">
		<TransactionHeader username="" password="" />
		<DateRange invoiceDateStart="2017/05/20" invoiceDateEnd="2017/05/24" />
	</InvoiceRequest>

Option 4 - Latest Invoices

By providing an empty LatestInvoices tag you will receive any invoices which have been raised since your last connection. Upon your first use of this functionality you will be automatically supplied the last 7 calendar days worth of invoices, afterwards it will be from the date of the last invoice you downloaded:

	<?xml version="1.0" encoding="utf-8" ?>
	<InvoiceRequest version="1.0" xml:lang="en-GB">
		<TransactionHeader username="" password="" />
		<LatestInvoices />
	</InvoiceRequest>

Option 5 - Latest Invoices Since Date

By providing a LatestInvoices tag with invoiceDateStart specified, you will receive all invoices since that date. As with option 4, future requests with an empty LatestInvoices tag will be from the date of the last invoice you downloaded:

	<?xml version="1.0" encoding="utf-8" ?>
	<InvoiceRequest version="1.0" xml:lang="en-GB">
		<TransactionHeader username="" password="" />
		<LatestInvoices invoiceDateStart="2017/05/20" />
	</InvoiceRequest>

Each <InvoiceRequest> option works exclusively, so mixing them up will return unpredicatable results. For reference the parsing order of the file is the same as the option order listed here, any subsequently detected option within the same file will be ignored.

Goods remain strictly the property of Northamber PLC until paid for in full. Strictly subject to our terms & conditions. E&OE.

All InvoiceResponses are copies of invoices.

InvoiceRequest Elements & Attributes

• Example XML InvoiceRequest using an <Invoices> section
• Example XML InvoiceRequest using a <DateRange> section by Order Date
• Example XML InvoiceRequest using a <DateRange> section by Invoice Date
• Example XML InvoiceRequest using a <LatestInvoices> tag
• Example XML InvoiceRequest using a <LatestInvoices> tag with a specific start date
• Example InvoiceResponse
• Example TransactionError

Error Messages Returned by the TransactionError File

How can I integrate with QuoteWerks?

To correctly setup your QuoteWerks software please follow the instructions below:

1. First make sure you have your XML gateway username and password to hand
2. Click Tools
3. Click Options
4. Click the Real-time tab
5. Click the Real-time Setup button
6. Click the Product Content Subscription tab
7. Ensure that the region is set to the UK
   
8. Next click the Other Realtime tab
9. Scroll down till you see Northamber then enter your details
   
10. Click Ok and exit the Options area
11. Now when you search, make sure you use Elitize and it should interrogate our gateway for your prices