Convert

BIAC Access point can convert a Peppol BIS Billing 3 UBL document into a hybrid ZUGFeRD / Factur-X document (profile EN 16931): a PDF containing the invoice structured data as an embedded factur-x.xml file (UN/CEFACT CII D16B).

The converted document is returned in the response. It is not sent on the Peppol network and not stored by the access point.

Prerequisite

The UBL document must:

be a Peppol BIS Billing 3 Invoice or CreditNote (CustomizationID urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0). Self-billing documents are not supported.
have as supplier (cac:AccountingSupplierParty/cac:Party/cbc:EndpointID) the company linked to the API key.
contain the invoice PDF as its first embedded attachment: the first cac:AdditionalDocumentReference having a cac:Attachment/cbc:EmbeddedDocumentBinaryObject, with mimeCode="application/pdf" and a filename attribute.
respect the Peppol BIS 3.0 validation Rulesopen in new window.

<cac:AdditionalDocumentReference>
    <cbc:ID>INV-1122334455</cbc:ID>
    <cac:Attachment>
        <cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf" filename="INV-1122334455.pdf">JVBERi0xLjcK...</cbc:EmbeddedDocumentBinaryObject>
    </cac:Attachment>
</cac:AdditionalDocumentReference>

The PDF is used as the visual part of the Factur-X document; its document reference is not carried over in the factur-x.xml. Document references without embedded binary (e.g. with an external URI) are ignored when looking for the PDF.

The other embedded attachments (annexes) are kept: each one is embedded in the Factur-X PDF as an associated file next to factur-x.xml (relationship Supplement), under its filename, or its cbc:ID when it has no filename (suffixed with a number when the name is already used). In the factur-x.xml, the annex remains as a document reference (identifier and description), without its content.

Convert by API

Request

URL : /document/convert
Method : POST
Headers:
- x-api-key: THE API KEY
Max size: 50 MB
Body:

{
    "xmlBase64" : "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPEludm9pY2UgeG1sbnM9...",
    "targetFormat": "ZugferdEn16931",
    "clientReference": "MY-REF-001"
}

xmlBase64: The UBL document, base64 encoded
targetFormat: The output format. Only available value: ZugferdEn16931
clientReference (optional): Your own reference, returned in the response

Success Response

Code : 200 OK

Content exemple

{
  "transactionId": "fe7f3e0b-ce92-4b78-9f07-216cad3ca98a",
  "transactionStatus": "Success",
  "clientReference": "MY-REF-001",
  "targetFormat": "ZugferdEn16931",
  "documentBase64": "JVBERi0xLjcKJeLjz9MK..."
}

transactionId: The UUID of the conversion, to give to the support in case of problem
transactionStatus: Success
documentBase64: The Factur-X PDF, base64 encoded
fallbackReason: Only when the PDF could not be made PDF/A compliant: the reason why (see below)

If there are warnings on the document, the document is converted and the warnings are returned in ublValidation.warnings, as for the send API.

About the PDF/A conformity

The Factur-X PDF is produced as a PDF/A-3b. When the invoice PDF cannot be made PDF/A compliant (for instance a signed PDF, or fonts not embedded), the factur-x.xml is embedded in the original PDF, which is returned without PDF/A declaration, and the response contains a fallbackReason property describing the blocking issues. Such a document may not be accepted by receivers requiring a fully compliant Factur-X. A signed PDF keeps its signature valid.

{
  "transactionId": "fe7f3e0b-ce92-4b78-9f07-216cad3ca98a",
  "transactionStatus": "Success",
  "clientReference": "MY-REF-001",
  "targetFormat": "ZugferdEn16931",
  "documentBase64": "JVBERi0xLjcKJeLjz9MK...",
  "fallbackReason": "fonts not embedded: Helvetica"
}

Error Response

Code: 400 Bad request

The document is rejected. The message property starts with an error code, followed by a description.

Content exemple

