Server Web API
Javadoc -->



Server web API

When you run ion-docval as a local minimal web service, you can write your own tooling to make use of the web service API. You can use the two client implementations as examples, but the API itself is pretty basic.

There are currently two endpoints: one to perform the validation of a single document, and one to retrieve a list of document types that are configured by the server, and their keywords.

Validating a document

  • Endpoint URI (with default settings): http://localhost:35791/api/validate
  • Method: POST
  • Content-Type: application/xml
  • Accept: either application/xml or application/json
  • Query parameters: keyword (optional, keyword derivation is used if no keyword is provided)

The body of the POST should contain the XML data itself.

Sample response (JSON):

{
  "warning_count": 1,
  "error_count": 1,
  "warnings": [
    {
      "test": "false()",
      "location": "/*:Invoice[namespace-uri()='urn:oasis:names:specification:ubl:schema:xsd:Invoice-2'][1]/*:AccountingSupplierParty[namespace-uri()='urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2'][1]/*:Party[namespace-uri()='urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2'][1]/*:PartyLegalEntity[namespace-uri()='urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2'][1]/*:CompanyID[namespace-uri()='urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2'][1]",
      "message": "Document should not contain empty elements."
    }
  ],
  "errors": [
    {
      "test": "(contains(concat(' ', string-join(cac:PartyLegalEntity/cbc:CompanyID/@schemeID, ' '), ' '), ' 0106 ') or contains(concat(' ', string-join(cac:PartyLegalEntity/cbc:CompanyID/@schemeID, ' '), ' '), ' 0190 ')) and (cac:PartyLegalEntity/cbc:CompanyID/normalize-space(.) != '')",
      "location": "/*:Invoice[namespace-uri()='urn:oasis:names:specification:ubl:schema:xsd:Invoice-2'][1]/*:AccountingSupplierParty[namespace-uri()='urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2'][1]/*:Party[namespace-uri()='urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2'][1]",
      "message": "[BR-NL-1] For suppliers in the Netherlands the supplier MUST provide either a KVK or OIN number for its legal entity identifier (cac:AccountingSupplierParty/cac:Party/cac:PartyLegalEntity/cbc:CompanyID with schemeID 0106 or 0190)"
    }
  ]
}

Sample response (XML):

<?xml version="1.0" encoding="UTF-8"?>
<ValidationResult>
   <ErrorCount>1</ErrorCount>
   <WarningCount>1</WarningCount>
   <Errors>
      <Error>
         <Message>[BR-NL-1] For suppliers in the Netherlands the supplier MUST provide either a KVK or OIN number for its legal entity identifier (cac:AccountingSupplierParty/cac:Party/cac:PartyLegalEntity/cbc:CompanyID with schemeID 0106 or 0190)</Message>
         <Test>(contains(concat(' ', string-join(cac:PartyLegalEntity/cbc:CompanyID/@schemeID, ' '), ' '), ' 0106 ') or contains(concat(' ', string-join(cac:PartyLegalEntity/cbc:CompanyID/@schemeID, ' '), ' '), ' 0190 ')) and (cac:PartyLegalEntity/cbc:CompanyID/normalize-space(.) != '')</Test>
         <Location>/*:Invoice[namespace-uri()='urn:oasis:names:specification:ubl:schema:xsd:Invoice-2'][1]/*:AccountingSupplierParty[namespace-uri()='urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2'][1]/*:Party[namespace-uri()='urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2'][1]</Location>
      </Error>
   </Errors>
   <Warnings>
      <Warning>
         <Message>Document should not contain empty elements.</Message>
         <Test>false()</Test>
         <Location>/*:Invoice[namespace-uri()='urn:oasis:names:specification:ubl:schema:xsd:Invoice-2'][1]/*:AccountingSupplierParty[namespace-uri()='urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2'][1]/*:Party[namespace-uri()='urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2'][1]/*:PartyLegalEntity[namespace-uri()='urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2'][1]/*:CompanyID[namespace-uri()='urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2'][1]</Location>
      </Warning>
   </Warnings>
</ValidationResult>

Retrieve the configured document types and keywords

Endpoint URI (with default settings): http://localhost:35791/api/document_types Method: GET Accept: either application/xml or application/json

Sample response (JSON):

{
  "document_types": [
    {
      "name": "Peppol BIS 3 UBL Invoice",
      "description": "Peppol BIS 3.0 UBL Invoice",
      "keyword": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1"
    },
    {
      "name": "Peppol BIS 3 UBL Credit Note",
      "description": "Peppol BIS 3.0 UBL Credit Note",
      "keyword": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1"
    },
    {
      "name": "SI-UBL 2.0 Invoice",
      "description": "NLCIUS",
      "keyword": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:nen.nl:nlcius:v1.0::2.1"
    },
    {
      "name": "SI-UBL 2.0 Credit Note",
      "description": "NLCIUS",
      "keyword": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:nen.nl:nlcius:v1.0::2.1"
    }
  ]
}

Sample response (XML):

<?xml version="1.0" encoding="UTF-8"?>
<DocumentTypes>
   <DocumentType>
      <Name>Peppol BIS 3 UBL Invoice</Name>
      <Description>Peppol BIS 3.0 UBL Invoice</Description>
      <Keyword>urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1</Keyword>
   </DocumentType>
   <DocumentType>
      <Name>Peppol BIS 3 UBL Credit Note</Name>
      <Description>Peppol BIS 3.0 UBL Credit Note</Description>
      <Keyword>urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1</Keyword>
   </DocumentType>
   <DocumentType>
      <Name>SI-UBL 2.0 Invoice</Name>
      <Description>NLCIUS</Description>
      <Keyword>urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:nen.nl:nlcius:v1.0::2.1</Keyword>
   </DocumentType>
   <DocumentType>
      <Name>SI-UBL 2.0 Credit Note</Name>
      <Description>NLCIUS</Description>
      <Keyword>urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:nen.nl:nlcius:v1.0::2.1</Keyword>
   </DocumentType>
</DocumentTypes>