SII API documentation

  Here you will find the technical documentation for our API to submit the issued-invoices book to the Agencia Estatal de Administración Tributaria (AEAT) in accordance with the Suministro Inmediato de Información (SII, immediate supply of information).

Other

`GET` /sii/health

API status

Returns the API key status: use it to check that the API is up and which NIF, environment and tax authority it belongs to.

Responses

Status	Description
`200`	API status
`401`	Missing or invalid API key.
`403`	The NIF linked to the API key is deactivated.

`GET` /sii/status

Record status

Returns the status of a record (registration, modification or cancellation) from the <code>uuid</code> returned when it was created.

Responses

Status	Description
`200`	Record status
`400`	The uuid is missing.
`401`	Missing or invalid API key.
`403`	The NIF linked to the API key is deactivated.
`404`	There is no record with that uuid for this NIF.

`POST` /sii/create

Create new invoice

Creates the registration record (A0) of an issued invoice in the issued-invoices book.

Request body

Field	Type	Required	Description
`ejercicio`	string	yes	Year of the tax period in which the invoice is reported (4 digits).
`periodo`	string	yes	Tax period: a month (01 to 12) or, for quarterly filers, a quarter (1T to 4T).
`serie`	string	yes	Invoice series. May be empty.
`numero`	string	yes	Invoice number.
`numero_fin`	string	no	Only in summary entries (F4), and required there: number of the last invoice of the range, in the same series.
`fecha_expedicion`	string	yes	Issue date. It cannot be later than today or earlier than 20 years ago.
`tipo_factura`	string	yes	Invoice type:<ul style="list-style: disc;"><li>F1: full invoice</li><li>F2: simplified invoice</li><li>F3: invoice replacing simplified invoices</li><li>F4: summary entry of invoices</li><li>R1: corrective (error founded in law and art.
`tipo_rectificativa`	string	no	Required in corrective invoices (R1 to R5), and only there: S by substitution, I by differences.
`facturas_rectificadas`	array	no	Invoices being corrected.
`facturas_sustituidas`	array	no	Simplified invoices that this invoice replaces.
`importe_rectificativa`	object	no	Amounts of the corrected invoice.
`fecha_operacion`	string	no	Transaction date, if different from the issue date.
`clave_regimen`	array	yes	Special regime or relevance keys of the invoice, 1 to 3: the first one is the main key.
`importe_total`	string	no	Invoice total amount.
`base_imponible_a_coste`	string	no	Taxable base at cost.
`descripcion`	string	yes	Description of the transaction (up to 500 characters).
`importe_transmision_inmuebles_sujeto_iva`	string	no	Amount of the transfer of real estate subject to VAT.
`inmuebles`	array	no	Rented properties, 1 to 15.
`nombre`	string	no	Name or company name of the counterparty.
`nif`	string	no	Spanish NIF of the counterparty.
`id_otro`	object	no	Identification of a counterparty without a Spanish NIF.
`nif_representante`	string	no	NIF of the counterparty's representative, if any.
`validar_destinatario`	boolean	no	If you send <code>nif</code>, by default we check that the counterparty is in the AEAT census, and with <code>id_otro</code> of type 02 that the VAT number is in the VIES census, because otherwise the AEAT rejects the invoice.
`especial`	object	no	Special-case flags.
`desglose`	object	yes	Invoice breakdown, with the SII's structure.

Responses

Status	Description
`200`	Valid invoice, queued
`400`	Error in the request data.
`401`	Missing or invalid API key.
`403`	The NIF linked to the API key is deactivated.
`500`	Server error. The record is not created; retry later.

`POST` /sii/create_bulk

Create invoices in bulk

This endpoint creates up to 500 registration records (A0) in a single call.

Responses

Status	Description
`200`	Valid invoices, queued
`400`	Error in the request data: the body is not an array, it has more than 500 invoices or an invoice has an error.
`401`	Missing or invalid API key.
`403`	The NIF linked to the API key is deactivated.
`500`	Server error. The record is not created; retry later.

`PUT` /sii/modify

Modify invoice

Creates a modification record (A1), which replaces the whole record the AEAT holds for the invoice.

Request body

Field	Type	Required	Description
`ejercicio`	string	yes	Year of the tax period in which the invoice is reported (4 digits).
`periodo`	string	yes	Tax period: a month (01 to 12) or, for quarterly filers, a quarter (1T to 4T).
`serie`	string	yes	Invoice series. May be empty.
`numero`	string	yes	Invoice number.
`numero_fin`	string	no	Only in summary entries (F4), and required there: number of the last invoice of the range, in the same series.
`fecha_expedicion`	string	yes	Issue date. It cannot be later than today or earlier than 20 years ago.
`tipo_factura`	string	yes	Invoice type:<ul style="list-style: disc;"><li>F1: full invoice</li><li>F2: simplified invoice</li><li>F3: invoice replacing simplified invoices</li><li>F4: summary entry of invoices</li><li>R1: corrective (error founded in law and art.
`tipo_rectificativa`	string	no	Required in corrective invoices (R1 to R5), and only there: S by substitution, I by differences.
`facturas_rectificadas`	array	no	Invoices being corrected.
`facturas_sustituidas`	array	no	Simplified invoices that this invoice replaces.
`importe_rectificativa`	object	no	Amounts of the corrected invoice.
`fecha_operacion`	string	no	Transaction date, if different from the issue date.
`clave_regimen`	array	yes	Special regime or relevance keys of the invoice, 1 to 3: the first one is the main key.
`importe_total`	string	no	Invoice total amount.
`base_imponible_a_coste`	string	no	Taxable base at cost.
`descripcion`	string	yes	Description of the transaction (up to 500 characters).
`importe_transmision_inmuebles_sujeto_iva`	string	no	Amount of the transfer of real estate subject to VAT.
`inmuebles`	array	no	Rented properties, 1 to 15.
`nombre`	string	no	Name or company name of the counterparty.
`nif`	string	no	Spanish NIF of the counterparty.
`id_otro`	object	no	Identification of a counterparty without a Spanish NIF.
`nif_representante`	string	no	NIF of the counterparty's representative, if any.
`validar_destinatario`	boolean	no	If you send <code>nif</code>, by default we check that the counterparty is in the AEAT census, and with <code>id_otro</code> of type 02 that the VAT number is in the VIES census, because otherwise the AEAT rejects the invoice.
`especial`	object	no	Special-case flags.
`desglose`	object	yes	Invoice breakdown, with the SII's structure.

Responses

Status	Description
`200`	Valid modification, queued
`400`	Error in the request data.
`401`	Missing or invalid API key.
`403`	The NIF linked to the API key is deactivated.
`500`	Server error. The record is not created; retry later.

`POST` /sii/cancel

Cancel invoice

Cancels an invoice the AEAT has registered, through an SII cancellation (baja) record.

Request body

Field	Type	Required	Description
`ejercicio`	string	yes	Year of the tax period of the original record (or of its last modification).
`periodo`	string	yes	Tax period of the original record (or of its last modification).
`serie`	string	yes	Invoice series. May be empty.
`numero`	string	yes	Invoice number. In a summary entry (F4), the first one of the range.
`fecha_expedicion`	string	yes	Issue date of the invoice.

Responses

Status	Description
`200`	Valid cancellation, queued
`400`	Error in the request data.
`401`	Missing or invalid API key.
`403`	The NIF linked to the API key is deactivated.
`500`	Server error. The record is not created; retry later.

`POST` /sii/list

List invoices

Queries the AEAT for the book's invoices of a tax period and returns those sent from this Verifacti NIF.

Request body

Field	Type	Required	Description
`ejercicio`	string	yes	Year of the tax period in which the invoice is reported (4 digits).
`periodo`	string	yes	Tax period: 01 to 12 or 1T to 4T.
`token`	string	no	Token of the previous page, to ask for the next one.

Responses

Status	Description
`200`	Invoices of the period
`400`	Error in the request data.
`401`	Missing or invalid API key.
`403`	The NIF linked to the API key is deactivated.
`502`	The AEAT query could not be completed.

`POST` /sii/export

Export XMLs

Returns signed URLs to download the XMLs sent to the AEAT in a month of submission (each submission with its response, <code>_req.xml</code> and <code>_res.xml</code>).

Request body

Field	Type	Required	Description
`ejercicio`	string	yes	Year of submission.
`periodo`	string	yes	Month of submission, 1 to 12.
`token`	string	no	Token of the previous page.

Responses

Status	Description
`200`	Download URLs
`400`	ejercicio or periodo is missing, or periodo is not a month.
`401`	Missing or invalid API key.
`403`	The NIF linked to the API key is deactivated.

SII API documentation

Other

GET /sii/health

Responses

GET /sii/status

Responses

POST /sii/create

Request body

Responses

POST /sii/create_bulk

Responses

PUT /sii/modify

Request body

Responses

POST /sii/cancel

Request body

Responses

POST /sii/list

Request body

Responses

POST /sii/export

Request body

Responses

`GET` /sii/health

`GET` /sii/status

`POST` /sii/create

`POST` /sii/create_bulk

`PUT` /sii/modify

`POST` /sii/cancel

`POST` /sii/list

`POST` /sii/export