Skip to main content
Download OpenAPI

Formats

Invoices in the Spanish market are issued in the national Facturae 3.2.2 format. POST /invoices, POST /invoices/draft and PUT /invoices/draft/{uuid} accept the document in either representation, selected by Content-Type:

  • application/xml (or text/xml): the Facturae XML document.
  • application/json: an equivalent JSON object whose keys mirror the Facturae element names one-for-one; repeated elements (Invoice, Tax, InvoiceLine, Installment, …) become JSON arrays. JSON is converted to Facturae XML before processing, so the two paths run the identical validation.

A-Cube validates the document against the official Facturaev3_2_2.xsd schema plus the business rules required for acceptance. Only single-invoice documents are accepted; a batch / lote (Modality L) is rejected.

The root element is <fe:Facturae> in namespace http://www.facturae.gob.es/formato/Versiones/Facturaev3_2_2.xml (FileHeader / Parties / Invoices top-level object keys in JSON), with three top-level blocks:

BlockPurpose
FileHeaderSchemaVersion, Modality (I individual, always, see above), InvoiceIssuerType (EM seller / RE buyer / TE third party), Batch totals
PartiesSellerParty and BuyerParty, each with TaxIdentification (the NIF/NIE/CIF in TaxIdentificationNumber) and LegalEntity or Individual
Invoicesa single Invoice with InvoiceHeader (InvoiceNumber, InvoiceDocumentType, InvoiceClass), InvoiceIssueData, TaxesOutputs, InvoiceTotals, Items

InvoiceDocumentType: FC complete invoice, FA simplified invoice, AF self-billed invoice. InvoiceClass: OO original, OR corrective, OC summary (and the CO / CR / CC copies). Corrective invoices are covered in Credit notes.

info

Under VERI*FACTU, A-Cube turns each accepted invoice into a billing record (registro de alta), chains it to the previous record through a hash (huella), reports it to AEAT, and returns the invoice as a factura verificable with its QR code. You send the Facturae document; the record building and reporting are handled for you.

Example​

The Send invoice page shows this same document in both XML and JSON, side by side. The XML form is below.

Facturae 3.2.2 invoice example (XML)
<?xml version="1.0" encoding="UTF-8"?>
<fe:Facturae xmlns:fe="http://www.facturae.gob.es/formato/Versiones/Facturaev3_2_2.xml" xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
	<FileHeader>
		<SchemaVersion>3.2.2</SchemaVersion>
		<Modality>I</Modality>
		<InvoiceIssuerType>EM</InvoiceIssuerType>
		<Batch>
			<BatchIdentifier>A58818501-FV-2026-0001</BatchIdentifier>
			<InvoicesCount>1</InvoicesCount>
			<TotalInvoicesAmount><TotalAmount>1452.00</TotalAmount></TotalInvoicesAmount>
			<TotalOutstandingAmount><TotalAmount>1452.00</TotalAmount></TotalOutstandingAmount>
			<TotalExecutableAmount><TotalAmount>1452.00</TotalAmount></TotalExecutableAmount>
			<InvoiceCurrencyCode>EUR</InvoiceCurrencyCode>
		</Batch>
	</FileHeader>
	<Parties>
		<SellerParty>
			<TaxIdentification>
				<PersonTypeCode>J</PersonTypeCode>
				<ResidenceTypeCode>R</ResidenceTypeCode>
				<TaxIdentificationNumber>A58818501</TaxIdentificationNumber>
			</TaxIdentification>
			<LegalEntity>
				<CorporateName>SupplierOfficialName Ltd.</CorporateName>
				<AddressInSpain>
					<Address>Calle Mayor 1</Address>
					<PostCode>28001</PostCode>
					<Town>Madrid</Town>
					<Province>Madrid</Province>
					<CountryCode>ESP</CountryCode>
				</AddressInSpain>
			</LegalEntity>
		</SellerParty>
		<BuyerParty>
			<TaxIdentification>
				<PersonTypeCode>J</PersonTypeCode>
				<ResidenceTypeCode>R</ResidenceTypeCode>
				<TaxIdentificationNumber>B12345674</TaxIdentificationNumber>
			</TaxIdentification>
			<LegalEntity>
				<CorporateName>Buyer Official Name</CorporateName>
				<AddressInSpain>
					<Address>Calle Alcala 20</Address>
					<PostCode>28014</PostCode>
					<Town>Madrid</Town>
					<Province>Madrid</Province>
					<CountryCode>ESP</CountryCode>
				</AddressInSpain>
			</LegalEntity>
		</BuyerParty>
	</Parties>
	<Invoices>
		<Invoice>
			<InvoiceHeader>
				<InvoiceNumber>FV-2026-0001</InvoiceNumber>
				<InvoiceDocumentType>FC</InvoiceDocumentType>
				<InvoiceClass>OO</InvoiceClass>
			</InvoiceHeader>
			<InvoiceIssueData>
				<IssueDate>2026-01-15</IssueDate>
				<InvoiceCurrencyCode>EUR</InvoiceCurrencyCode>
				<TaxCurrencyCode>EUR</TaxCurrencyCode>
				<LanguageName>es</LanguageName>
			</InvoiceIssueData>
			<TaxesOutputs>
				<Tax>
					<TaxTypeCode>01</TaxTypeCode>
					<TaxRate>21.00</TaxRate>
					<TaxableBase><TotalAmount>1200.00</TotalAmount></TaxableBase>
					<TaxAmount><TotalAmount>252.00</TotalAmount></TaxAmount>
				</Tax>
			</TaxesOutputs>
			<InvoiceTotals>
				<TotalGrossAmount>1200.00</TotalGrossAmount>
				<TotalGrossAmountBeforeTaxes>1200.00</TotalGrossAmountBeforeTaxes>
				<TotalTaxOutputs>252.00</TotalTaxOutputs>
				<TotalTaxesWithheld>0.00</TotalTaxesWithheld>
				<InvoiceTotal>1452.00</InvoiceTotal>
				<TotalOutstandingAmount>1452.00</TotalOutstandingAmount>
				<TotalExecutableAmount>1452.00</TotalExecutableAmount>
			</InvoiceTotals>
			<Items>
				<InvoiceLine>
					<ItemDescription>Servicios de consultoria</ItemDescription>
					<Quantity>1</Quantity>
					<UnitPriceWithoutTax>1200.00</UnitPriceWithoutTax>
					<TotalCost>1200.00</TotalCost>
					<GrossAmount>1200.00</GrossAmount>
					<TaxesOutputs>
						<Tax>
							<TaxTypeCode>01</TaxTypeCode>
							<TaxRate>21.00</TaxRate>
							<TaxableBase><TotalAmount>1200.00</TotalAmount></TaxableBase>
							<TaxAmount><TotalAmount>252.00</TotalAmount></TaxAmount>
						</Tax>
					</TaxesOutputs>
				</InvoiceLine>
			</Items>
			<PaymentDetails>
				<Installment>
					<InstallmentDueDate>2026-02-14</InstallmentDueDate>
					<InstallmentAmount>1452.00</InstallmentAmount>
					<PaymentMeans>04</PaymentMeans>
				</Installment>
			</PaymentDetails>
		</Invoice>
	</Invoices>
</fe:Facturae>

See the POST /invoices API reference for the full request schema.

Last updated on