Detailed information¶

Certificate and field signing¶

We use the WS-Security extension to SOAP in conjunction with HTTPS to provide signing and encryption of the message between endpoints.

Although WS-Security can provide both encryption and signing, we are only using the signing part, as the link is already encrypted via HTTPS.

Once the X.509 certificate has been generated, you’ll need to provide uswith the Public Key Certificate and this will be installed into the test platform to allow access.

It is recommended that a certificate is generated which has a 5-year expiry date. It is recommended that the same private key is used when generating a certificate with a renewed expiry date.

Instructions submitted into our live platform with a valid signature and correctly formatted are accepted automatically for fulfilment as a contractually binding order subject to our normal terms and conditions.

Testing and acceptance criteria¶

Before you can access our live service, we run through an acceptance test script with you to ensure that your requests are submitted correctly and your code can handle error responses robustly.

All acceptance tests must be performed on the test environment before moving onto the production environment. Although we have our own test plan, you should ensure that you complete your own testing to meet your own requirements as well.

Our test plan is a simple Acceptance Criteria as a set of statements, each with a clear pass/fail result, that specify both functional and non-functional requirements as follows:

It is expected that ALL order submissions, responses and errors are tested and handed correctly before going live. If tests are not performed then Nuvias UC have no confidence that the reseller can handle the different responses and errors in a live production environment and therefore support cannot be provided for in-life issues. Nuvias UC will request proof that these tests have been completed before moving a reseller into the production environment.
It is imperative that the resellers platform can support the order process flow that Nuvias UC has implemented and outlined in this document.
If there are any edge cases that do not yield the expected results, then these can be shared with our Professional Services development team for investigation and support prior to going live.

Item SKUs¶

The Stock Keeping Unit (SKU), is a number assigned to a product by our vendors (sometimes referred to as an MPN or Manufacturer Part Number) and which we use for stock-keeping purposes and internal operations. SKU codes are assigned to a product wherever it is sold, remaining a constant throughout and made available to customers. Where possible we try and ensure that the SKU we use matches the MPN to make life simple for everyone. We also have our own products and services which you’ll find are in a specific format and always start “XX-SIP-“.

It is therefore imperative that a customer has an agreed a full list of SKU codes that they are allowed to use and are expected to use. Without a pre-agreed list of SKU codes orders will fail when submitted if they are not associated with the customer account. This is typically agreed as part of a price book with your account manager and a full list of SKUs and their details can be obtained through your account manager.

It is important that these codes and how they should be used are agreed with us prior to any test or production orders being submitted. There are occasionally discrepancies between Sandbox and Live – this reflects the timescales of the data update to Sandbox which occurs from time to time.

We are not able to support custom SKUs specified by customers. You must use the SKU we provide.

SKU Codes Fields¶

These are standard SKU codes are typically associated with individual standalone products. All existing Reseller SKU Codes used over the Phone / Email or via the WebStore will also be available through the Reseller API.

SKU Codes can take many formats and typically relate to the underlying product or service.

An example SKU Code is 2200-46162-025.

SKU Attributes¶

Note that certain SKU codes are utilized for ordering specific Nuvias UC services (e.g. firmware upgrades or provisioning), or add-on product licensing, which may or may not have a chargeable element to the end reseller. These must be included when placing orders and at this time can include:

Licensing SKU – typically device and reseller specific. Resellers are aware of the licensing required for each device (e.g. VQMON).
Provisioning SKU – usually a single SKU code to indicate Provisioning is required so that it generates the associated charge. Note that there are multiple provisioning services available from Nuvias UC, not all of which are appropriate to all products. You should confirm with your account manager which provisioning SKU you should use for which scenario.

These above items would then generate a “Provisioning Instruction” to the warehouse for configuration.

An example Attribute SKU – UD-SIP-SER-PRV-PH

These attribute SKUs should then be added as a line item with the required quantity in the SubmitOrderForm object.

SKU Attributes

