Sovos Canonical Invoice Extensions

The SCI Extensions address the challenges of mapping UBL 2.1 standard elements to specific country mandates by providing a set of elements for countries with unique requirements.

UBL 2.1 is known to be a complete and flexible standard, but there are cases where it's difficult to find related elements between this format and certain elements available in some country mandates. To solve this, Sovos created the SCI Extensions, which are a set of elements applicable for countries that trigger this kind of conflict.

Extensions are the schemas created by the mapping team. Each schema serves to:

Represent specific information required by a particular mandate (SovosExtension container).
Represent information on the XML document that isn't required to be sent to the tax authority, but is needed by Sovos or its customers to meet internal data requirements (AdditionalData container).

There may be cases where the SovosExtension element must be used to include the extensions for meeting the tax authority's data requirements. In addition, if the AdditionalData tag is also used in that case, it should be created on the same level as SovosExtension, so that both are under the ExtensionContent UBL node, as shown in examples from this page.

In other words, extended fields are fields defined outside the UBL pattern to attend government or internal requirements:

Data that will be reported to the government: In this scenario, the data is too specific and doesn't fit in a UBL standard element. In that case, the fields must be inserted in SovosExtension (Generic Extensions). When the data is reported to the government, the mapping will direct (transform) the information to the Legal Element required by the Tax Authority in the same way that the rest of the SCI works.
Data that will not be reported to the government: In this scenario, the data is needed for meeting internal requirements such as mail distribution list, QR code encryption, and PDF documents. In that case, the fields must be also added as extensions, but in the AdditionalData extension (different structure than SovosExtension). The backend needs to be able to extract this information for the internal requirements.

SCI elements

Available SCI elements:

AdditionalData
SovosExtensions
- legalExtension
  - Legal
  - LegalAddon
  - CustomerData

You need extensions if the country you want to support is on this list:

Colombia: AdditionalData
Peru: AdditionalData
Mexico: SovosExtension: LegalAddon group
Chile: Boletas
Brazil: NFCom and NFe (SovosExtension: Legal group)
Hungary: SovosExtension: Legal group
Poland: SovosExtension: Legal group

AdditionalData element

AdditionalData is a data block dedicated to specific data that will not be reported to the legal tax authority. It is used for internal purposes such as logos, email distribution list, and data to be printed in PDFs.

Note:

To use the AdditionalData element, your backend must be able to extract its information.

Here is a sample using the AdditionalData element inside a UBLExtension:

<cbc:ID>90049115</cbc:ID>
<cbc:IssueDate>2021-08-30</cbc:IssueDate>
<cbc:IssueTime>12:36:07</cbc:IssueTime>
<cbc:InvoiceTypeCode>I</cbc:InvoiceTypeCode>
<cbc:DocumentCurrencyCode>MXN</cbc:DocumentCurrencyCode>
<ext:UBLExtensions>
	<ext:UBLExtension>
		<ext:ExtensionContent>
			<ad:AdditionalData>
				<ad:HeaderFields>
					<ad:Field name="Correodist" type="string">name@sovos.com</ad:Field>
				</ad:HeaderFields>
				<ad:ItemFields>
					<ad:Field name="QRcode" type="string" item="10">iewqiuwqdiuqwniqn91229328eu9wdn91</ad:Field>
				</ad:itemFields>
			</ad:AdditionalData>
		</ext:ExtensionContent>
	</ext:UBLExtension>
</ext:UBLExtensions>

Note:

In this example, there's an email for a distribution list inside HeaderFields and a QR Code inside ItemFields.

The following table lists the different Xpaths for this element:


XPath			Type	#	Description
HeaderFields			block	0..1	Block to add information at the invoice level.
	Field		string	0..*	Element used to report printed information.
		name	string	1..1	Attribute that refers to the description of information that needs to be printed.
		type	string	0..1	Attribute used for special cases where the client wants to report Base64-encoded values or image references. Enum: "Base64" and "Image".
		item	string	0..1	Attribute used to link the current `Field` tag with their respective invoice line item.
