Sending POX (Plain Old XML) Messages to Unimarket

  • Updated

POX (Plain Old XML) is a simplified protocol used for communicating with Unimarket when full SOAP overhead is not required. It is primarily used for administrative and data-sync integrations like user provisioning, budget checks, and approval configurations.

 

The POX Message Structure

Unlike standard cXML, which includes its own authentication headers, POX messages must be wrapped in a specific pox-envelope. This envelope contains two main parts:

  • Authentication Header: Contains your tenant identifier, username, and shared secret.

  • Request Body: Contains the actual uXML request (e.g., a budget check or user update).

 

Implementation Guide

To get started with POX integration, follow these four steps:

Step 1: Obtain Credentials

Contact Unimarket to receive the following mandatory security details:

  • Tenant Identifier: Your unique community or supplier ID.

  • Integration Username: The specific service account name.

  • Shared Secret: The secure password for the integration.

 

Step 2: Identify the Request Type

Determine which uXML element you need to send. Common top-level elements include:

  • validate-account-code-request

  • user-detail-request

  • approval-configuration-request

 

Step 3: Construct the Envelope

Wrap your request and credentials in the pox-envelope.

 

POX Envelope Example:

<?xml version="1.0" encoding="UTF-8"?>
<u:pox-envelope xmlns:u="http://www.unimarket.com/schema/unimarket-ws">
    <u:header>
        <u:authentication>
            <!-- Unique identifier of the Unimarket tenant (community or supplier) -->
            <u:tenant-ref identity="7f251a49-bd4d-4527-b234-d3d4a3e14e1b" domain="UNIMARKET_ID_DOMAIN"/>
            <u:sender>
                <!-- Unique identifier of the Unimarket integration user -->
                <u:user-ref identity="6cd91828-a4f4-4b70-b9ac-5f6f4d9e4082" domain="UNIMARKET_USERNAME_DOMAIN"/>
                <!-- Password used to authenticate the request -->
                <u:shared-secret>password1</u:shared-secret>
            </u:sender>
        </u:authentication>
    </u:header>
    <u:body>
        <create-quote-request xmlns='http://www.unimarket.com/schema/unimarket-ws'>
            <header>
                <to>
                    <!-- Unique Unimarket username of the user the quote is for -->
                    <user-ref identity='user1'/>
                    <!-- Unique Unimarket code of the user's community -->
                    <tenant-ref identity='AACC'/>
                </to>
                <summary>summary value</summary>
                <reference-code>quote ref value</reference-code>
                <expiry>2009-08-01T15:30:00</expiry>
            </header>
            <!-- e.g. line with tax -->
            <line quantity="2">
                <code>product code</code>
                <name>name value</name>
                <description>desc value</description>
                <unit-of-measure unit="EA"/>
                <unit-price iso-currency-code="USD">50.00</unit-price>
                <subtotal iso-currency-code="USD">100.00</subtotal>
                <tax iso-currency-code="USD">15</tax>
                <total iso-currency-code="USD">115</total>
            </line>
        </create-quote-request>
    </u:body>
</u:pox-envelope>

 

Step 4: Submit to the Endpoint

Send your message as an HTTPS POST to the applicable regional URL.

LocationSupplier EndpointCommunity Endpoint
United Stateshttps://supplier.unimarket.com/wshttps://<code\>.unimarket.com/ws
New Zealandhttps://supplier.unimarket.co.nz/wshttps://<code\>.unimarket.co.nz/ws
Australiahttps://supplier.unimarket.com.au/wshttps://<code\>.unimarket.com.au/ws

 

Important Distinction: cXML vs. POX

It is important to note that cXML messages (such as OrderRequest or InvoiceDetailRequest) do not require a POX envelope. These messages already contain an internal <Header> with <Sender> credentials. So they can be posted directly to the endpoint, without the pox-envelope wrapper.