Note that we also support Vendor “virtual SKUs” or virtual bundles, where a number of items are bundled together, sometimes with a service. These will be provided as part of your normal list of SKUs in your price book. However, when you add these to your order, even though you only add a single SKU, internally we represent these as multiple items of which has its own SKU. As a result, your invoice will show a group of items with a header corresponding to the virtual bundle and a number of items underneath.

For more information on virtual bundles, speak with your account manager.

Non-SKU Attributes¶

You can use the following fields to send information to the Nuvias UC warehouse so that the orders are processed with the correct configuration instructions and they are successfully delivered to the end customer.

deliveryInstructions - the text in here is passed to our couriers and can be used by the delivery driver. Note that for many of our couriers this space is extremely limited and so we recommend that you do not use more than 46 characters. All of our delivery messages are prepended with a “Do not leave with neighbour. Do not leave in a safe place.” message. If you are unsure of how to format your message our customer services team can assist with common codes and shortcuts used by our couriers.
provisioningInstructions - used by the warehouse team to configure devices as part of a pre-staging configuration service. The configuration service must be set up by our team ahead of any orders, so you must contact the customer services team prior to using this field. They will provide details of what to place in here for any given configuration you wish to use.
configurationURL - Similar to the above, our customer services team can assist you in what to place in this field.

Order submission scenarios¶

When submitting orders via the API it is important that certain information related to the SKU attributes & non-SKU attributes is supplied in a defined manner. This will allow the order to successfully pass through each Nuvias UC distribution process.

The following scenarios highlight how orders should be placed with Nuvias UC.

Product SKU Orders¶

Define the product item SKUs and the required quantity
For delivery please provide one valid contact name and address per order
A valid PO number is required for the order

Consider the below items ordered for the above scenario:

Sample Item

Below is an example XML request for the above order scenario:

Request

<ns2:submitOrder xmlns:ns2="urn:transactions_10.reseller.siphon.com" xmlns:ns3="urn:error.transactions_10.reseller.siphon.com">
    <submitOrderForm>
        <purchaseOrderID>PO123451</purchaseOrderID>
        <shipAddress>
            <attentionName>John Smith on 07943 123 001</attentionName>
            <companyName>Taylors Ltd</companyName>
            <addressLine1>Suite 3 Goose Court</addressLine1>
            <addressLine2>9 Blacksmith Street</addressLine2>
            <addressTown>London</addressTown>
            <addressCounty>London</addressCounty>
            <addressPostalCode>SW1 1XS</addressPostalCode>
        </shipAddress>
        <shippingMethod>UK Standard Next Day Delivery</shippingMethod>
        <shippingDate>2016-09-27T13:04:31.688+01:00</shippingDate>
        <deliveryInstructions>Main entrance at rear</deliveryInstructions>
        <insertType>TYPE_1</insertType>
        <submitOrderItemList>
            <partNumber>2200-46162-025</partNumber>
            <quantityRequired>5.0</quantityRequired>
        </submitOrderItemList>
    </submitOrderForm>
</ns2:submitOrder>

Response

<ns2:submitOrderResponse xmlns:ns2="urn:transactions_10.reseller.siphon.com" xmlns:ns3="urn:error.transactions_10.reseller.siphon.com">
    <orderID>SO52315</orderID>
</ns2:submitOrderResponse>

Product SKU and Ancillary Items Orders¶

Define the product item SKUs and the required quantity
Define any additional items associated with each product item and the required quantity – e.g. PSUs
Define any additional licenses associated with each product item – the quantity must be the same as the product items being ordered, e.g. Polycom VQMON Software
For delivery please provide one valid contact name and address per order
A valid PO number is required for the order

Consider the below items ordered for the above scenario:

Sample Items

Below is an example XML request for the above order scenario:

Request