{
  "transactionId": "e7d8b208-003f-4eb6-81d4-896e16fd8e89",
  "transactionStatus": "Failed",
  "message": "NO_EMBEDDED_PDF: The document has no embedded attachment.",
  "clientReference": "MY-REF-001",
  "targetFormat": "ZugferdEn16931"
}

Content exemple with validation errors

{
  "transactionId": "e7d8b208-003f-4eb6-81d4-896e16fd8e89",
  "transactionStatus": "Failed",
  "message": "EN16931_VIOLATION: The document violates an EN 16931 or Peppol business rule.",
  "targetFormat": "ZugferdEn16931",
  "ublValidation": {
    "errors": [
      {
        "context": "THE CONTEXT ERROR",
        "errorMessage": "THE ERROR MESSAGE",
        "xpathTest": "MORE INFORMATION"
      }
    ],
    "warnings": []
  }
}

Code: 401 Unauthorized

ApiKey incorrectly configured or invalid.

Code: 500 Internal Server Error

The document is valid but the conversion failed (CONVERSION_FAILED). For instance, the invoice PDF is encrypted or corrupted. Please contact the support with the transactionId.

Error codes

Code	HTTP	Description
`UNSUPPORTED_TARGET_FORMAT`	400	`targetFormat` is missing or has an unknown value.
`INVALID_XML`	400	`xmlBase64` is missing, empty or is not well-formed XML.
`INVALID_BASE64`	400	`xmlBase64`, or the content of an annex, is not valid base64.
`SCHEMA_VIOLATION`	400	The document is not a UBL BIS Billing 3 `Invoice` or `CreditNote`, or does not respect the UBL schema. Details in `xmlSchemaErrors`.
`SUPPLIER_MISMATCH`	400	The supplier of the document is not the company linked to the API key.
`NO_EMBEDDED_PDF`	400	The document has no embedded attachment.
`PDF_NOT_FIRST_ATTACHMENT`	400	The first embedded attachment is not a PDF (wrong `mimeCode`, missing `filename`, invalid base64 or content not being a PDF).
`EN16931_VIOLATION`	400	The document violates an EN 16931 or Peppol business rule. Details in `ublValidation.errors`.
`CONVERSION_FAILED`	500	Technical error during the conversion.

The controls are done in this order: target format, reading of xmlBase64, document type, supplier, invoice PDF, annexes, then UBL schema and business rules. A rejected document is never converted.

Schemas

ConvertResponseModel

{
  "transactionId": "STRING",
  "transactionStatus": "STRING",
  "message": "STRING",
  "clientReference": "STRING",
  "targetFormat": "STRING",
  "documentBase64": "STRING",
  "fallbackReason": "STRING",
  "xmlSchemaErrors": [
    {
      "context": "STRING",
      "errorMessage": "STRING",
      "xpathTest": "STRING"
    }
  ],
  "ublValidation": {
    "errors": [
      {
        "context": "STRING",
        "errorMessage": "STRING",
        "xpathTest": "STRING"
      }
    ],
    "warnings": [
      {
        "context": "STRING",
        "errorMessage": "STRING",
        "xpathTest": "STRING"
      }
    ]
  }
}

Properties without value are not returned.

transactionId

transactionId is the identifiant of the conversion.

transactionStatus

the transaction status, Success or Failed.

message

When the conversion fails, message contains the error code and its description (CODE: description).

clientReference

The clientReference sent in the request.

targetFormat

The targetFormat sent in the request.

documentBase64

The Factur-X PDF, base64 encoded. Only returned on success.

fallbackReason

Only returned on success, when the invoice PDF could not be made PDF/A compliant: the blocking issues, separated by ;. The document is then the original PDF with the embedded factur-x.xml, without PDF/A declaration.

xmlSchemaErrors

xmlSchemaErrors is an array containing all errors about the xml schema.

ublValidation

errors is an array containing all errors not respecting Peppol BIS 3.0 validation Rulesopen in new window

warnings is an array containing all warning not respecting Peppol BIS 3.0 validation Rules open in new window

# Convert

# Prerequisite

# Convert by API

# Request

# Success Response

# Error Response

# Error codes

# Schemas

# ConvertResponseModel