ItemFields			block	0..1	Block to add information at the invoice line level.
	Field		string	0..*	Element used to report printed information.
		name	string	1..1	Attribute that refers to the description of information that needs to be printed.
		type	string	0..1	Attribute used for special cases where the client wants to report Base64-encoded values or image references. Enum: "Base64" and "Image".
		item	string	0..1	Attribute used to link the current `Field` tag with their respective invoice line item.

Sovos extensions (generic extensions)

You need to add the SovosExtension element for countries that need this structure to fulfill the tax authority's data requirements. It's used to support the legal elements that require information that doesn't have related fields inside the UBL 2.1 standard.

Generic approach to cover many scenarios
Reusable structure | Support to all countries/documents that need it
Recursive groups
More readable and understandable documents

You need to create the SovosExtension tag with the prefix "sov:" and place it in the ext:UBLExtensions/ext:UBLExtension/ext:ExtensionContent element, which is a common element in all UBL 2.1 standard documents such as invoice, credit note, and debit note.

Here is a sample:

<svs:SovosDocument>
  <sci:SovosCanonicalInvoice>
    <inv:Invoice>
      <ext:UBLExtensions>
        <ext:UBLExtension>
          <ext:ExtensionContent>
            <sov:SovosExtension>
              *extension content*
            </sov:SovosExtension>
          </ext:ExtensionContent>
        </ext:UBLExtension>
      </ext:UBLExtensions>
    </inv:Invoice>
  </sci:SovosCanonicalInvoice>
</svs:SovosDocument>

The SovosExtension group can contain the following nodes:

legalExtension: This node can hold, at the same time, the Legal, LegalAddon, and CustomerData child nodes.
Legal group: Contains particular data required by the country schema.

Here is a sample:

<n0:StandardBusinessDocument>
	<svs:SovosDocument>
		<sci:SovosCanonicalInvoice>
			<inv:Invoice>
				<ext:UBLExtensions>
					<ext:UBLExtension>
						<ext:ExtensionContent>
							<sov:SovosExtension>
								<leg:legalExtension>
									<leg:Legal>
										<leg:HeaderFields>
											<leg:Field/>
											<leg:GroupInformation>
												<leg:Id/>
												<leg:Field/>
												<leg:GroupInformation/></leg:GroupInformation>
										</leg:HeaderFields>
										<leg:LineFields>
											<leg:Line>
												<leg:LineId/>
												<leg:Field/>
												<leg:GroupInformation>
													<leg:Id/>
													<leg:Field/>
													<leg:GroupInformation/></leg:GroupInformation>
											</leg:Line>
										</leg:LineFields>
									</leg:Legal>
								</leg:legalExtension>
							</sov:SovosExtension>
						</ext:ExtensionContent>
					</ext:UBLExtension>
				</ext:UBLExtensions>
			</inv:Invoice>
		</sci:SovosCanonicalInvoice>
	</svs:SovosDocument>
</n0:StandardBusinessDocument>

The following table lists the different Xpaths:


XPath					Type	#	Description
HeaderFields					block	0..1	Block to add information at the invoice level.
	Field				string	0..*	Element used to carry data
		name			string	1..1	Attribute that refers to the description of the data
	GroupInformation				block	0..*	It's the group node or container used to carry data of group nodes from the legal structure
		Id			string	0..1	Used to specify which group of information from the legal structure corresponds to the data contained on the `GroupInformartion` element of the SCI
		Field			string	0..*	Element used to carry data
			name		string	1..1	Attribute that refers to the description of the data
		GroupInformation			block	0..*	The group node or container used to carry data from group nodes of the legal structure
LineFields					block	0..1	Block to add information at the invoice line level
	Line				block
		LineId			string	0..1	Invoice Line ID, used to differentiate the possible uses
		Field			string	0..*	Element used to carry data
			name		string	1..1	Attribute that refers to the description of the data
		GroupInformation			block	0..*	The group node or container used to carry data of group nodes from the legal structure
			Id		string	0..1	Used to specify to which group of information from the legal structure corresponds to the data contained in the `GroupInformartion` element of the SCI
			Field		string	0..*	Element used to carry data
				name	string	1..1	Attribute that refers to the description of the data
			GroupInformation		block	0..*	The group node or container used to carry data from group nodes of the legal structure