<ns2:submitOrder xmlns:ns2="urn:transactions_10.reseller.siphon.com" xmlns:ns3="urn:error.transactions_10.reseller.siphon.com">
    <submitOrderForm>
        <purchaseOrderID>PO123452</purchaseOrderID>
        <shipAddress>
            <attentionName>John Smith on 07943 123 001</attentionName>
            <companyName>Taylors Ltd</companyName>
            <addressLine1>Suite 3 Goose Court</addressLine1>
            <addressLine2>9 Blacksmith Street</addressLine2>
            <addressTown>London</addressTown>
            <addressCounty>London</addressCounty>
            <addressPostalCode>SW1 1XS</addressPostalCode>
        </shipAddress>
        <shippingMethod>UK Standard Next Day Delivery</shippingMethod>
        <shippingDate>2016-09-27T13:23:38.865+01:00</shippingDate>
        <deliveryInstructions>Main entrance at rear</deliveryInstructions>
        <insertType>TYPE_1</insertType>
        <submitOrderItemList>
            <partNumber>2200-46162-025</partNumber>
            <quantityRequired>5.0</quantityRequired>
        </submitOrderItemList>
        <submitOrderItemList>
            <partNumber>2200-46157-025</partNumber>
            <quantityRequired>3.0</quantityRequired>
        </submitOrderItemList>
        <submitOrderItemList>
            <partNumber>2200-46175-102</partNumber>
            <quantityRequired>3.0</quantityRequired>
        </submitOrderItemList>
        <submitOrderItemList>
            <partNumber>5150-47891-001</partNumber>
            <quantityRequired>8.0</quantityRequired>
        </submitOrderItemList>
    </submitOrderForm>
</ns2:submitOrder>

Product SKU, Ancillary Items and Provisioning Orders¶

Define the product item SKUs and the required quantity
Define any additional items associated with each product item and the required quantity – e.g. PSUs
Define any additional licenses associated with each product item – the quantity must be the same as the product items being ordered, e.g. Polycom VQMON Software
For provisioning include the appropriate Provisioning SKU – the quantity must be the same as the product items being ordered
It is recommended that Nuvias UC use an agreed default URL associated to each product item SKU
- Any updates to the provisioning URL must be agreed in advance and provided in writing by the reseller
For delivery please provide one valid contact name and address per order
A valid PO number is required for the order

These above items would then generate a Sales Order in Netsuite. From this order a “Provisioning Instruction” is sent to to the warehouse for configuration. This “Provisioning Instruction” will be the pre-agreed URL for each product item included in the order.

Consider the below items ordered for the above scenario:

Sample Items

Below is an example XML request for the above order scenario:

Request

<ns2:submitOrder xmlns:ns2="urn:transactions_10.reseller.siphon.com" xmlns:ns3="urn:error.transactions_10.reseller.siphon.com">
    <submitOrderForm>
        <purchaseOrderID>PO123453</purchaseOrderID>
        <shipAddress>
            <attentionName>John Smith on 07943 123 001</attentionName>
            <companyName>Taylors Ltd</companyName>
            <addressLine1>Suite 3 Goose Court</addressLine1>
            <addressLine2>9 Blacksmith Street</addressLine2>
            <addressTown>London</addressTown>
            <addressCounty>London</addressCounty>
            <addressPostalCode>SW1 1XS</addressPostalCode>
        </shipAddress>
        <shippingMethod>UK Standard Next Day Delivery</shippingMethod>
        <shippingDate>2016-09-27T13:29:50.627+01:00</shippingDate>
        <deliveryInstructions>Main entrance at rear</deliveryInstructions>
        <insertType>TYPE_1</insertType>
        <submitOrderItemList>
            <partNumber>2200-46162-025</partNumber>
            <quantityRequired>5.0</quantityRequired>
        </submitOrderItemList>
        <submitOrderItemList>
            <partNumber>2200-46157-025</partNumber>
            <quantityRequired>3.0</quantityRequired>
        </submitOrderItemList>
        <submitOrderItemList>
            <partNumber>2200-46175-102</partNumber>
            <quantityRequired>3.0</quantityRequired>
        </submitOrderItemList>
        <submitOrderItemList>
            <partNumber>5150-47891-001</partNumber>
            <quantityRequired>8.0</quantityRequired>
        </submitOrderItemList>
        <submitOrderItemList>
            <partNumber>UD-SIP-SER-PRV-PH</partNumber>
            <quantityRequired>8.0</quantityRequired>
        </submitOrderItemList>
    </submitOrderForm>
