Order data transmission

from your system to TB.One

Definition

After generating sales in your system, may it be your own shopping cart system or sales on your marketplace, you might want to transfer these orders to the TB.One database for the purpose of forwarding them to the merchant who needs to do the shipping.

TB.One uses a specific XML format that we call “TB.Order” for order-transmission. The same format is used no matter if you are sending to or retrieving from TB.Ones REST API.

This format includes all relevant order data like

  • the point of sale/channel information (where did the order occur)
  • customers billing address
  • customers shipping address (can be identical with billing address)
  • ordered articles and services

Process

  1. Send your sales order by order to the TB.One REST API. Yes, that is one API call per order.
  2. When you post that REST call, TB.One will validate your data and will answer with a response in XML format you must handle.
    In case your order is successfully added to TB.One, the response will include the generated ID (TB_ID) for the new order. You should save this in your system for further referring to that order.

    • In case a catchable error occurs you will get a human readable error message as response.
      This may look like this:

      <?xml version=”1.0″ encoding=”UTF-8″?>

      <tradebyte>

      <state>

      Provided XML does not validate against tbORDER schema.

      </state>

      </tradebyte>

    • Any other case will result in a HTTP status code other than 200 and needs to be taken care of.
  3. Later – when the order has been handled within TB.One – you will be able to retrieve an order status message with tracking codes, cancellations or no-inventory-information. Retrieving order messages is explained here

Preconditions

  • You will need access to TB.One with REST-API credentials.
  • You can only send orders to TB.One containing articles that are known in your TB.One database.

Best Practise

  1. If any problems occure while transmitting an order to TB.One your system should mark that order as problem case, stop trying to transmit this order and inform someone from your team. After the problem is solved transmission can be retried.
  2. Often validation errors occur because of invalid data entered by your customers. For example this zip code with tailing spaces will lead to an error, because zip field must only contain numbers. 41515 . Make sure you clean, validate, trim etc. data as good as possible before transmitting, even best would be to add the TB.One requirements to your customer form validation, so only valid data can be entered.
  3. For testing purposes either get a separate TB.One account, or you should define a range of order numbers that are considered “test” and will not be processed (i.e. all order numbers starting with 6).
  4. Usually only orders considered as “paid” and “ready to ship” should be transmitted to TB.one. Especially if you are selling products of other brands or merchants and transfer the order to them for fulfillment vie TB.One.
  5. Validation of the XML against the latest XSD version is required before processing the data.
    You will find the most recent XSD under this URL https://api.trade-server.net/schema/all_in_one/tb-order_all_in_one.xsd
  6. Only send one order per XML and REST call.
  7. Always handle the API response.

Next steps

Autor