Transactions: Orders, Receipts, Invoices & More
-
Setup and Process Peppol Invoices
Overview
Peppol is an electronic invoice integration standard available for customers in Australia and New Zealand. It allows suppliers to send customers electronic invoices so you can process them without manual data entry. More details can be found here.
Peppol provides the ability to receive electronic invoices from both Registered and Lite suppliers
Setting up Peppol in your Community
Before you can receive Peppol invoices from suppliers you must register with a Peppol Access Point who manage the transmission of Peppol invoices from the Peppol Network to Unimarket. Please contact Unimarket for Access Point options.
Once you are setup with an Access Point, Unimarket will configure the integration to start receiving invoices from the Access Point. The following needs to be in place:
- You community needs to have an NZBN or ABN number specified in Community Settings. This is used to identify in the Invoice Receiver.
- Your suppliers need to have an NZBN or ABN number specified in their Profile. This is used to match the invoice to the correct supplier in your Community. Note there cannot be duplicates or the invoice will fail.
- Your Community needs to be setup with inbound sFTP (secure file transfer) so that you can receive Peppol invoices.
Managing Peppol Invoices
Peppol invoices are sent to your Community from the Access Point to your sFTP folder. Unimarket then validates the invoice to ensure it contains all the required information and is compliant with the electronic invoicing standard. The results can be reviewed on the File Processing page within Community Admin.
- Success: If the invoice was processed successfully it will show as Success and there will be a link to the invoice in your community.
-
Error: If the invoice was not successfully processed it will appear on the File Processing page with a summary of the error under the info hover icon.
- Note that Unimarket requires invoices to have a purchase order or they will generate an Error.
Notifying Suppliers of Errors
The sFTP process used to receive invoices means 2-way communication with suppliers is not supported. When there are errors the customer should communicate to the supplier directly so they can fix and resend the invoice or provide it in a different way (e.g. if there is no order).
Matching
Once a Peppol invoice has been processed successfully it will be matched like all other invoices.
-
Electronic Invoicing
What is eInvoicing?
eInvoicing is the electronic exchange of invoice information directly between your supplier's system and your Unimarket Community. eInvoicing eliminates the need for suppliers and buyers to create and process PDF and paper invoices, reducing processing costs and administrative efforts while increasing accuracy, payment speed, and data capture efficiency.
Unimarket supports two global standards for eInvoicing to ensure that we can offer flexible options when connecting with your suppliers. However, from a customer perspective, the standard used is less critical because both provide all the necessary data and compliance to generate a valid invoice.
The key takeaway here is that electronic invoicing offers a substantial improvement in accuracy and efficiency compared to the PDF alternative, eliminating the requirement for manual data entry.
cXML (Commerce XML)
cXML is an industry-standard for digital invoice transmission, widely embraced in the industry, making it a seamless setup with your suppliers. Unimarket is fully capable of receiving invoices from your suppliers in the cXML format through direct integration between their system and your Unimarket community.
How do I get setup with cXML?
As part of customer and supplier enablement projects, the Unimarket Supplier Management team will handle the setup and testing of cXML integration. Customers need not take any action in this regard. However, it's important to note that this form of integration necessitates that the supplier supports cXML and completes registration as a Premium Supplier on Unimarket.
PeppolPeppol is a European digital standard which has been adopted by the Australian and New Zealand Government as part of their push to drive electronic invoicing. Peppol sends invoices through a common Peppol Network using certified Access Points. This means that customers signing up to use Peppol will have immediate access to all their suppliers currently enabled on the network. For example, suppliers using finance solutions such as XERO and MYOB have Peppol capability built into these tools and will have the option to send you an electronic invoice rather than a PDF invoices. The integration is one-to-many and allows you to scale electronic invoicing quickly.
How do I get setup on Peppol?
Sign up for Unimarket Peppol Integration
Unimarket has designed a specialized integration tailored for Peppol, allowing us to seamlessly receive and process invoices from the Peppol Network. To enable this Peppol integration, there is an associated annual integration support cost.
Register with a Peppol Access Point
All Peppol invoices received from the network must come through a registered Peppol Access Point, to which Unimarket's integration is connected. Customers must independently register for a Peppol Access Point to establish connectivity with the Peppol Network. It's important to clarify that Unimarket itself does not operate as an Access Point; however, we do have a trusted Access Point partner available for businesses that do not already have one.
Please be aware that registering with an Access Point incurs a transactional cost for managing invoice traffic. This cost is seperate from the Unimarket Peppol Integration.
Whats next?
Upon the successful setup completion, your suppliers will transmit their invoices through the Peppol Network. These invoices are guided by identifiers, ensuring their precise routing to your dedicated Access Point. Subsequently, they descend into Unimarket for a matching process facilitated by our integration.
In the event of an existing invoice integration between Unimarket and your ERP, the final act unfolds. We seamlessly transfer the matched invoice data into your ERP, preparing the stage for payment processing.
-
cXML Order Integration - Change Orders
Identifying change orders within the order integration
Change orders can be setup in 2 ways within Unimarket:
- Unimarket can issue a new number when an order is changed; or
- Unimarket can issue the same number with an order version number
Using new numbers
If the configuration is set to use a new order number each time an order is edited, then the following sequence of events will occur:
- Order is created. An order integration message is sent with a new order number and the Type of 'NEW'
- Order is then edited by the user.
- A second order integration message is sent with the original order number, and the Type of 'DELETE'
- A third order integration message follows with a new order number, and the Type of 'NEW'
<OrderRequest>
<OrderRequestHeader orderDate="2023-04-06T14:33:37.680+12:00"
orderID="1004891"
orderType="regular"
type="delete"><OrderRequest>
<OrderRequestHeader orderDate="2023-04-06T14:35:19.707+12:00"
orderID="1004892"
orderType="regular"
type="new">The message details of the replacement order provides extrinsic details that link the replacement order back to the originating (edited) order via the order-source-type and the order-source-identifier (order number of the edited order).
</Extrinsic>
<Extrinsic name="shippingNote"/>
<Extrinsic name="order-submission">ELECTRONIC</Extrinsic>
<Extrinsic name="requisition-created-date">2023-04-06T14:34:20.000+12:00</Extrinsic>
<Extrinsic name="organization">Unimarket eProcurement</Extrinsic>
<Extrinsic name="organization-unit">Information Technology</Extrinsic>
<Extrinsic name="requisition-justification"/>
<Extrinsic name="is-retrofit-order">no</Extrinsic>
<Extrinsic name="order-source-type">EDIT_ORDER</Extrinsic>
<Extrinsic name="order-source-identifier">1004891</Extrinsic>
<Extrinsic name="requisition-source-type">EDIT_ORDER</Extrinsic>Using order versions
If the configuration is set to use a new order version each time an order is edited, then the following sequence of events will occur:
- Order is created. An order integration message is sent with a new order number and the Type of 'NEW'
- Order is then edited by the user.
- A second order integration message is sent with the original order number, and the Type of 'UPDATE'. This will also contain a version number.
<OrderRequest>
<OrderRequestHeader orderDate="2023-03-09T16:54:51.281+10:00"
orderID="100024"
orderType="regular"
type="new">After the order is changed:
<OrderRequest>
<OrderRequestHeader isInternalVersion="no"
orderDate="2023-03-09T16:55:38.672+10:00"
orderID="100024"
orderType="regular"
orderVersion="2"
type="update"> -
Integration Options for Validate Account Code (Budget Check) Integration
Overview
The Unimarket Validate Account Code integration is a 2-way synchronous integration point triggered during the checkout process to tell the user if the account(s) they are using on their requisition are valid and/or have budget. It can be used to check all or some of the following:
- if a user is eligible to purchase against the account codes specified on their requisition
- the validity of account code combinations
- if there is budget in the accounts specified on their requisition
Process
When the user clicks 'checkout' the integration is triggered to check the accounting and budget in the customer's ERP solution. The ERP then responds back with the required information and a 'valid', 'invalid' or 'warning' response. The ERP can also optionally provide a Message if the customer wants specific information displayed to the user.
Integration Details
The Validate Account Code integration point is an XML based integration. Details and examples of the Request/Response message can be downloaded below. Customers can either integrate directly with the XML integration point or use middleware like the Unimarket Connector to manage the integration (see below).
Using the Connector to Handle Validate Account Code (Budget Check) Integration
If the Unimarket Connector is used the manage customer integration then the following are examples of how the Connector can be configured to retrieve account code and budget information from the ERP solution.
Note: The specification for each customer is specific based on the options required. Below are examples to illustrate possible approaches. Option: Calling a Stored Procedure (SP)
The Connector is used to called a customer stored procedure which will provide the connector with the required account code / budget information.
INPUT to the SP: (minimum required) (example as JSON array)
[
{"line_number": 1, "account": 123-4567-10, "amount": 123.12},
{"line_number": 2, "account": 123-4567-11, "amount": 200.00},
{"line_number": 3, "account": 123-4567-12, "amount": 738.50},
{"line_number": 4, "account": 123-4567-13, "amount": 120.15},
{"line_number": 5, "account": 123-4567-14, "amount": 23.12}
]line_number : Integer - line number of items in the checkout
account : String - the account code for the line item
amount : numeric - the value to checkout for the line itemOptional Values
The following optional values can be used:
username: The user trying to purchase against the account code. Used to determine if they have permission to purchase against the account.
organisation unit: The user's organisation unit. Used to determine if they have permission to purchase against the account.
finance year: The Financial Year of the transaction used to validate the correct budget year. Only applicable if the community has FY's setup.
OUTPUT after SP call:
[
{"line_number": 1, "status": "Valid", "message": ""},
{"line_number": 2, "status": "Invalid", "message": "Some message"},
{"line_number": 3, "status": "Invalid", "message": "Some message"},
{"line_number": 4, "status": "Warning", "message": ""},
{"line_number": 5, "status": "Valid", "message": ""}
]line_number : Integer - line number of items in the checkout
statue : String - "valid": all good to go; "invalid": hard stop; "warning": soft stop, allow checkout to proceed, but with some message displayed(low on budget etc)
message : String - optional string to be display if invalid or warningPros:
- More "real-time", each checkout will call the budget-check SP
- Customer has total control of their business logic
- The actual budget is hidden (as it maybe sensitive information)
Cons:
- Will need to deal with complex data type and message format
- More implement effort at customer side
Option: Reading a Budget Table
The Connector is used to read a customer 'budget table' which will provide the connector with the required account code / budget information.
Minimum table structure required:"ACCOUNT CODE", "BUDGET"
4740-14100-10, 46.33
4740-14100-11, -114.5
4740-14100-12, 500.32
The table would only need two columns: "ACCOUNT CODE" and "BUDGET" as minimum required.If needs other business logic , more columns can be added, such as financial year, organisation unit etc (see notes on these option values above).
- "ACCOUNT CODE" - String (e.g. 1234-2345-AD7644)
- "BUDGET" - numeric
- The table should only contain valid account codes, any purchasing account not found in the table would be "invalid" and rejected
- A previously valid account code will need to be removed from table if it becomes invalid
- The table data would need to be updated regularly (the frequency depends, we have customers doing daily, most commonly hourly)
Pros
- Solution is simple to implement on the customer side
Cons
- The account's budget is exposed
- Less "real-time"
- Validation logic is implemented by Unimarket, changes later would involve us for update (cost of time and material). For example any Messages for display to the user will be hardcoded on the connector.
-
Purchase Order Integration (OrderRequest) Overview
Overview
The OrderRequest integration is used to communicate order details between Unimarket and an external system. The OrderRequest may be used by Unimarket to update external systems (outbound) or for external system to update Unimarket (inbound). The OrderRequest message follows the cXML standard for orders.
Why use this integration?
This integration is commonly used to update supplier systems and external ERP/Finance systems with order details when a Purchase Order is generated within Unimarket. Example below:
OrderRequest Technical Documentation
Technical details relating to the OrderRequest integration can be found below:
Supplier Setup
Login to the supplier eStore and go to Edit Store, then select the Integration tab.
Field Purpose Dispatch Mechanism Determines how the electronic message will be sent to the supplier. This must be set to the mechanism the supplier supports (ask the supplier). URL This is the URL where the electronic PO's will be sent. The supplier will provide the URL. If a Gateway such as Tranzsoft is being used to pass messages between Unimarket and the supplier then the URL will be the gateway URL not the supplier URL. The supplier or Gateway service provider will provide this. FROM Credential Domain This identifies the Community Domain where the orders are being sent from. This is the key information for the supplier to identify the customer that is sending them the order. If the supplier sets the 'FROM Credential Identity' as their DUNS number then this is usually set to the word DUNS (but can be anything). FROM Credential Identity This identifies the Community where the orders are being sent from. This is the key information for the supplier to identify the customer that is sending them the order. It can be set to anything but it is commonly set to the Communities DUNS number. TO Credential Domain This identifies the Supplier Domain where the orders are being sent to. If the supplier sets the 'TO Credential Identity' as their DUNS number then this is usually set to the word DUNS (but can be anything). It is rarely verified by the supplier. TO Credential Identity This Supplier Identity where the orders are being sent to. It is commonly set to the suppliers DUNS number (but can be anything). It is rarely verified by the supplier. Shared Secret This is a password that must be set within Unimarket and within the supplier's system. The 2 must match. The bulk of the order integration settings above stay the same for all Communities. The 2 credentials that must change for each community are the FROM Credentials. These are used to uniquely identify the specific community.
-
Purchase Order (OrderRequest) Technical Documentation
Overview
Purchase Order Integration uses the cXML standard to send orders to Communities from Unimarket.
This will be sent to a HTTP(S) endpoint using the POST method containing the cXML payload. Ideally this should be secured by TLS1.2.
In this Article
Example Basic Purchase Order
<?xml version="1.0" encoding="UTF-8"?>
<cXML payloadID="[A Unique Value]" timestamp="2020-11-16T12:17:51.945+13:00" version="1.2.021" xml:lang="en">
<Header>
<From>...</From>
<To>...</To>
<Sender>...</Sender>
</Header>
<Request deploymentMode="test">
<OrderRequest>
<OrderRequestHeader orderDate="2020-11-16T12:17:51.124+13:00" orderID="102" orderType="regular" type="new">
<Total>
<Money currency="NZD">5.75</Money>
</Total>
<ShipTo>...</ShipTo>
<BillTo>...</BillTo>
<Shipping>...</Shipping>
<Tax>...</Tax>
<Contact role="buyer">...</Contact>
<Extrinsic name="buyer-credential">...</Extrinsic>
<Extrinsic name="shippingNote"/>
</OrderRequestHeader>
<ItemOut lineNumber="1" quantity="1" requisitionID="56">...</ItemOut>
<ItemOut lineNumber="2" quantity="4" requisitionID="56">...</ItemOut>
</OrderRequest>
</Request>
</cXML>
Header
The Purchase Order starts with the Header which can used to authenticate the message. For Communities these are left empty.
<Header>
<From>
<Credential domain="">
<Identity/>
</Credential>
</From>
<To>
<Credential domain="">
<Identity/>
</Credential>
</To>
<Sender>
<Credential domain="">
<Identity/>
<SharedSecret/>
</Credential>
<UserAgent>unimarket</UserAgent>
</Sender>
</Header>
Request
The Request element contains the the OrderRequest and shows if this purchase order has been sent from a Test or Production environment.
Test:
<Request deploymentMode="test">
Production:
<Request deploymentMode="production">
OrderRequest
The OrderRequest contains attributes that describe the orderDate, orderID, orderType and type.
<OrderRequestHeader orderDate="2020-11-16T12:17:51.124+13:00" orderID="102" orderType="regular" type="new">
The orderDate attribute is the date and time the order was generated in the format:
YYYY-MM-DD'T'hh:mm:ss.SSSZ
The orderID attribute is the purchase order number.
The orderType attribute is the type of order this is. This could be: "regular" or "blanket".
The type is the status of the order:
new - This is a new order.
update - This means the order has been updated. The order will contain all details as they have been updated. Two new attributes will now be included in OrderRequest: orderVersion and isInternalVersion.
The orderVersion attribute shows the version number for this order. It will start from 2 and increase.
The isInternalVersion attribute is a flag that indicates if this change should be hidden from the supplier. This will be set to "no".
delete - This means the order has been cancelled.
Total
The total element contains the Money Element. The Money element shows the total value of all items included in the order including taxes. The currency attribute shows the currency code.
<Total>
<Money currency="NZD">5.75</Money>
</Total>
ShipTo
This ShipTo element contains address information on where the Community would like the order to be delivered.
<ShipTo>
<Address addressID="101" isoCountryCode="NZ">
<Name xml:lang="en">Branch Location</Name>
<PostalAddress>
<DeliverTo>Mike Brady</DeliverTo>
<Street>456 Something Drive</Street>
<City>Auckland</City>
<State/>
<PostalCode>1010</PostalCode>
<Country isoCountryCode="NZ">New Zealand</Country>
</PostalAddress>
<Email>mike.brady@unimarket.com</Email>
</Address>
</ShipTo>The Address addressID attribute is a unique identifier for the ShipTo location in Unimarket.
The Name element is the name assigned to the location.
The PostalAddress element includes multiple elements relating to the address.
The DeliverTo element will show the Attention field value selected during checkout. By default this is the Buyers name.
The Street element can be repeated up to 3 times and contains information about the street address.
The City element contains the city.
The State element contains the state or region.
The PostalCode element contains the post or zip code.
The Country element contains the country and the isoCountryCode attribute is the ISO country code.
The Email element contains the email address for the Buyer.
BillTo
This BillTo element contains address information on the billing address for the order.
<BillTo>
<Address addressID="001" isoCountryCode="NZ">
<Name xml:lang="en">Head Office</Name>
<PostalAddress>
<Street>123 Something Street</Street>
<City>Auckland</City>
<State/>
<PostalCode>1010</PostalCode>
<Country isoCountryCode="NZ">New Zealand</Country>
</PostalAddress>
<Email>mike.brady@unimarket.com</Email>
</Address>
</BillTo>The Address addressID attribute is a unique identifier for the BillTo location in Unimarket.
The Name element is the name assigned to the location.
The PostalAddress element includes multiple elements relating to the address.
The Street element can be repeated up to 3 times and contains information about the street address.
The City element contains the city.
The State element contains the state or region.
The PostalCode element contains the post or zip code.
The Country element contains the country and the isoCountryCode attribute is the ISO country code.
The Email element contains the email address for the Buyer.
Shipping
This is the header level Shipping amount. The element will be included even when there is no charge.
<Shipping>
<Money currency="NZD">0.00</Money>
<Description xml:lang="en">Standard Delivery</Description>
</Shipping>
Tax
This is the summary Tax information for the orders, including the break down of the shippingTax and the tax for the lines.
<Tax>
<Money currency="NZD">0.75</Money>
<Description xml:lang="en">NZ GST</Description>
<TaxDetail category="GST" percentageRate="15.00" purpose="shippingTax">
<TaxableAmount>
<Money currency="NZD">0.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">0.00</Money>
</TaxAmount>
<Description xml:lang="en">NZ GST</Description>
</TaxDetail>
<TaxDetail category="GST" percentageRate="15.00" purpose="tax">
<TaxableAmount>
<Money currency="NZD">5.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">0.75</Money>
</TaxAmount>
<Description xml:lang="en">NZ GST</Description>
</TaxDetail>
</Tax>The TaxDetail element contains the category, percentageRate and purpose attributes along with the TaxableAmount and TaxAmount elements.
<TaxDetail category="GST" percentageRate="15.00" purpose="tax">
<TaxableAmount>
<Money currency="NZD">5.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">0.75</Money>
</TaxAmount>
<Description xml:lang="en">NZ GST</Description>
</TaxDetail>The category attribute is the type of tax that is being applied.
The percentageRate attribute is the tax rate being applied.
The purpose attribute indicates which part of the order is included in the tax calculation.
The TaxableAmount element is the subtotal amount excluding tax.
The TaxAmount element is the amount of tax for the TaxableAmount.
Note: There is a TaxDetail element for each purpose.
Contact
This contains the Name and Email Address for the Buyer.
<Contact role="buyer">
<Name xml:lang="en">Mike Brady</Name>
<Email>mike.brady@unimarket.com</Email>
</Contact>
Extrinsics
Extrinsics are additional elements that can be included to extend the cXML standard.
This is where you can find additional information about the order.
<Extrinsic name="buyer-credential">
<Credential domain="unimarket-user">
<Identity>mike.brady@unimarket.com</Identity>
</Credential>
</Extrinsic>
<Extrinsic name="shippingNote"/>
<Extrinsic name="requisition-created-date">2020-11-16T12:17:51.055+13:00</Extrinsic>
<Extrinsic name="organisation">Mike Test Environment</Extrinsic>
<Extrinsic name="organisation-unit">Testing</Extrinsic>
<Extrinsic name="is-retrofit-order">no</Extrinsic>
<Extrinsic name="order-source-type">DEFAULT</Extrinsic>
<Extrinsic name="requisition-source-type">DEFAULT</Extrinsic>
ItemOut
The ItemOut element is repeated for each item that is included in the order.
<ItemOut lineNumber="1" quantity="1">
<ItemID>
<SupplierPartID>1010003</SupplierPartID>
<SupplierPartAuxiliaryID/>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="NZD">1.00</Money>
</UnitPrice>
<Description xml:lang="en">Product Code 10003</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">44000000</Classification>
<ManufacturerName xml:lang="en">Description 10003</ManufacturerName>
</ItemDetail>
<SupplierID domain="external-id">TestVendorID</SupplierID>
<ShipTo>...</ShipTo>
<Shipping>...</Shipping>
<Tax>...</Tax>
<Comments/>
</ItemOut>The ItemOut lineNumber attribute is the line number for that item on the order.
The ItemOut quantity attribute is the quantity ordered for the item.
<ItemOut lineNumber="1" quantity="1">
ItemID
This includes identifying codes for the item.
<ItemID>
<SupplierPartID>1010003</SupplierPartID>
<SupplierPartAuxiliaryID/>
</ItemID>The SupplierPartID element is the product/item/SKU code for the item.
The SupplierPartAuxiliaryID element is a supporting code used in conjunction with the SupplierPartID. This is typically used for configuration details for a variable items.
ItemDetail
This includes more descriptive elements about the item.
<ItemDetail>
<UnitPrice>
<Money currency="NZD">1.00</Money>
</UnitPrice>
<Description xml:lang="en">Product Code 10003</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">44000000</Classification>
<ManufacturerName xml:lang="en">Description 10003</ManufacturerName>
</ItemDetail>The UnitPrice element is the price per unit excluding tax for the item.
The Description element is the name for the item.
The UnitOfMeasure element is the in which the unit is measured for the item.
The Classification element is the UNSPSC for the item. This is derived from the catalogue when the item is selected, from the default category for the supplier set by the customer or blank if it's not supplied.
<Classification domain="UNSPSC">44000000</Classification>
The ManufacturerName element the item description of the item along with any form details.
SupplierID
The SupplierID element will contain the Supplier ID assigned by the Community or when this is not assigned; it will default to the unique ID generated by Unimarket for the supplier.
external-id:
<SupplierID domain="external-id">TestVendorID</SupplierID>
unimarket-code:
<SupplierID domain="unimarket-code">[Unique Supplier UUID]</SupplierID>
ShipTo
This ShipTo element contains address information on where the customer would like the order to be delivered.
<ShipTo>
<Address addressID="101" isoCountryCode="NZ">
<Name xml:lang="en">Branch Location</Name>
<PostalAddress>
<DeliverTo>Mike Brady</DeliverTo>
<Street>456 Something Drive</Street>
<City>Auckland</City>
<State/>
<PostalCode>1010</PostalCode>
<Country isoCountryCode="NZ">New Zealand</Country>
</PostalAddress>
<Email>mike.brady@unimarket.com</Email>
</Address>
</ShipTo>The Address addressID attribute is a unique identifier for the ShipTo location in Unimarket.
The Name element is the name assigned to the location.
The PostalAddress element includes multiple elements relating to the address.
The DeliverTo element will show the Attention field value selected during checkout. By default this is the Buyers name.
The Street element can be repeated up to 3 times and contains information about the street address.
The City element contains the city.
The State element contains the state or region.
The PostalCode element contains the post or zip code.
The Country element contains the country and the isoCountryCode attribute is the ISO country code.
The Email element contains the email address for the Buyer.
Note: This is the same detail that appears in the OrderRequestHeader element. Some systems might need this information at item level.
Shipping
This is the item level Shipping amount. The element will be included even when there is no charge.
<Shipping>
<Money currency="NZD">0.00</Money>
<Description xml:lang="en">Standard Delivery</Description>
</Shipping>
Tax
This is the Tax information for the item.
<Tax>
<Money currency="NZD">0.15</Money>
<Description xml:lang="en">NZ GST</Description>
<TaxDetail category="GST" percentageRate="15.00" purpose="tax">
<TaxableAmount>
<Money currency="NZD">1.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">0.15</Money>
</TaxAmount>
<Description xml:lang="en">NZ GST</Description>
</TaxDetail>
</Tax>The Money element total amount of tax for the item.
The Description element is the description of the tax being applied.
The category attribute is the type of tax that is being applied.
The percentageRate attribute is the tax rate being applied.
The purpose attribute indicates which part of the order is included in the tax calculation. For items on the order this will be "tax".
The TaxableAmount element is the subtotal amount excluding tax for the item.
The TaxAmount element is the amount of tax for the TaxableAmount.
Note: There is a TaxDetail element for each purpose.
Comments
The Comments element is where any item level notes are included.
<Comments>For Mike</Comments>
Complete Basic Order Example
<?xml version="1.0" encoding="UTF-8"?>
<cXML payloadID="dc61a74d-82ac-4a87-8b83-6e757edd7f85" timestamp="2020-11-16T12:17:51.945+13:00" version="1.2.021" xml:lang="en">
<Header>
<From>
<Credential domain="">
<Identity/>
</Credential>
</From>
<To>
<Credential domain="">
<Identity/>
</Credential>
</To>
<Sender>
<Credential domain="">
<Identity/>
<SharedSecret/>
</Credential>
<UserAgent>unimarket</UserAgent>
</Sender>
</Header>
<Request deploymentMode="test">
<OrderRequest>
<OrderRequestHeader orderDate="2020-11-16T12:17:51.124+13:00" orderID="102" orderType="regular" type="new">
<Total>
<Money currency="NZD">5.75</Money>
</Total>
<ShipTo>
<Address addressID="101" isoCountryCode="NZ">
<Name xml:lang="en">Branch Location</Name>
<PostalAddress>
<DeliverTo>Mike Brady</DeliverTo>
<Street>456 Something Drive</Street>
<City>Auckland</City>
<State/>
<PostalCode>1010</PostalCode>
<Country isoCountryCode="NZ">New Zealand</Country>
</PostalAddress>
<Email>mike.brady@unimarket.com</Email>
</Address>
</ShipTo>
<BillTo>
<Address addressID="001" isoCountryCode="NZ">
<Name xml:lang="en">Head Office</Name>
<PostalAddress>
<Street>123 Something Street</Street>
<City>Auckland</City>
<State/>
<PostalCode>1010</PostalCode>
<Country isoCountryCode="NZ">New Zealand</Country>
</PostalAddress>
<Email>mike.brady@unimarket.com</Email>
</Address>
</BillTo>
<Shipping>
<Money currency="NZD">0.00</Money>
<Description xml:lang="en">Standard Delivery</Description>
</Shipping>
<Tax>
<Money currency="NZD">0.75</Money>
<Description xml:lang="en">NZ GST</Description>
<TaxDetail category="GST" percentageRate="15.00" purpose="shippingTax">
<TaxableAmount>
<Money currency="NZD">0.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">0.00</Money>
</TaxAmount>
<Description xml:lang="en">NZ GST</Description>
</TaxDetail>
<TaxDetail category="GST" percentageRate="15.00" purpose="tax">
<TaxableAmount>
<Money currency="NZD">5.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">0.75</Money>
</TaxAmount>
<Description xml:lang="en">NZ GST</Description>
</TaxDetail>
</Tax>
<Contact role="buyer">
<Name xml:lang="en">Mike Brady</Name>
<Email>mike.brady@unimarket.com</Email>
</Contact>
<Extrinsic name="buyer-credential">
<Credential domain="unimarket-user">
<Identity>mike.brady@unimarket.com</Identity>
</Credential>
</Extrinsic>
<Extrinsic name="shippingNote"/>
<Extrinsic name="requisition-created-date">2020-11-16T12:17:51.055+13:00</Extrinsic>
<Extrinsic name="organisation">Mike Test Environment</Extrinsic>
<Extrinsic name="organisation-unit">Testing</Extrinsic>
<Extrinsic name="is-retrofit-order">no</Extrinsic>
<Extrinsic name="order-source-type">DEFAULT</Extrinsic>
<Extrinsic name="requisition-source-type">DEFAULT</Extrinsic>
</OrderRequestHeader>
<ItemOut lineNumber="1" quantity="1">
<ItemID>
<SupplierPartID>1010003</SupplierPartID>
<SupplierPartAuxiliaryID/>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="NZD">1.00</Money>
</UnitPrice>
<Description xml:lang="en">Product Code 10003</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">44000000</Classification>
<ManufacturerName xml:lang="en">Description 10003</ManufacturerName>
</ItemDetail>
<SupplierID domain="external-id">TestVendorID</SupplierID>
<ShipTo>
<Address addressID="101" isoCountryCode="NZ">
<Name xml:lang="en">Branch Location</Name>
<PostalAddress>
<DeliverTo>Mike Brady</DeliverTo>
<Street>456 Something Drive</Street>
<City>Auckland</City>
<State/>
<PostalCode>1010</PostalCode>
<Country isoCountryCode="NZ">New Zealand</Country>
</PostalAddress>
<Email>mike.brady@unimarket.com</Email>
</Address>
</ShipTo>
<Shipping>
<Money currency="NZD">0.00</Money>
<Description xml:lang="en"/>
</Shipping>
<Tax>
<Money currency="NZD">0.15</Money>
<Description xml:lang="en">NZ GST</Description>
<TaxDetail category="GST" percentageRate="15.00" purpose="tax">
<TaxableAmount>
<Money currency="NZD">1.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">0.15</Money>
</TaxAmount>
<Description xml:lang="en">NZ GST</Description>
</TaxDetail>
</Tax>
<Comments>For Mike</Comments>
</ItemOut>
<ItemOut lineNumber="2" quantity="4">
<ItemID>
<SupplierPartID>1010004</SupplierPartID>
<SupplierPartAuxiliaryID/>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="NZD">1.00</Money>
</UnitPrice>
<Description xml:lang="en">Product Code 10004</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">44000000</Classification>
<ManufacturerName xml:lang="en">Description 10004</ManufacturerName>
</ItemDetail>
<SupplierID domain="external-id">TestVendorID</SupplierID>
<ShipTo>
<Address addressID="101" isoCountryCode="NZ">
<Name xml:lang="en">Branch Location</Name>
<PostalAddress>
<DeliverTo>Mike Brady</DeliverTo>
<Street>456 Something Drive</Street>
<City>Auckland</City>
<State/>
<PostalCode>1010</PostalCode>
<Country isoCountryCode="NZ">New Zealand</Country>
</PostalAddress>
<Email>mike.brady@unimarket.com</Email>
</Address>
</ShipTo>
<Shipping>
<Money currency="NZD">0.00</Money>
<Description xml:lang="en"/>
</Shipping>
<Tax>
<Money currency="NZD">0.60</Money>
<Description xml:lang="en">NZ GST</Description>
<TaxDetail category="GST" percentageRate="15.00" purpose="tax">
<TaxableAmount>
<Money currency="NZD">4.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">0.60</Money>
</TaxAmount>
<Description xml:lang="en">NZ GST</Description>
</TaxDetail>
</Tax>
<Comments/>
</ItemOut>
</OrderRequest>
</Request>
</cXML>
Expected Response
The expected response back to the POST request is a cXML payload with a 200 Status code.
<?xml version="1.0" encoding="UTF-8"?>
<cXML>
<Response>
<Status code="200" text="OK">Purchase Order Processed Successfully</Status>
</Response>
</cXML>The Status code attribute should be in the 200 range. All others codes will be considered an error.
The Status element can include any information about the order.
Exchange Rates
When an order is sent to the supplier it will use the currency as per the supplier store. There are additional attributes included in each Money element to show the value in the currency set for the customer.
The OrderRequestHeader element contains an additional Extrinsic element showing the exchange rate.
<Extrinsic name="exchange-rate">
<ExchangeRate alternate-currency="NZD" currency="USD" user-specified="false">0.6930</ExchangeRate>
</Extrinsic>The ItemOut element also shows the exchange rate in the attributes for the Money elements in UnitPrice and Shipping.
<ItemOut lineNumber="1" quantity="5">
<ItemID>
<SupplierPartID>1000010</SupplierPartID>
<SupplierPartAuxiliaryID/>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money alternateAmount="1.443001" alternateCurrency="NZD" currency="USD">1.00</Money>
</UnitPrice>
<Description xml:lang="en">Product Code 10</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">44000000</Classification>
<ManufacturerName xml:lang="en">Description 10</ManufacturerName>
</ItemDetail>
<SupplierID domain="external-id">2</SupplierID>
<ShipTo>...</ShipTo>
<Shipping>
<Money alternateAmount="0.00" alternateCurrency="NZD" currency="USD">0.00</Money>
<Description xml:lang="en"/>
</Shipping>
<Tax>...</Tax>
<Comments/>
</ItemOut>The alternateCurrency attribute shows the currency code that is set for the Community.
The alternateAmount attribute shows the value in the currency set for the Community.
Note: More information on how exchange rates are managed is available here: Exchange Rates
Distributions
Distributions allow the Community to code their purchases to account codes. These can be included at an item level in the purchase order.
<Distribution>
<Accounting name="GLCode">
<AccountingSegment id="Auckland">
<Name xml:lang="en">Location</Name>
<Description xml:lang="en">Auckland Office</Description>
</AccountingSegment>
<AccountingSegment id="Blue">
<Name xml:lang="en">Team</Name>
<Description xml:lang="en">Team Blue</Description>
</AccountingSegment>
</Accounting>
<Charge>
<Money currency="NZD">12.00</Money>
</Charge>
</Distribution>The Distribution element contains Accounting and Charge elements. This is repeated for each account code used for the iteam.
The Accounting name attribute shows the account coding format that was used.
The AccountingSegment element is repeated for each part of the account code.
The AccountingSegment id attribute is the value for the account code part.
The Name element is the name of the account code part.
The Description element is the description of the value in the AccountingSegment id attribute.
The Charge element contains the value that has been assigned to the account code.
Example Distribution for an Item
This show an two account codes for the same line. The account code consists of two parts: Location and Team.
<ItemOut lineNumber="1" quantity="15">
<ItemID>
<SupplierPartID>1010005</SupplierPartID>
<SupplierPartAuxiliaryID/>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="NZD">1.00</Money>
</UnitPrice>
<Description xml:lang="en">Product Code 10005</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">44000000</Classification>
<ManufacturerName xml:lang="en">Description 10005</ManufacturerName>
</ItemDetail>
<SupplierID domain="external-id">TestVendorID</SupplierID>
<ShipTo>...</ShipTo>
<Shipping>...</Shipping>
<Tax>...</Tax>
<Distribution>
<Accounting name="GLCode">
<AccountingSegment id="Auckland">
<Name xml:lang="en">Location</Name>
<Description xml:lang="en">Auckland Office</Description>
</AccountingSegment>
<AccountingSegment id="Blue">
<Name xml:lang="en">Team</Name>
<Description xml:lang="en">Team Blue</Description>
</AccountingSegment>
</Accounting>
<Charge>
<Money currency="NZD">12.00</Money>
</Charge>
</Distribution>
<Distribution>
<Accounting name="GLCode">
<AccountingSegment id="Wellington">
<Name xml:lang="en">Location</Name>
<Description xml:lang="en">Wellington Office</Description>
</AccountingSegment>
<AccountingSegment id="Red">
<Name xml:lang="en">Team</Name>
<Description xml:lang="en">Team Red</Description>
</AccountingSegment>
</Accounting>
<Charge>
<Money currency="NZD">3.00</Money>
</Charge>
</Distribution>
<Comments/>
</ItemOut>
Distribution Extrinsics
Distribution Extrinsics can be included in the ItemDetail element to show the percentage assigned for each account code for the item.
The Extrinsic element has a name attribute of "unimarket-distribution-details" and will include repeating extrinsic elements for each account code for the item.
The account code can be identified in the Extrinsic name attribute with the format:
"Account Code Format":"Account Code"
In this example it's: "GLCode:Auckland-Blue" or "GLCode:Wellington-Red"
The associated percentage can be found in the contained Extrinsic element.
<ItemOut lineNumber="1" quantity="15">
<ItemID>
<SupplierPartID>1010005</SupplierPartID>
<SupplierPartAuxiliaryID/>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="NZD">1.00</Money>
</UnitPrice>
<Description xml:lang="en">Product Code 10005</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">44000000</Classification>
<ManufacturerName xml:lang="en">Description 10005</ManufacturerName>
<Extrinsic name="unimarket-distribution-details">
<Extrinsic name="GLCode:Auckland-Blue">
<Extrinsic name="percentage">80.00000000</Extrinsic>
</Extrinsic>
<Extrinsic name="GLCode:Wellington-Red">
<Extrinsic name="percentage">20.00000000</Extrinsic>
</Extrinsic>
</Extrinsic>
</ItemDetail>
<SupplierID domain="external-id">TestVendorID</SupplierID>
<ShipTo>...</ShipTo>
<Shipping>...</Shipping>
<Tax>...</Tax>
<Distribution>...</Distribution>
<Distribution>...</Distribution>
<Comments/>
</ItemOut>
Common cXML Elements
The tables show some examples on where to find common fields used from the Header and Item levels.
Header Level
Detail Path Example Environment cXML/Request/@deploymentMode test Order Date cXML/Request/OrderRequest/OrderRequestHeader/@orderDate 2020-11-16T12:17:51.124+13:00 Order Number cXML/Request/OrderRequest/OrderRequestHeader/@orderID 102 Order Status cXML/Request/OrderRequest/OrderRequestHeader/@type new Ship To ID cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/@addressID 101 Ship To Name cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/Name Branch Location Deliver To / Attn To cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/DeliverTo Mike Brady Street cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/Street[1]
cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/Street[2]
cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/Street[3]
456 Something Drive City cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/City Auckland State / Region cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/State Post / ZIP Code cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/PostalCode 1010 Country cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/Country New Zealand Buyer Name cXML/Request/OrderRequest/OrderRequestHeader/Contact[@role="buyer"]/Name Mike Brady Buyer Email cXML/Request/OrderRequest/OrderRequestHeader/Contact[@role="buyer"]/Email mike.brady@unimarket.com Order Total cXML/Request/OrderRequest/OrderRequestHeader/Total/Money 5.75 Shipping Total cXML/Request/OrderRequest/OrderRequestHeader/Shipping/Money 0.00 Tax Total cXML/Request/OrderRequest/OrderRequestHeader/Tax/Money 0.75 Order Note cXML/Request/OrderRequest/OrderRequestHeader/Extrinsic[@name="shippingNote"] Item Level
Detail Path Example Line Number cXML/Request/OrderRequest/ItemOut[*]/@lineNumber 1 Quantity cXML/Request/OrderRequest/ItemOut[*]/@quantity 1 Item Code cXML/Request/OrderRequest/ItemOut[*]/ItemID/SupplierPartID 1010003 Item Description cXML/Request/OrderRequest/ItemOut[*]/ItemDetail/Description Product Code 10003 Unit of Measure cXML/Request/OrderRequest/ItemOut[*]/ItemDetail/UnitOfMeasure EA UNSPSC / Product Category cXML/Request/OrderRequest/ItemOut[*]/ItemDetail/Classification 44000000 Unit Price cXML/Request/OrderRequest/ItemOut[*]/ItemDetail/UnitPrice/Money 1.00 Tax cXML/Request/OrderRequest/ItemOut[*]/Tax/Money 0.15 Item Note cXML/Request/OrderRequest/ItemOut[*]/Comments For Mike
Additional Information
Example Downloadable Files
-
Receiving Integration (order-received-request)
Overview
The order-received-request integration is used to communicate received PO line quantities between Unimarket and an external system. When a user receives PO lines within Unimarket the order-received-request will update the external system (such as an ERP system) with a received quantity. The order-received-request is one of the 3 commonly used integration points with ERP or Finance systems. These include Purchase Orders, Receipts (order-received-request) and Invoices.
Technical Documentation
Technical documentation and examples relating to the full list of Unimarket webservice interfaces can be found below:
-
Accounting Transaction Request (General Ledger Integration)
Overview
The Account Transaction Request/Response integration (General Ledger (GL) integration) is used to send accounting transactions from Unimarket to an external system such as an FMIS/ERP. Transactions are generated when orders are created, receipted and then invoiced.
For an overview of the GL Module functionality and business related scenarios see General Ledger Module.
Setting up GL Integration
In order to start sending test messages to an external system the community needs to configure the Ledger within Unimarket to reflect the ledger structure in the external system. This determines which accounts get updated when orders are created, received and invoiced. There are 3 accounts which are commonly configured (but it does differ) - 1 for Order Amounts, 1 for Received Amounts and 1 for Invoiced Amounts.
Setting Up Accounts
- Name - As noted above, the Name of the Account e.g. Estimate, GRNI or simply the Account Number.
- Account Code - The GL account code that is posted to.
- Type - Determines the type of account:
- Liability: Estimate, GRNI, AP are all Liability accounts.
- Expense: Used for Shipping.
- Asset: (Not used)
- Equity: (Not used)
- Income: (Not used)
Configure Posting Manager
The Posting Manager should be configured after the accounts have been setup. It determines the process of updating the accounts and again it needs to reflect the accounting process used with the ERP system.
- Estimate (also know as Commitments): For the Estimate select the Account (setup above) where your commitments are coded when an order is created in the system.
- GRNI Account (Goods Received Not Invoiced): For the GRNI select the Account where received order item amount is coded when a buyer receives. The may be the same or different to the Estimate Account. If it is the same then the Estimate account is adjusted to reflect the received amount when order items are received, if it is different then the amount is backed out of the Estimate account and the received amount is updated in a separate GRNI account. The process all depends on how the accounting is completed in the ERP system.
- AP (Accounts Payable): Select the account where invoice amount is coded when the invoice is matched. Note that this is optional and some organizations choose not to send AP transactions via the GL integration - they just handle the process in their ERP system.
Note: If a separate shipping account is specified then all header level shipping charges will get posted to the specified account. If not shipping account is specified then the system will spread any header level charges across all the lines. Technical
Technical details relating to the integration can be found by going to Integration > General.
-
Work Orders
Overview
This is used to send a Work Order to Unimarket from an external work order system.
- Work Order Name: 255 characters
- Work Order Description: 2000 characters
- Dates: These are used to determine if the WO is in a Pending or Active state
- State: Pending, Active, Cancelled, Expired.
- Members: These are the users in Unimarket that can purchase from the WO. The Identity must be a valid username in Unimarket.
Work Order Request
<?xml version="1.0" encoding="UTF-8"?>
<create-work-order-request xmlns="http://www.unimarket.com/schema/unimarket-ws-1.1" work-order-number="WO0033">
<name>My Work Order</name>
<description>Blah blah</description>
<start-date>2020-01-01T10:30:00Z</start-date>
<end-date>2021-01-01T10:30:00Z</end-date>
<state>PENDING</state>
<owner-ref identity="user1" domain="UNIMARKET_USERNAME_DOMAIN"/>
<members>
<member-ref identity="user2" domain="UNIMARKET_USERNAME_DOMAIN"/>
</members>
</create-work-order-request>Work Order Response
<?xml version="1.0" encoding="UTF-8"?>
<create-work-order-response xmlns="http://www.unimarket.com/schema/unimarket-ws-1.1">
<response code="OK"/>
</create-work-order-response>Update Work Order Request
This is used to send a work order details update to Unimarket from an external work order system.
Update Work Order Request
<?xml version="1.0" encoding="UTF-8"?>
<update-work-order-request xmlns="http://www.unimarket.com/schema/unimarket-ws-1.1" work-order-number="WO0033">
<name>My Work Order - Updated</name>
<description>Blah blah - Updated</description>
<start-date>2020-02-01T10:30:00Z</start-date>
<end-date>2021-02-01T10:30:00Z</end-date>
<state>CANCELLED</state>
<owner-ref identity="user1" domain="UNIMARKET_USERNAME_DOMAIN"/>
<members>
<member-ref identity="user3" domain="UNIMARKET_USERNAME_DOMAIN"/>
</members>
</update-work-order-request>Update Work Order Response
<?xml version="1.0" encoding="UTF-8"?>
<update-work-order-response xmlns="http://www.unimarket.com/schema/unimarket-ws-1.1">
<response code="OK"/>
</update-work-order-response>