SCI extension usage examples

Samples with the SCI extension being used in different scenarios.

Hungary (legal group)

Here is a sample of the GroupInformation node for Hungary:

<leg:GroupInformation>
	<leg:Id>newTransportMean</leg:Id>
	<leg:Field name="brand">PULI-H</leg:Field>
	<leg:Field name="serialNum">TR11234200000001</leg:Field>
	<leg:Field name="engineNum">ABCD12345</leg:Field>
	<leg:Field name="firstEntryIntoService">2021-03-02</leg:Field>
	<leg:Field name="engineCapacity">1182</leg:Field>
	<leg:Field name="enginePower">74</leg:Field>
	<leg:Field name="kms">80000</leg:Field>
</leg:GroupInformation>

Brazil (legal group)

For NFCom, see this XML Sample and the following print sample:

<ext:UBLExtensions>
	<ext:UBLExtension>
		<ext:ExtensionContent>
			<sov:SovosExtension>
				<leg:LegalExtension>
					<leg:Legal>
						<leg:HeaderFields>
							<leg:Field name="cUF">14</leg:Field>
							<leg:Field name="mod">62</leg:Field>
							<leg:Field name="cNF">00000000</leg:Field>
							<leg:GroupInformation>
								<leg:Id>gFidelidade</leg:Id>
								<leg:Field name="qtdSaldoPts">100</leg:Field>
								<leg:Field name="dRefSaldoPts">2022-08-10</leg:Field>
								<leg:Field name="qtdPtsResg">0</leg:Field>
								<leg:Field name="dRefResgPts">2022-08-10</leg:Field>
							</leg:GroupInformation>
						</leg:HeaderFields>
						<leg:LineFields>
							<leg:Line>
								<leg:LineId>1</leg:LineId>
								<leg:Field name="chNFComAnt">00000000000000000000000000000000000000000000</leg:Field>
								<leg:Field name="nItemAnt">1</leg:Field>
								<leg:Field name="CFOP">1001</leg:Field>
								<leg:Field name="CNPJLD">11222333000144</leg:Field>
								<leg:Field name="indDevolucao">0</leg:Field>
								<leg:GroupInformation>
									<leg:Id>gProcRef</leg:Id>
									<leg:Field name="indDevolucao">1</leg:Field>
									<leg:GroupInformation>
										<leg:Id>gProc</leg:Id>
										<leg:Field name="tpProc">1</leg:Field>
									</leg:GroupInformation>
								</leg:GroupInformation>
							</leg:Line>
						</leg:LineFields>
					</leg:Legal>
				</leg:LegalExtension>
			</sov:SovosExtension>
		</ext:ExtensionContent>
	</ext:UBLExtension>
</ext:UBLExtensions>

For NF3e, see this XML Sample and the following print sample:

<ext:UBLExtensions>
	<ext:UBLExtension>
		<ext:ExtensionContent>
			<sov:SovosExtension>
				<leg:LegalExtension>
					<leg:Legal>
						<leg:HeaderFields>
							<leg:Field name="cNF">1484723</leg:Field>
							<leg:Field name="cDV">7</leg:Field>
							<leg:Field name="tpEmis">1</leg:Field>
							<leg:Field name="xNomeUC">UC Name</leg:Field>
							<leg:GroupInformation>
								<leg:Id>gMed</leg:Id>
								<leg:Field name="nMed">16</leg:Field>
								<leg:Field name="idMedidor">4587</leg:Field>
								<leg:Field name="dMedAnt">2022-07-02</leg:Field>
								<leg:Field name="dMedAtu">2022-08-01</leg:Field>
							</leg:GroupInformation>
						</leg:HeaderFields>
						<leg:LineFields>
							<leg:Line>
								<leg:LineId>1</leg:LineId>
								<leg:Field name="chNF3eAnt">00000000000000000011100000000000000000000000</leg:Field>
								<leg:Field name="mod6HashAnt">UjBsR09EbGhjZ0dTQUxNQUBFUUNBRU1tQ1p0dU1GUXhEUzhi</leg:Field>
								<leg:Field name="nItemAnt">900</leg:Field>
								<leg:GroupInformation>
									<leg:Id>gAjusteNF3eAnt</leg:Id>
									<leg:Field name="tpAjuste">3</leg:Field>
									<leg:Field name="motAjuste">3</leg:Field>
								</leg:GroupInformation>
							</leg:Line>
						</leg:LineFields>
					</leg:Legal>
				</leg:LegalExtension>
			</sov:SovosExtension>
		</ext:ExtensionContent>
	</ext:UBLExtension>
