- What is the Northamber Gateway XML Feed?
- What is HTTPS?
- How do I set up my XML feed?
- How do I place orders through Northamber's Gateway?
- How can I check price & availability?
- How can I check the status of an order?
- How can I check invoice details?
- Error Messages Returned by the TransactionError File
- Integrate with QuoteWerks
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
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 |
- 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.
- 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.
- 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>
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 & conditions. E&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. |
- 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
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:
- First make sure you have your XML gateway username and password to hand
- Click Tools
- Click Options
- Click the Real-time tab
- Click the Real-time Setup button
- Click the Product Content Subscription tab
- Ensure that the region is set to the UK
- Next click the Other Realtime tab
- Scroll down till you see Northamber then enter your details
- Click Ok and exit the Options area
- Now when you search, make sure you use Elitize and it should interrogate our gateway for your prices