JSON/XML or JSON to XML

As we support both the Peppol UBL and XML standards you can freely choose between then, and even mix them, with creating a message as XML but fetching it using JSON, or the other way round.

The response, in JSON, will always include the three latest messages, per default. Using XML you always only get one (as there's no "array" function for XML).

With JSON data we add the integrationId attribute (the unique identifier in our DB) into the JSON object, as, with JSON, you can get an array of objects and then each object has it's own unique integrationId.

With XML we only return one message at a time in the original XML format and because of this the integrationId will be returned as a HTTP response header (and please note that HTTP headers are case-insensitive, meaning the returned ID will be integrationidin all lowercase letters!)

Transformation between JSON and XML

Our API is developed closely to the UBL and Peppol specifications why we've opted to include both the XML and JSON representations of the formats.

The two representations are "interchangeble" through a transform but if you are a "Node.js" shop you should opt for the JSON format. Other programming languages might have an easier time to work with XML instead.

There is a limitation in XML as there is no batch function for XML, meaning the XML format only supports one invoice per request!

Using the npm module xml2js you can transform between JSON and XML as the format is bi-directional.

const xml2js = require('xml2js');
// Convert from JSON ->> XML
const convertUblJsonToUblXml = async (json) => {
  const builder = new xml2js.Builder();
  return builder.buildObject(json);
};
// Convert from XML (string) ->> JSON
const convertUblXmlToUblJson = async (xmlString) => {
  const parser = new xml2js.Parser({ explicitArray: true, explicitCharkey: true });
  return parser.parseStringPromise(xmlString);
};

Limit

The XML has no “envelope” so we only ever return one message, meaning the limit parameter is set to 1. Using JSON you can set any limit you like, but the response size is limited to 6 MB.

For JSON, we return the integrationId as part of the message, while with XML you'll find it as a returned HTTP header named integrationId. When you do a POST (creating something) we return the message about the message created along with the integrationId.

The integrationId is the unique identifier for the message in our database and you can store that as an external permanent link to the message with us.