</ext:UBLExtensions>

LegalAddon group

"Complementos" or schemas that are not included in the general structure of the country, such as Mexico's carta porte. Here is a sample:

<n0:StandardBusinessDocument>
	<svs:SovosDocument>
		<sci:SovosCanonicalInvoice>
			<inv:Invoice>
				<ext:UBLExtensions>
					<ext:UBLExtension>
						<ext:ExtensionContent>
							<sov:SovosExtension>
								<leg:legalExtension>
									<leg:LegalAddon>
										*Country specific schema*
									</leg:LegalAddon>
								</leg:legalExtension>
							</sov:SovosExtension>
						</ext:ExtensionContent>
					</ext:UBLExtension>
				</ext:UBLExtensions>
			</inv:Invoice>
		</sci:SovosCanonicalInvoice>
	</svs:SovosDocument>
</n0:StandardBusinessDocument>

CustomerData group

Information that can be in any format and that you want to send, but are not required to report.

Here is a sample:

<n0:StandardBusinessDocument>
	<svs:SovosDocument>
		<sci:SovosCanonicalInvoice>
			<inv:Invoice>
				<ext:UBLExtensions>
					<ext:UBLExtension>
						<ext:ExtensionContent>
							<sov:SovosExtension>
								<leg:legalExtension>
									<leg:CustomerData>
										*Customer specific data*
									</leg:CustomerData>
								</leg:legalExtension>
							</sov:SovosExtension>
						</ext:ExtensionContent>
					</ext:UBLExtension>
				</ext:UBLExtensions>
			</inv:Invoice>
		</sci:SovosCanonicalInvoice>
	</svs:SovosDocument>
</n0:StandardBusinessDocument>

Here is a usage example:

<ext:UBLExtensions>
	<ext:UBLExtension>
		<ext:ExtensionContent>
			<sov:SovosExtension>
				<leg:LegalExtensions>
					<leg:CustomerData>
						<Electricity xmls="" xsi:schemaLocation="">
						<!--Corresponding namespaces and schemalocation for the CustomerData structure-->
							<VERSION>
								<Number>2.0</Number>
							</VERSION>
							<Document>
								<DocumentType>Invoice</DocumentType>
							</Document>
							<Business>
								<DIVISION>Cars</DIVISION>
								<Expenses/>
							</Business>
							<Provider>
								<ProviderName>HASBRO DE MEXICO</ProviderName>
								<Email>invoicing@example.com</Email>
							</Provider>
							<Details>
								<Line>
									<LineNumber>1</LineNumber>
									<Quantity>1</Quantity>
									<UnitPrice>80000</UnitPrice>
								</Line>
							</Details>
						</Electricity>
					</leg:CustomerData>
				</leg:LegalExtensions>
			</sov:SovosExtension>
		</ext:ExtensionContent>
	</ext:UBLExtension>
</ext:UBLExtensions>

Extensions for Mexico

The mex:Mexico format in the extensions is currently supported in the Delta backend, as well as the generic leg:legalExtension structure. Legacy implementations are considered and made backward compatible for them to migrate when the time is right.

