Versions Compared

Old Version 4

changes.mady.by.user Aaron o'Donnell

Saved on

compared with

New Version Current

changes.mady.by.user Cor Zijlstra

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Message Exchange

Onetrail TPN™ is providing services in order to trade electronically by using RESTAPI's. This page describes the specifications for these REST servicesAPI's. Onetrail API's requires no 'Pulling' of messages. Choosing this communication, Suppliers and Buyers can POST messages to a Onetrail endpoint, and Onetrail will provide responses back to customer endpoint. It's not yet supported to collect messages from a Onetrail endpoint via REST.

Scope

The Onetrail TPN™ REST Message exchange API for Sellers supports receiving orders, sending order status, despatch advice and invoice messages as well as handling of real-time price and availability requests. The provisioning of product-, price-, and stock data (batch) is not supported via REST, but via SOAP, FTP or email only.

The Onetrail TPN™ REST Message exchange API for Buyers supports the real time price and availabilitysending orders.

Design

The Onetrail TPN™ REST ODE Service Message exchange API for Sellers is payload agnostic, meaning the service is generic for all order related message types and thus not aware of the content of the message. Message validation (schema validation in case of XML) needs to be performed outside of the service. At this moment Onetrail TPN™ is not supporting JSON formatted messages, but only The API supports JSON, XML and EDIFACT.

The Onetrail TPN™ REST Message exchange API Service for Buyers is payload agnostic and supports JSON and XML.

Message definitions

Onetrail TPN™ supports JSON (P&A only), XML and EDIFACT for the REST servicesMessage exchange API. The message documentation and definitions can be found here: Message Types

Communication

From Seller to Onetrail

...

https://$base_url/exchange/rest/tradingpartner/{toGLN}/msgtype/{msgType}/msg/{msgID}

...

  • Method: POST
  • Body: XML or EDIFACT content

From Onetrail

...

to Seller

This API needs to be implemented by the seller.

https://$base_url/tradingpartner/{fromGLN}/msgtype/{msgType}/msg/{msgID}

Example: https://testrest.seller.com/tradingpartner/8714253023366/msgtype/Order/msg/OrdReqTest001

  • base_url:
    • Acceptance: to be provided by the Seller
    • Production: to be provided by the Seller
  • Variables:
    • {fromGLN} = GLN for the buyer sending the message
    • {msgType} = Order
    • {msgID} = the unique messageID
  • Method: POST
  • Body: XML, JSON or EDIFACT content

From Buyer

...

to

...

Onetrail

...

...

  • RESTful services have a smaller footprint than SOAP, Parsing JSON is less computationally heavy and memory intensive then XML, however we can still support XML as well.
  • Improved efficiency allows us to support bulk requests as well as single requests, this will allow buyers to retrieve multiple items with 1 request rather than multiple single requests.
  • The health check will allow you to monitor the availability and uptime of the service.

Syntax

https://$base_url/pdeexchange/rest/v5tradingpartner/products?{SellerGLNtoGLN}&/msgtype/{PDINumbermsgType}&/msg/{SellerVPN}&{GTIN}&{Quantity}&{BidID}msgID}

Example: httphttps://prd-tpn-pna-5.cloudacc-rest.onetrail.net:8088/pdeexchange/rest/v5tradingpartner/products?SellerGLN=8714253023236&PDINumber=C7978A8714253023236/msgtype/Order/msg/OrdReqTest001

  • base_url:
    • Acceptance: acc-rest.onetrail.net
    • Production: restprd-tpn-pna-5.cloud.onetrail.net:8088
  • Variables:
    • SellerGLN (multiple ; separated){toGLN} = provide the GLN from for the Seller
    • PDINumber = Onetrail TPN™ PDI number
    • SellerVPN = Seller Vendor part number
    • GTIN = Seller Global Trade Item Number (EAN)
    • Quantity = Quantity for which you want the price and availability
    • BidID = Contract ID for the price of a contract product
    Remarks:
  • At least one of the product numbers is mandatory;

  • Can now handle bulk requests as well as the usual single requests. (For bulk requests the URL is:  https://rest.onetrail.net/productApi/v1/products/bulk

  • Uses basic authentication and user managed in the TPN Manager.

    • It's now RESTful, no longer SOAP.
  • Request Types:

    • In previous versions of Onetrail PnA, HTTP-GET, REST and SOAP requests were all valid request types. With the current version we've streamlined to accept REST requests only. There are many reasons why, but the main benefits of REST over other request types are as mentioned above: It has a smaller footprint that SOAP, can handle JSON and XML as well as other data types, it's also generally faster, more efficient and requires less bandwidth.

  • Response:
    • If no Seller GLN is specified, the response will contain all products from Sellers that matches the Request of which the buyer has prices
  • Remarks:
    • The JSON response is based on the PRD version 3.1 output
    • The result can contain multiple Onetrail PDI items. In that case the response will contain n-times an ns2:product element
    • The result can contain multiple Seller items per Onetrail PDI item. In that case the response will contain n-time an ns2:sellerInfo element
  • Method: GET
  • Body: JSON/XML content

  • Authentication:

    • With our update to PnA5 also comes new improved authentication and user management. Every buyer and seller who is set up in the Onetrail TPN Manager will automatically have the rights to submit PnA requests. Previously Onetrail required Buyer credentials for a specific seller, but now it's not necessary.

From Buyer to Onetrail TPN™ (Order)

    • , or use fixed value unknown otherwise
    • {msgType} = Order
    • {msgID} = the unique messageID (Can be used for duplicate checking)
  • Method: POST
  • Body: XML, EDIFACT or JSON content
    • for JSON, please contact your consultant for additional requirements like namespaces.

From Onetrail to Buyer

The buyer needs to implement a REST API that matches the below definition.

https://$base_url/exchange/rest/tradingpartner/{toGLN}/msgtype/{msgType}/msg/{msgID}

Example: https://acc-rest.onetrailbuyer.netcom/exchange/rest/tradingpartner/87142530232368714253023366/msgtype/OrderOrderResponse/msg/OrdReqTest001OrdRspTest001

  • Variables:
    • {toGLN} = provide the GLN for the Sellerbuyer, or use fixed value unknown otherwise
    • {msgType} = OrderOrderResponse, DespatchAdvice or Invoice
    • {msgID} = the unique messageID (Can be used for duplicate checking)
  • Method: POST
  • Body: XML or EDIFACT content

Security

The REST service uses basic authentication and TLS 1.2 security settings. Credentials will be provided by Onetrail., Seller or Buyer.

Downloads

Please find below the OpenApi definition,

Download: MessageExchangeAPI.json