</ns2:submitOrder>

Response

<ns2:submitOrderResponse xmlns:ns2="urn:transactions_10.reseller.siphon.com" xmlns:ns3="urn:error.transactions_10.reseller.siphon.com">
    <orderID>SO52317</orderID>
</ns2:submitOrderResponse>

Product SKU, Ancillary Items, Provisioning and Firmware Upgrade Orders¶

Define the product item SKUs and the required quantity
Define any additional items associated with each product item and the required quantity – e.g. PSUs
Define any additional licenses associated with each product item – the quantity must be the same as the product items being ordered, e.g. Polycom VQMON Software
For provisioning include the appropriate Provisioning SKU – the quantity must be the same as the product items being ordered
It is recommended that Nuvias UC use an agreed default URL associated to each product item SKU
- Any updates to the provisioning URL must be agreed in advance and provided in writing by the reseller
For firmware upgrade include the appropriate SKU or provisioning information – the quantity must be the same as the product items being ordered
It is recommended that Nuvias UC use an agreed default firmware associated to each product item SKU – updates to the firmware version must be agreed in advance and provided in writing by the reseller
- Any updates to the firmware version must be agreed in advance and provided in writing by the reseller
For delivery please provide one valid contact name and address per order
A valid PO number is required for the order

These above items would then generate a Sales Order in Netsuite. From this order a “Provisioning Instruction” is sent to to the warehouse for configuration. This “Provisioning Instruction” will be the pre-agreed URL & firmware version for each product item included in the order.

Consider the below items ordered for the above scenario:

Sample Items

Below is an example XML request for the above order scenario:

Request

<ns2:submitOrder xmlns:ns2="urn:transactions_10.reseller.siphon.com" xmlns:ns3="urn:error.transactions_10.reseller.siphon.com">
    <submitOrderForm>
        <purchaseOrderID>PO123454</purchaseOrderID>
        <shipAddress>
            <attentionName>John Smith on 07943 123 001</attentionName>
            <companyName>Taylors Ltd</companyName>
            <addressLine1>Suite 3 Goose Court</addressLine1>
            <addressLine2>9 Blacksmith Street</addressLine2>
            <addressTown>London</addressTown>
            <addressCounty>London</addressCounty>
            <addressPostalCode>SW1 1XS</addressPostalCode>
        </shipAddress>
        <shippingMethod>UK Standard Next Day Delivery</shippingMethod>
        <shippingDate>2016-09-27T13:30:15.948+01:00</shippingDate>
        <deliveryInstructions>Main entrance at rear</deliveryInstructions>
        <insertType>TYPE_1</insertType>
        <submitOrderItemList>
            <partNumber>2200-46162-025</partNumber>
            <quantityRequired>5.0</quantityRequired>
        </submitOrderItemList>
        <submitOrderItemList>
            <partNumber>2200-46157-025</partNumber>
            <quantityRequired>3.0</quantityRequired>
        </submitOrderItemList>
        <submitOrderItemList>
            <partNumber>2200-46175-102</partNumber>
            <quantityRequired>3.0</quantityRequired>
        </submitOrderItemList>
        <submitOrderItemList>
            <partNumber>5150-47891-001</partNumber>
            <quantityRequired>8.0</quantityRequired>
        </submitOrderItemList>
        <submitOrderItemList>
            <partNumber>UD-SIP-SER-PRV-ADV-PH</partNumber>
            <quantityRequired>8.0</quantityRequired>
        </submitOrderItemList>
    </submitOrderForm>
</ns2:submitOrder>

Response

<ns2:submitOrderResponse
xmlns:ns2="urn:transactions_10.reseller.siphon.com" xmlns:ns3="urn:error.transactions_10.reseller.siphon.com">
    <orderID>SO52318</orderID>
</ns2:submitOrderResponse>

Multiple Deliveries¶

All of the scenarios above assume there is only one delivery address. Each order must have a single delivery address per order. If more than one delivery address is required for any of the above scenarios, you must supply a separate order per address.

You can repeat the process for each of the scenarios above and simply select a separate delivery address for each order.