Empty

£0.00
 
 

Close

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:

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

Element Attribute Description
OrderDetails customerPOId The Buyer's own unique reference number. This is optional.
OrderDetails statusId A flag to notify if the order is a live or a test order. "L" for live; "T" for test. This is optional. If this is not supplied or an unrecognised value is supplied, then the order is assumed to be a test order.
OrderDetails backOrder Instructs the Vendor whether or not to accept orders that contain items that are not currently in stock. Values: "Y" or "N". "N" indicates that the entire order will be rejected if one or more items are not in stock. This is optional. If it is not supplied or an unrecognised value is supplied, then the order will be set to "N" and rejected if one or more items are not in stock.
OrderDetails shippingCode This contains the code for the type of delivery. The code options are listed in the Delivery Codes table below. This is optional. If the code is not supplied or the code is not recognised, then the value will be set to "SND" (Standard Next Day Delivery).
OrderDetails shipComplete Instructs the Vendor either to Ship Complete (dispatch the order only when all items have been allocated) or to Part Ship (dispatch each item as soon as it becomes available). Values: "Y" (Ship Complete) or "N" (Part Ship). This is optional. If the value is not supplied or is unrecognised, then the value will be set to "Y" (Ship Complete).
BillTo/Address/CustomerName   30 characters limit
BillTo/Address/AddressLine1   30 characters limit
BillTo/Address/AddressLine2   30 characters limit
BillTo/Address/AddressLine3   30 characters limit
BillTo/Address/City   30 characters limit
BillTo/Address/County   22 characters limit
BillTo/Address/PostCode   8 characters limit
ShipTo/Address/DeliveryInstruction1   (optional) 30 characters limit
ShipTo/Address/DeliveryInstruction2   (optional) 30 characters limit
ShipTo/Address/DeliveryInstruction3   (optional) 30 characters limit
ShipTo/Address/CustomerName   30 characters limit
ShipTo/Address/AddressLine1   30 characters limit
ShipTo/Address/AddressLine2   30 characters limit
ShipTo/Address/AddressLine3   30 characters limit
ShipTo/Address/City   30 characters limit
ShipTo/Address/County   22 characters limit
ShipTo/Address/PostCode   8 characters limit
ProductLines/Item/SupplierPartID   Northamber's part number. Required.
ProductLines/Item/UnitPrice   The price in pounds sterling. It can be submitted as a decimal (<UnitPrice currency="GBP">29.99<UnitPrice>) or in pence (<UnitPrice currency="GBP">2999<UnitPrice>). This is optional. If no price is supplied or the price is not valid, then the standard Northamber trade price will be used when the order is placed.

OrderRequest Delivery Codes

Code Description Delivery Times
SND Standard (Next Day)1 Next business day
PMD Next Day PM (UK mainland only)2 Next business day - before 1:30pm
AMD Next Day AM (UK mainland only)2 Next business day - 7:10am to 10:30am
SAT Saturday (UK mainland only)3 Saturday delivery
  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.

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

Element Attribute Description
PNAItem supplierPartId Northamber's part number. This is optional.
PNAItem manufacturerPartNumber The manufacturer's part number. This is optional.

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>
	
OrderStatusRequest Elements & Attributes
Element Attribute Description
Order customerPOId The Buyer's own unique reference number. This is optional. If both acustomerPOId and a supplierOrderId is submitted, then thesupplierOrderId will be used to find the order.
Order supplierOrderId Northamber's order ID. This is optional. If both a customerPOId and asupplierOrderId is submitted, then the supplierOrderId will be used to find the order.

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 & conditionsE&OE.

All InvoiceResponses are copies of invoices.

InvoiceRequest Elements & Attributes

Element Attribute Description
Invoice supplierInvoiceId Northamber's invoice ID. This is optional. If this value is submitted, then both supplierOrderId and customerPOId will be ignored.
Invoice supplierOrderId Northamber's order ID. This is optional. If this value is submitted, thencustomerPOId will be ignored. If a supplierInvoiceId is also submitted, then both supplierOrderId and customerPOId will be ignored. N.B. A single order may get broken down into several invoices, and so a singlesupplierOrderId may pull up more than one invoice.
Invoice customerPOId The Buyer's own unique reference number. This is optional. If asupplierInvoiceId and/or a supplierOrderId is also submitted, thencustomerPOId will be ignored. N.B. A single order may get broken down into several invoices, and so a single customerPOId may pull up more than one invoice.
DateRange orderDateStart Inclusive. Must be in the format YYYY/MM/DD.
DateRange orderDateEnd Inclusive. Must be in the format YYYY/MM/DD.
DateRange invoiceDateStart Inclusive. Must be in the format YYYY/MM/DD.
DateRange invoiceDateEnd Inclusive. Must be in the format YYYY/MM/DD.
LatestInvoices invoiceDateStart Optional. Must be in the format YYYY/MM/DD.

Error Messages Returned by the TransactionError File

Error No Description
100 An unknown error has occurred.
101 This service has been switched off.
102 This a test submission and no data has been submitted to the database.
200 OK.
300 Access to this service is restricted.
301 Not sent via https.
302 The submission method has not been recognised.
303 The UserName and/or Password has not been recognised.
304 You have not been granted permission to use this service.
305 Your account has locked out. This happens when an incorrect UserName and/or Password has been submitted too many times. If you wish to unlock your account, go to the www.northamber.com login page.
306 Your account has been suspended.
307 You cannot choose this delivery option. All special deliveries (i.e. everything except the Standard Next Day delivery (SND)) can be made to the UK mainland only and must be placed before 5pm. Next Day PM (PMD) and Next Day AM (AMD) deliveries cannot be placed on Saturday or Sundays. Saturday (SAT) deliveries can only be placed on Fridays before 5pm. You can still place this order if you choose the Standard Next Day delivery option (SND).
308 The postcode provided with the shipping address could not be validated
400 One or more submitted values have been rejected.
401 One or more required values have not been submitted.
402 One or more submitted values are invalid.
500 An error occurred whilst submitting your data to the database.
501 An order with the same Customer Reference number already exists on the database. The same order may have been submitted twice for some reason. If you only wanted to place this order once, you can ignore this message as your order will have been placed once and not duplicated. If you still wish to place this order, change the Customer Reference number to a unique number and try placing the order again.
502 None of the items you submitted could be ordered. This is either because they are not currently in stock or because they are no longer on our database.
503 One or more of the items you submitted could NOT be ordered. This is either because they are not currently in stock or because they are no longer on our database. Since you have chosen not to allow backorders, this order has been cancelled.
600 An XML error has occurred.
601 The submitted XML contains errors: the XML is not well-formed.
602 The submitted XML is well-formed but is not recognised as valid.

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
    medium_quotewerks_region.png
  8. Next click the Other Realtime tab
  9. Scroll down till you see Northamber then enter your details
    medium_quotewerks_userdetails.png
  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
    medium_quotewerks_elitize.png