IBX Connect - The HTTP protocol

HTTP (Hypertext Transfer Protocol) or HTTPS (HTTP secure) in combination with SSL/TLS is the preferred protocol to exchange XML business documents between trading partners and the IBX Platform. HTTP uses the client-server model: An HTTP client opens a TCP/IP socket connection and sends a request message to an HTTP server; the server then returns a response message. After delivering the response, the server closes the connection. The format of the request and response messages are similar. IBX Connect uses and supports the POST method to send/retrieve data to/from trading partners.

HTTP POST request

A POST request is used to send data to the server to be processed in some way, like by a CGI script, a webservice etc. The HTTP POST request contains a block of data sent in the message body and specific header lines:

  • POST /invoke/inbound.soap:receiveSOAP HTTP/1.0 (path to the script, service, program processing the message; HTTP version)
  • Content-Type: text/xml; charset=utf-8 (type of content and encoding of the message in the body)
  • Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= ("username:password" credentials as base64 encoded string)
  • Content-Length: (the length of the data stream in the body)
  • Host: (server:port)
  • (blank line)
  • (the message to be sent)

  • The message in the body has to be well-formed XML wrapped into a SOAP envelope according to the IBX SOAP envelope specification. IBX Connect is sending HTTP requests with SOAP messages and "Content-Type: text/xml; charset=utf-8" if no attachments are included. Inbound also "Content-Type: application/soap+xml; charset=utf-8" is accepted.

    HTTP POST request with MIME

    The request looks different if the content of the body is not pure XML but including other type of data, e.g. images, binary objects, as in case of attachments being added to the business document (order, invoice etc.). Then the Content-Type in the HTTP header has to be "multipart/related" and the body contains both SOAP envelope with XML payload (buisiness document) and attachments in a MIME structure.

    The maximum size of a message being accepted by IBX Connect is 7.5 MB.

    HTTP response

    Each message sent to IBX Connect via the HTTP protocol results in a synchronous response message back to the calling application. An HTTP response with a 2xx OK response code is returned if the message has successfully passed the inbound validation at IBX Connect (basic- and schema validation). When sending business documents to trading partners IBX Connect is considering a transaction as FINISHED when it receives the HTTP 2xx OK response code within 45 seconds (session timeout). Additionally the SOAP-Response in the HTTP response body can hold warnings or information which helps for troubleshooting in case of errors but is not interpreted in case of success. The HTTP response consists of:

  • HTTP/1.0 200 OK (HTTP version and a standard response code - 200, 400, 500 etc.)
  • Content-Type: text/xml (type of content of the response message in the body)
  • Connection: Close (indicating that the HTTP connection is closed)
  • Content-Length: (the length of the data stream in the body)
  • (blank line)
  • (the optional SOAP response message to be sent)

  • The HTTP response body is SOAP based and describes the result of the operation on a detailed level with the message id of the received document. If an error is detected (validation, duplicate check), the response message describes the reason for it.
    Content type of the HTTP response is always "text/xml". For duplicate messages the response code can be modified per sender to e.g. "203" with a comprehensive error explanation in the SOAP response.