For Mexico (LegalAddon group), see this XML Sample and the following print sample of "Complementos":

<ext:UBLExtensions>
	<ext:UBLExtension>
		<ext:ExtensionContent>
			<sov:SovosExtension>
				<mex:Mexico>
					<mex:LegalAddon>
					<cce11:ComercioExterior xmlns:cce11="http://www.sat.gob.mx/ComercioExterior11" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Version="1.1" MotivoTraslado="04" TipoOperacion="2" ClaveDePedimento="A1" CertificadoOrigen="0" NumCertificadoOrigen="$&quot;#! %" NumeroExportadorConfiable="!" Incoterm="DAP" Subdivision="0" Observaciones="!" TipoCambioUSD="0" TotalUSD="0">
						<cce11:Emisor Curp="AAAA000101HASBBB00">
							<cce11:Domicilio Calle="!" NumeroExterior="!" NumeroInterior="!" Colonia="6051" Localidad="11" Referencia="!" Municipio="318" Estado="VT" Pais="TON" CodigoPostal="08490"/>
						</cce11:Emisor>
						<cce11:Propietario NumRegIdTrib="aaaaaa" ResidenciaFiscal="BGD"/>
						<cce11:Receptor NumRegIdTrib="aaaaaa">
							<cce11:Domicilio Calle="!" NumeroExterior="!" NumeroInterior="!" Colonia="!" Localidad="!" Referencia="!" Municipio="!" Estado="!" Pais="PRK" CodigoPostal="a"/>
						</cce11:Receptor>
						<cce11:Destinatario NumRegIdTrib="aaaaaa" Nombre="!">
							<cce11:Domicilio Calle="!" NumeroExterior="!" NumeroInterior="!" Colonia="!" Localidad="!" Referencia="!" Municipio="!" Estado="!" Pais="BLR" CodigoPostal="a"/>
						</cce11:Destinatario>
						<cce11:Mercancias>
							<cce11:Mercancia NoIdentificacion="!" FraccionArancelaria="2922390900" CantidadAduana="0.001" UnidadAduana="13" ValorUnitarioAduana="0" ValorDolares="0">
								<cce11:DescripcionesEspecificas Marca="!" Modelo="!" SubModelo="!" NumeroSerie="!"/>
							</cce11:Mercancia>
						</cce11:Mercancias>
					</cce11:ComercioExterior>
					</mex:LegalAddon>
				</mex:Mexico>
			</sov:SovosExtension>
		</ext:ExtensionContent>
	</ext:UBLExtension>
</ext:UBLExtensions>

For Mexico (CustomerData), see this sample:

<ext:UBLExtensions>
	<ext:UBLExtension>
		<ext:ExtensionContent>
			<sov:SovosExtension>
				<mex:Mexico>
					<mex:CustomerData>
						<Electricity xmls="" xsi:schemaLocation="">
							<!--Corresponding
namespaces and schemalocation for the CustomerData structure-->
							<VERSION>
								<Number>2.0</Number>
							</VERSION>
							<Document>
								<DocumentType>Invoice</DocumentType>
							</Document>
							<Business>
								<DIVISION>Cars</DIVISION>
								<Expenses/>
							</Business>
							<Provider>
								<ProviderName>HASBRO DE MEXICO</ProviderName>
								<Email>invoicing@example.com</Email>
							</Provider>
							<Details>
								<Line>
									<LineNumber>1</LineNumber>
									<Quantity>1</Quantity>
									<UnitPrice>80000</UnitPrice>
								</Line>
							</Details>
						</Electricity>
					</mex:CustomerData>
				</mex:Mexico>
			</sov:SovosExtension>
		</ext:ExtensionContent>
	</ext:UBLExtension>
</ext:UBLExtensions>

Sovos Docs

Sovos Canonical Invoice Extensions

SCI elements

AdditionalData element

Sovos extensions (generic extensions)

SCI extension usage examples

Hungary (legal group)

Brazil (legal group)

LegalAddon group

CustomerData group

Extensions for Mexico

sovos-footer