Skip to main content

Configure e-invoicing response field mappings

Zuora

Configure e-invoicing response field mappings

The e-invoicing response field mappings are used to map values in Sovos response data, which includes additional information generated by the tax authority, to fields on the EInvoiceData object in Zuora.

You can configure response field mappings only if you configure the following settings:

After an e-invoicing document is successfully processed in Sovos, Sovos sends the billing-document-related information with additional information retrieved from the tax authority in the response data, which might include the reference number, QR code data, authorization code, and others.

You can configure response field mappings at the business region level to customize the field mapping rules of the EInvoiceData object.

  • If the buyer is from a Zuora pre-integrated country such as India, Italy, and Saudi Arabia, Zuora maps the reference number, QR code and other required information in the response data to the EInvoiceData object by default. You can configure the response field mappings to store additional information as needed.
    Note that configuring field mappings for default fields overwrites Zuora’s default settings, which might break the e-invoicing workflow.
    For more information about pre-integrated countries, see Pre-integrated countries.
  • If it is not a pre-integrated country, Zuora does not store any data in the EInvoiceData object by default. You must configure the response field mappings to decide which values to store.

Prerequisites

Before configuring the response field mappings, you must complete the following prerequisites:

  • Get an XML-formatted response payload sample of a particular country from Sovos.
  • Get familiar with the XPath syntax that field paths must be compliant with. For more information, see Field path format.

Configure response field mappings

You can configure response field mappings when creating or updating business regions for the Sovos service provider.

To configure response field mappings, perform the following steps:

  1. Click your avatar in the upper right and click Settings > Billing.
  2. On the Billing Settings page, click E-Invoice.
  3. On the E-Invoice Settings page, perform one of the following operations:
    • If you want to configure response field mappings for a new business region, click + Add in the Business Regions section.
    • If you want to configure response field mappings for an existing business region, locate the business region in the Business Regions section and then click the Edit  icon.
  4. In the displayed Add Business Region dialog, click + Add Field Mapping in the Response Mapping section.

    You can configure response field mappings only if you configure the following settings:

  5. Complete the following information:
    • Field Name: Select a field name from the list. This is the name of the mapped field on the EInvoiceData object. For more information, see Supported response fields.
      If you select a default field for countries with which Zuora is pre-integrated, the setting will overwrite the default mapping. For more information about default fields of different countries, see Manage country-specific configurations.
    • Field Path: Refer to the response payload sample provided by Sovos and specify the field path of an XML node.
      The format of this field must comply with the XML Path Language (XPath) syntax. For more information about how to identify XML nodes with XPath, see Field path format.

Retrieve e-invoicing response data

When the e-invoice file status of a billing document is Success, you can retrieve the e-invoicing response data stored in the EInvoiceData object.

For more information, see Retrieve e-invoice results.

Supported response fields

The following table lists supported e-invoicing response fields. Most of these fields are from the EInvoiceData object, except for the EInvoiceFile field.

Field name Format Description
EInvoiceFile String

This field is used to store the cleared e-invoice file returned from the tax authority.

This is not a field on the EInvoiceData object. Zuora retrieves the cleared e-invoice file according to this field and stores the file ID in the EInvoiceFile field on billing documents. You can download the file with the Retrieve a file API operation.

AuthorizationCode String This field is used to store the authorization code issued by the administration when the e-invoicing data of a billing document is approved by the tax authority.
QrCode String

This field is used to store the QR code generated by the tax authority.

You do not need to map this field if the tax authority does not provide a QR code.

ReferenceNumber String

This field is used to store the unique number generated by the tax authority.

You do not need to map this field if the tax authority does not provide this number.

Field1 - Field10 String

These reserved fields are used to store additional information. You can map any values in the Sovos response data to these fields to meet your business needs.

The maximum number of characters for the fields are as follows:

  • Field1 to Field5: 2048
  • Field6 to Field10: 8192

Field path format

A field path in a field mapping configuration is a string that indicates a node in Sovos’ XML response payload, and the string must comply with the XPath syntax.

The later sections of this article use the following snippet as an example to help you understand the XPath syntax. This snippet is extracted from the Sovos’ response payload sample. You can get a complete response payload sample for each country from Sovos.

<ApplicationResponse>
    <ext:UBLExtensions>
        <ext:UBLExtension>
            <ext:ExtensionContent>
                <ad:AdditionalData>
                    <ad:Field name="SdiId" type="FormalIdentifier">a2c73…10b31
                    </ad:Field>
                    …
                </ad:AdditionalData>
            </ext:ExtensionContent>
        </ext:UBLExtension>
    </ext:UBLExtensions>
    …
    <cac:DocumentResponse>
        …
        <cac:DocumentReference>
            <cbc:ID>JqYyq…cKje</cbc:ID>
            <cbc:DocumentTypeCode>LegalCleared</cbc:DocumentTypeCode>
            <cac:Attachment>
                <cbc:EmbeddedDocumentBinaryObject>ZXlKaGJH…nN3c=
                </cbc:EmbeddedDocumentBinaryObject>
            </cac:Attachment>
        </cac:DocumentReference>
        <cac:DocumentReference>
            <cbc:ID>JqYyq…CUcs</cbc:ID>
            <cbc:DocumentTypeCode>Legal</cbc:DocumentTypeCode>
            <cac:Attachment>
                <cbc:EmbeddedDocumentBinaryObject>ZXlKaGJH…kQQ==
                </cbc:EmbeddedDocumentBinaryObject>
            </cac:Attachment>
        </cac:DocumentReference>
    </cac:DocumentResponse>
</ApplicationResponse>

Commonly used expressions

The following table lists some commonly used expressions in XPath:

Expression Description Example Result
/ Selects from the root node /ApplicationResponse Selects the root node ApplicationResponse
/ApplicationResponse/cac:DocumentResponse Selects all cac:DocumentResponse nodes that are children of ApplicationResponse
// Selects nodes from the current node that match the selection no matter where they are //cac:DocumentReference Selects all cac:DocumentReference nodes in the document
/ApplicationResponse//cac:DocumentReference Selects all cac:DocumentReference nodes that are descendants of the root node ApplicationResponse
@ Selects attributes @type Selects all attributes that are named type
[] Applies a filter to the current node //cac:DocumentReference[cbc:DocumentTypeCode=DocumentTypeCode] Selects all cac:DocumentReference nodes that have a cbc:DocumentTypeCode child node with the value of DocumentTypeCode
//ad:Field[@name=’SdiId’] Selects all ad:Field nodes that have a name attribute with the value of SdiId
* Matches any element node //cac:DocumentReference/* Selects all the children of cac:DocumentReference
text() Selects the text of the current node //ad:Field/text() Selects the text of each ad:Field node

For more information about XPath syntax, see XPath Tutorial.

Field path examples

The following table lists the field path examples for some commonly used fields:

Field name Field path example Selected content
EInvoiceFile //cac:DocumentReference[cbc:DocumentTypeCode='LegalCleared']/cac:Attachment/cbc:EmbeddedDocumentBinaryObject/text() ZXlKaGJH…nN3c=
ReferenceNumber //ad:Field[@name='SdiId']/text() a2c73…10b31