Send invoice
- The destination format (Facturae), through the country's invoicing API.
- The A-Cube standard CSV or UBL, through SFTP or the file upload API using A-Cube Transfer. Transfer converts your files to Facturae.
- Your own format, the files your ERP already exports, with A-Cube Transfer. A-Cube builds the conversion to Facturae during onboarding.
Ask A-Cube to activate A-Cube Transfer and confirm your format and file upload API access for this destination before the first upload.
The outbound module builds the billing record for an invoice issued by one of your registered legal entities and, in the same flow, reports it to AEAT under VERI*FACTU. There are two ways in: submit a finished invoice directly, or build it as a draft first and submit it when it is ready.
For the payload structure and a full example, see Formats.
Input format
POST /invoices, POST /invoices/draft and PUT /invoices/draft/{uuid} all accept the
Facturae 3.2.2 document in either representation, or a native VERI*FACTU billing
record, selected by the Content-Type header and, for XML, by the root element of the
document:
Content-Type | Body |
|---|---|
application/xml | the Facturae XML document (<fe:Facturae> root), or a native VERI*FACTU <RegistroAlta> XML with the business data of the record, see Native VERI*FACTU format |
application/json | an equivalent JSON object whose keys mirror the Facturae element names (repeated elements such as Invoice, Tax, InvoiceLine, Installment become JSON arrays) |
Facturae JSON is converted to Facturae XML before processing, so both Facturae paths
run the exact same validation and produce the same result. Only single-invoice
Facturae documents are accepted; a batch / lote (Modality L, multiple Invoice
entries) is rejected with 422.
To issue a simplified invoice (F2, without recipient), use the dedicated endpoints
described in Simplified invoices.
Send directly
Forward the Facturae 3.2.2 document (or the
native VERI*FACTU record)
as the request body. The platform validates it synchronously and, on success, responds 202 Accepted
with the created invoice resource, including its uuid. Store the uuid to retrieve
details and track processing.
- Submit an invoice:
POST /invoices - Fetch invoice details:
GET /invoices/{uuid}
Request: Facturae as XML
POST /invoices
Authorization: Bearer {{jwt}}
Content-Type: application/xml
Accept: application/json
<?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>
Request: Facturae as JSON (equivalent)
POST /invoices
Authorization: Bearer {{jwt}}
Content-Type: application/json
Accept: application/json
{
"FileHeader": {
"SchemaVersion": "3.2.2",
"Modality": "I",
"InvoiceIssuerType": "EM",
"Batch": {
"BatchIdentifier": "A58818501-FV-2026-0001",
"InvoicesCount": 1,
"TotalInvoicesAmount": { "TotalAmount": "1452.00" },
"TotalOutstandingAmount": { "TotalAmount": "1452.00" },
"TotalExecutableAmount": { "TotalAmount": "1452.00" },
"InvoiceCurrencyCode": "EUR"
}
},
"Parties": {
"SellerParty": {
"TaxIdentification": {
"PersonTypeCode": "J",
"ResidenceTypeCode": "R",
"TaxIdentificationNumber": "A58818501"
},
"LegalEntity": {
"CorporateName": "SupplierOfficialName Ltd.",
"AddressInSpain": {
"Address": "Calle Mayor 1",
"PostCode": "28001",
"Town": "Madrid",
"Province": "Madrid",
"CountryCode": "ESP"
}
}
},
"BuyerParty": {
"TaxIdentification": {
"PersonTypeCode": "J",
"ResidenceTypeCode": "R",
"TaxIdentificationNumber": "B12345674"
},
"LegalEntity": {
"CorporateName": "Buyer Official Name",
"AddressInSpain": {
"Address": "Calle Alcala 20",
"PostCode": "28014",
"Town": "Madrid",
"Province": "Madrid",
"CountryCode": "ESP"
}
}
}
},
"Invoices": {
"Invoice": [
{
"InvoiceHeader": {
"InvoiceNumber": "FV-2026-0001",
"InvoiceDocumentType": "FC",
"InvoiceClass": "OO"
},
"InvoiceIssueData": {
"IssueDate": "2026-01-15",
"InvoiceCurrencyCode": "EUR",
"TaxCurrencyCode": "EUR",
"LanguageName": "es"
},
"TaxesOutputs": {
"Tax": [
{
"TaxTypeCode": "01",
"TaxRate": "21.00",
"TaxableBase": { "TotalAmount": "1200.00" },
"TaxAmount": { "TotalAmount": "252.00" }
}
]
},
"InvoiceTotals": {
"TotalGrossAmount": "1200.00",
"TotalGeneralDiscounts": "0.00",
"TotalGeneralSurcharges": "0.00",
"TotalGrossAmountBeforeTaxes": "1200.00",
"TotalTaxOutputs": "252.00",
"TotalTaxesWithheld": "0.00",
"InvoiceTotal": "1452.00",
"TotalOutstandingAmount": "1452.00",
"TotalExecutableAmount": "1452.00"
},
"Items": {
"InvoiceLine": [
{
"ItemDescription": "Servicios de consultoria",
"Quantity": "1",
"UnitPriceWithoutTax": "1200.00",
"TotalCost": "1200.00",
"GrossAmount": "1200.00",
"TaxesOutputs": {
"Tax": [
{
"TaxTypeCode": "01",
"TaxRate": "21.00",
"TaxableBase": { "TotalAmount": "1200.00" },
"TaxAmount": { "TotalAmount": "252.00" }
}
]
}
}
]
},
"PaymentDetails": {
"Installment": [
{
"InstallmentDueDate": "2026-02-14",
"InstallmentAmount": "1452.00",
"PaymentMeans": "04"
}
]
}
}
]
}
}
Request: native VERI*FACTU RegistroAlta (equivalent)
POST /invoices
Authorization: Bearer {{jwt}}
Content-Type: application/xml
Accept: application/json
<RegistroAlta>
<IDFactura>
<IDEmisorFactura>A58818501</IDEmisorFactura>
<NumSerieFactura>FV-2026-0001</NumSerieFactura>
<FechaExpedicionFactura>15-01-2026</FechaExpedicionFactura>
</IDFactura>
<NombreRazonEmisor>SupplierOfficialName Ltd.</NombreRazonEmisor>
<TipoFactura>F1</TipoFactura>
<DescripcionOperacion>Servicios de consultoria</DescripcionOperacion>
<Destinatarios>
<IDDestinatario>
<NombreRazon>Buyer Official Name</NombreRazon>
<NIF>B12345674</NIF>
</IDDestinatario>
</Destinatarios>
<Desglose>
<DetalleDesglose>
<TipoImpositivo>21.00</TipoImpositivo>
<BaseImponibleOimporteNoSujeto>1200.00</BaseImponibleOimporteNoSujeto>
<CuotaRepercutida>252.00</CuotaRepercutida>
</DetalleDesglose>
</Desglose>
<CuotaTotal>252.00</CuotaTotal>
<ImporteTotal>1452.00</ImporteTotal>
</RegistroAlta>
A native record carries no due date, so dueDate is null in the response.
Sample response (202 Accepted)
The response is the same regardless of the input format. The AEAT response fields
(aeatErrorCode, sendAttempts, …) are described in
Invoice lifecycle.
{
"uuid": "01a03e4a-ee3a-7e1f-b372-c8382bd4ec73",
"invoiceNumber": "FV-2026-0001",
"invoiceDate": "2026-01-15",
"dueDate": "2026-02-14",
"currency": "EUR",
"totalAmount": "1452.00",
"netAmount": "1200.00",
"direction": "outgoing",
"sender": { "name": "SupplierOfficialName Ltd.", "fiscalId": "A58818501" },
"recipient": { "name": "Buyer Official Name", "fiscalId": "B12345674" },
"status": "accepted",
"errorReason": null,
"aeatErrorCode": null,
"aeatErrorDescription": null,
"sendAttempts": 1,
"lastSendAttemptAt": "2026-08-26T13:38:13+00:00",
"sentWithIncident": false,
"downloaded": false,
"downloadedAt": null,
"createdAt": "2026-08-26T13:38:13+00:00",
"updatedAt": "2026-08-26T13:38:13+00:00"
}
The sender tax id must belong to a legal entity you own that has
customerInvoiceEnabled; otherwise the call is rejected with 403. Sending also
requires the ROLE_WRITER role on your token.
Send from a draft
A draft is a draft-status invoice you can create with partial content, review, amend,
and send later. Only the sender and recipient identity is required to create one:
Parties for a Facturae draft, or IDFactura/IDEmisorFactura, NombreRazonEmisor and
Destinatarios/IDDestinatario for a native VERI*FACTU draft. Drafts accept the same
Content-Type values as POST /invoices.
| Step | Call |
|---|---|
| Create | POST /invoices/draft → 201, returns uuid |
| Read | GET /invoices/draft/{uuid} |
| Amend | PUT /invoices/draft/{uuid} |
| Discard | DELETE /invoices/draft/{uuid} → 204 |
| Send | POST /invoices/draft/{uuid}/send → 202 |
A draft keeps its type: PUT /invoices/draft/{uuid} on a
simplified draft
returns 409 Conflict; amend it with PUT /invoices/draft/simplified/{uuid} instead.
POST /invoices/draft/{uuid}/send has no body and returns 202 Accepted with the
terminal status and errorReason already resolved; see
Invoice lifecycle. You can still re-fetch
GET /invoices/{uuid} at any later
point to read the current outcome.
Validation
POST /invoices and the draft endpoints validate the document before creating the
resource; the same checks apply whether you sent XML or JSON. On failure the response
is returned immediately and nothing is sent to AEAT:
| Status | Meaning |
|---|---|
400 | the JSON body cannot be parsed |
403 | the caller does not own the sender tax id, the entity is not enabled to invoice, or the token lacks ROLE_WRITER |
409 | the draft is not in draft status, or is a draft of the other type |
415 | the Content-Type is not accepted |
422 | the document is invalid: malformed XML, a missing element or wrong format, a broken AEAT rule (with the AEAT error code), a duplicate invoice, or an incomplete draft on send. The violations array points at the offending element (for example Facturae/Invoices/Invoice[0]/TaxesOutputs) |
See Validation for every error group, the AEAT rules checked, and an example response for each.
Track the outcome
Once accepted, the invoice moves through the
lifecycle states. An invoice AEAT accepts with
errors (accepted_with_errors) can be fixed with a
correction (subsanación). In the sandbox you can force
any outcome with a reserved recipient tax id.
To be notified of the outcome instead of reading it from the API, subscribe to
webhooks.
Listing
- List invoices:
GET /invoicesreturns your invoices, most recent first; see Search documents for filtering.