Enviar registro de facturación

Authorizations

X-Qbikode-ClientApiKey

string

header

required

API-KEY de la empresa que hace la petición. Este dato se puede consultar en el panel web, accediendo a la sección Empresas y accediendo a la ficha de la empresa en.

Body

application/json

sif_id

string<uuid>

required

ID del SIF que se quiere utilizar para el envío de la factura. Los SIFs se pueden registrar en el panel web de KubiFACTU.

Un SIF puede procesar registros de facturación de diferentes empresas.

Una empresa puede tener uno o varios SIFs. Por ejemplo, una empresa con varias tiendas puede operar con un SIF por cada establecimiento, de forma que el encadenamiento/trazabilidad de las facturas se trate por separado.

Example:

"9db0bca1-187e-4cf4-b87c-96f2044008d7"

invoice_type_key

enum<string>

required

Especificación del tipo de factura: factura completa, factura simplificada, factura emitida en sustitución de facturas simplificadas o factura rectificativa.

F1: Factura (art. 6, 7.2 y 7.3 del RD 1619/2012).
F2: Factura Simplificada y Facturas sin identificación del destinatario art. 6.1.d) RD 1619/2012.
F3: Factura emitida en sustitución de facturas simplificadas facturadas y declaradas.
R1: Factura Rectificativa (Error fundado en derecho y Art. 80 Uno Dos y Seis LIVA)
R2: Factura Rectificativa (Art. 80.3)
R3: Factura Rectificativa (Art. 80.4)
R4: Factura Rectificativa (Resto)
R5: Factura Rectificativa en facturas simplificadas

Available options:

F1,

F2,

F3,

R1,

R2,

R3,

R4,

R5

Example:

"F1"

sender_data

object

required

Información referente al emisor de la factura.

Show child attributes

sender_data.company_name

string

required

Nombre de la empresa emisora.

sender_data.tax_id_number

string

required

NIF/CIF de la empresa emisora.

full_invoice_number

string

required

Serie+Nº Factura que identifica a la factura emitida. Sólo puedo contener caracteres ASCII del 32 a 126 (caracteres imprimibles). Ejemplo: 2025-00001.

Example:

"2025-00001"

fiscal_year

integer

required

Ejercicio fiscal en el que se emite la factura. Aunque este dato no se envía a la AEAT, se utiliza junto con el sif_id para verificar que no se están duplicando los números de factura.

Example:

2025

issue_date

string<date>

required

Fecha de expedición del registro de facturación.

No puede ser una fecha futura.

Example:

"2025-09-15"

operation_description

string

required

Descripción del objeto de la factura.

lines

object[]

required

Desglose de la factura con la lista de los conceptos facturados agrupados por condición fiscal completa. El número máximo de líneas es de 12.

El desglose debe agruparse por condición fiscal completa: tax_rate + vat_tax_regime_key o igic_tax_regime_key + equalization_tax_rate (si aplica). Esta agrupación responde a la condición fiscal de la operación, y no puede realizarse únicamente por tipo impositivo.

A modo de ejemplo, indicar lo siguiente:

Caso 1: Factura con todas las líneas al 21%

Si las líneas al 21% se acogen a regímenes diferentes, deben generarse múltiples agrupaciones en el desglose, cada una con su combinación única de tax_rate + vat_tax_regime_key o igic_tax_regime_key + equalization_tax_rate (si aplica).

Ejemplo válido:

Línea 1: 21%, régimen general
Línea 2: 21%, régimen criterio de caja

El desglose debe contener dos entradas distintas, ambas con tipo 21%, pero con claves de régimen diferentes.

Caso 2: Factura con líneas al 21% y al 10%

Se pueden informar más de una clave de régimen por cada tipo impositivo, siempre que existan líneas que lo justifiquen.

Ejemplo válido:

Línea 1: 21%, régimen general
Línea 2: 21%, régimen especial agencias
Línea 3: 10%, régimen general

El desglose incluirá tres agrupaciones:

21% + régimen general
21% + régimen especial agencias
10% + régimen general

Maximum array length: 12

Show child attributes

lines.tax_type_key

enum<string>

required

Impuesto de aplicación. Los valores posibles son:

01: Impuesto sobre el Valor Añadido (IVA).
02: Impuesto sobre la Producción, los Servicios y la Importación (IPSI) de Ceuta y Melilla.
03: Impuesto General Indirecto Canario (IGIC).
05: Otros.

Available options:

01,

02,

03,

05

lines.vat_tax_regime_key

enum<string>

required

Clave que identificará el tipo de régimen del impuesto o una operación con trascendencia tributaria en el contexto del IVA. Este campo no debe incluirse si se está incluyendo igic_tax_regime_key o tax_type_key tiene un valor diferente de 01. Los valores posibles son:

01: Operación de régimen general.
02: Exportación.
03: Operaciones a las que se aplique el régimen especial de bienes usados, objetos de arte, antigüedades y objetos de colección.
04: Régimen especial del oro de inversión.
05: Régimen especial de las agencias de viajes.
06: Régimen especial grupo de entidades en IVA (Nivel Avanzado).
07: Régimen especial del criterio de caja.
08: Operaciones sujetas al IPSI / IGIC (Impuesto sobre la Producción, los Servicios y la Importación / Impuesto General Indirecto Canario).
09: Facturación de las prestaciones de servicios de agencias de viaje que actúan como mediadoras en nombre y por cuenta ajena (D.A.4ª RD1619/2012).
10: Cobros por cuenta de terceros de honorarios profesionales o de derechos derivados de la propiedad industrial, de autor u otros por cuenta de sus socios, asociados o colegiados efectuados por sociedades, asociaciones, colegios profesionales u otras entidades que realicen estas funciones de cobro.
11: Operaciones de arrendamiento de local de negocio.
14: Factura con IVA pendiente de devengo en certificaciones de obra cuyo destinatario sea una Administración Pública.
15: Factura con IVA pendiente de devengo en operaciones de tracto sucesivo.
17: Operación acogida a alguno de los regímenes previstos en el Capítulo XI del Título IX (OSS e IOSS).
18: Recargo de equivalencia.
19: Operaciones de actividades incluidas en el Régimen Especial de Agricultura, Ganadería y Pesca (REAGYP).
20: Régimen simplificado.

Available options:

01,

02,

03,

04,

05,

06,

07,

08,

09,

10,

11,

14,

15,

17,

18,

19,

20

lines.igic_tax_regime_key

enum<string>

required

Clave que identificará el tipo de régimen del impuesto o una operación con trascendencia tributaria en el contexto del IGIC. Este campo no debe incluirse se se está incluyendo vat_tax_regime_key. Los valores posibles son:

01: Operación de régimen general.
02: Exportación.
03: Operaciones a las que se aplique el régimen especial de bienes usados, objetos de arte, antigüedades y objetos de colección.
04: Régimen especial del oro de inversión.
05: Régimen especial de las agencias de viajes.
06: Régimen especial grupo de entidades en IGIC (Nivel Avanzado).
07: Régimen especial del criterio de caja.
08: Operaciones sujetas al IPSI / IVA (Impuesto sobre la Producción, los Servicios y la Importación / Impuesto sobre el Valor Añadido).
09: Facturación de las prestaciones de servicios de agencias de viaje que actúan como mediadoras en nombre y por cuenta ajena (D.A.4ª RD1619/2012).
10: Cobros por cuenta de terceros de honorarios profesionales o de derechos derivados de la propiedad industrial, de autor u otros por cuenta de sus socios, asociados o colegiados efectuados por sociedades, asociaciones, colegios profesionales u otras entidades que realicen estas funciones de cobro.
11: Operaciones de arrendamiento de local de negocio.
14: Factura con IGIC pendiente de devengo en certificaciones de obra cuyo destinatario sea una Administración Pública.
15: Factura con IGIC pendiente de devengo en operaciones de tracto sucesivo.
17: Régimen especial de comerciante minorista.
18: Régimen especial del pequeño empresario o profesional.
19: Operaciones interiores exentas por aplicación artículo 25 Ley 19/1994.

Available options:

01,

02,

03,

04,

05,

06,

07,

08,

09,

10,

11,

14,

15,

17,

18,

19

lines.operation_type_key

enum<string>

required

Código que identifica el tipo de operación según su sujeción o exención tributaria. Los valores posibles son:

S1: Operación Sujeta y No exenta - Sin inversión del sujeto pasivo.
S2: Operación Sujeta y No exenta - Con Inversión del sujeto pasivo.
N1: Operación No Sujeta artículo 7, 14, otros.
N2: Operación No Sujeta por Reglas de localización.

Available options:

S1,

S2,

N1,

N2

lines.tax_base

number<decimal>

required

Magnitud dineraria sobre la que se aplica el tipo impositivo/importe no sujeto. Valor con 12 dígitos en la parte entera y 2 decimales. Ejemplo: 200.00.

Example:

200

lines.exemption_cause_key

enum<string>

Causa de la exención. Los valores posibles son:

E1: Exenta por el artículo 20.
E2: Exenta por el artículo 21.
E3: Exenta por el artículo 22.
E4: Exenta por los artículos 23 y 24.
E5: Exenta por el artículo 25.
E6: Exenta por otros.

Available options:

E1,

E2,

E3,

E4,

E5,

E6

lines.tax_base_at_cost

number<decimal>

Magnitud dineraria sobre la que se aplica el tipo impositivo en régimen especial de grupos nivel avanzado. Valor con 12 dígitos en la parte entera y 2 decimales. Ejemplo: 100.00.

lines.tax_rate

number<decimal>

Porcentaje aplicado sobre la base imponible para calcular la cuota. Valor con 3 dígitos en la parte entera y 2 decimales. Ejemplo: 21.00.

Example:

21

lines.tax_quota

number<decimal>

Cuota resultante de aplicar a la base imponible el tipo impositivo. Valor con 12 dígitos en la parte entera y 2 decimales. Ejemplo: 42.00.

Example:

42

lines.equalization_tax_rate

number<decimal>

Tipo de recargo de equivalencia asociado en función del impuesto y tipo impositivo. Valor con 3 dígitos en la parte entera y 2 decimales. Ejemplo: 5.20.

Example:

5.2

lines.equalization_tax_quota

number<decimal>

Cuota de resultante de aplicar a la base imponible el tipo de recargo de equivalencia. Valor con 12 dígitos en la parte entera y 2 decimales. Ejemplo: 10.40.

Example:

10.4

total_quota

number<decimal>

required

Importe total de la cuota (sumatorio de la cuota repercutida y cuota de recargo de equivalencia) de la factura. Valor con 12 dígitos en la parte entera y 2 decimales. Ejemplo: 33.57.

total_amount

number<decimal>

required

Importe total de la factura. Ʃ(tax_base + tax_quota + equalization_tax_quota) de todas las líneas de detalle de desglose (agrupación lines). Valor con 12 dígitos en la parte entera y 2 decimales. Ejemplo: 2450.75.

client_invoice_id

string

Identificador único de la factura dentro del sistema del cliente. Si se envía y ya existe una factura con ese mismo client_invoice_id para la empresa actual, no se generará una nueva factura: el sistema devolverá directamente la factura existente.

Maximum string length: 50

Example:

"96f2044008d7iujfd78jspo4"

callback_url

string<url>

Sólo aplicable a facturas diferidas. URL a la que se llamará con el resultado de la AEAT al procesamiento del registro de facturación.

Se hará una petición POST a esta URL y se enviarán un array en formato JSON con los datos de las facturas procesadas cuyos ítems contendrán los siguientes campos:

id: string. Identificador de KubiFACTU para el registro de facturación.
client_invoice_id: string|null. Identificador del cliente para el registro de facturación.
record_type: string (creation|cancellation). Tipo de registro de facturación.
sif_id: string. ID del SIF utilizado para la creación del registro.
sender_company_name: string. Nombre de la empresa emisira.
sender_tax_id_number: string. CIF/NIF de la empresa emisora.
full_invoice_number: string. Número de factura.
fingerprint: string. Huella del registro de facturación.
vf_post_status: string. Ver valores posibles en la documentación del campo vf_post_status de la respuesta de envío de registros de facturación.
vf_record_registration_status: string. Ver valores posibles en la documentación del campo vf_record_registration_status de la respuesta de envío de registros de facturación.
has_warnings: bool. Indica si el registro contiene errores que deban ser subsanados.
vf_error_descriptions: string|null. Cadena con la descripción de los errores devueltos por Veri*Factu.
xml_contents: string|null. XML del registro de facturación enviado a Veri*Factu en formato Base64. Si el registro de facturación forma parte de un envío en diferido, el XML puede contener información sobre otros registros de facturación incluidos en el envío.

Example:

"https://www.tuempresa.com/kubifactu/callback"

recipients

object[]

Información de los receptores de la factura. Obligatorio para facturas ordinarias.

Show child attributes

recipients.company_name

string

required

Nombre de la empresa receptora.

recipients.tax_id_number

string

NIF/CIF de la empresa receptora. Este campo es obligatorio si el receptor es nacional y se identifica mediante CIF/NIF.

recipients.other_country_code

string

Código del país en formato ISO 3166-1 alpha-2. Sólo es necesario rellenarlo si el sujeto no es nacional. El código de país debe ser ES si other_tax_id_type_key es 07 (no censado). Ejemplo: DE

recipients.other_tax_id_type_key

enum<string>

Clave para identificar el tipo de documento. Los valores posibles son:

02: NIF-IVA: Número de Identificación Fiscal para IVA.
03: Pasaporte: Documento oficial que acredita la identidad y nacionalidad del portador.
04: Documento oficial de identificación expedido por el país o territorio de residencia.
05: Certificado de residencia: Documento que acredita la residencia fiscal.
06: Otro documento probatorio: Documento adicional que sirve como prueba de identidad.
07: No censado: El receptor no está registrado en el censo fiscal.

Available options:

02,

03,

04,

05,

06,

07

recipients.other_tax_id_number

string

Número de identificación en el país de residencia del destinatario de la operación de la factura expedida. Ejemplo: L74JF44L2 para una empresa de DE.

representative_company_name

string

Nombre/razón social del representante del obligado tributario. A rellenar solo en caso de que el registro de facturación remitido haya sido generado por un representante/asesor del obligado tributario.

representative_tax_id_number

string

NIF del representante del obligado tributario. A rellenar solo en caso de que el registro de facturación remitido haya sido generado por un representante/asesor del obligado tributario.

previous_rejection_key

enum<string>

Indica si el registro que se envía corresponde a una subsanación de un envío anterior rechazado por la AEAT.

X: El registro se reenvía porque el envío anterior fue rechazado (no llegó a registrarse en la AEAT). Solo puede informarse cuando correction_key = S. Se utiliza al reenviar una factura previamente rechazada para que la AEAT la procese como una corrección del intento fallido, sin alterar los datos originales de emisión ni generar una nueva factura.
N: No, se trata de un alta normal/inicial.

Available options:

X,

N

correction_key

enum<string>

Indicador que especifica que se trata de una subsanación de un registro de facturación de alta previamente generado y exitente en la AEAT. El contenido de este nuevo registro de facturación es el correcto y el que deberá tenerse en cuenta. Si no se informa este campo, se entenderá que tiene valor N (alta normal/inicial).

S: Sí, se trata de una subsanación de un registro de facturación anterior que existe en la AEAT.
N: No, se trata de un alta normal/inicial.

Available options:

S,

N

operation_date

string<date>

Fecha en la que se ha realizado la operación, siempre que sea diferente a la fecha de expedición. Determina el ejercicio y periodo fiscal al que pertenece la operación."

Formato yyyy-mm-dd.

Example:

"2025-02-26"

simplified_invoice_key

enum<string>

Factura simplificada Articulo 7.2 Y 7.3 RD 1619/2012.

Si no se informa este campo se entenderá que tiene valor N.

Sólo se podrá rellenar con S si invoice_type_key es F1, F3, R1, R2, R3 o R4.

S: Sí
N: No

Available options:

S,

N

without_recipient_identification_key

enum<string>

Factura sin identificación del destinatario según el artículo 6.1.d del RD 1619/2012.

Si no se informa este campo, se entenderá que tiene valor "N".

Sólo se podrá rellenar con "S" si invoice_type_key es F2 o R5.

S: Sí
N: No

Available options:

S,

N

macrodata_key

enum<string>

Identificador que especifica aquellas facturas con base o importe >= |100.000.000,00| (valor absoluto).

Si no se informa este campo, se entenderá que tiene valor "N".

Sólo se podrá rellenar con "S" si invoice_type_key es F2 o R5.

S: Sí
N: No

Available options:

S,

N

issued_by_third_party_or_recipient_key

enum<string>

Identificador que especifica si la factura ha sido expedida materialmente por un tercero o por el destinatario (contraparte).

Si es igual a T (tercero), el bloque third_party_data será de cumplimentación obligatoria.
Si es igual a D (destinatario), el bloque recipients será de cumplimentación obligatoria.
T: Tercero
D: Destinatario

Available options:

T,

D

third_party_data

object

Información del tercero que expide la factura.

Show child attributes

third_party_data.company_name

string

required

Nombre de la empresa del tercero que expide la factura.

third_party_data.tax_id_number

string

NIF/CIF de la empresa. Este campo es obligatorio si el tercero que expide la factura es nacional y se identifica mediante CIF/NIF

third_party_data.other_country_code

string

third_party_data.other_tax_id_type_key

enum<string>

Clave para identificar el tipo de documento. Los valores posibles son:

02: NIF-IVA: Número de Identificación Fiscal para IVA.
03: Pasaporte: Documento oficial que acredita la identidad y nacionalidad del portador.
04: Documento oficial de identificación expedido por el país o territorio de residencia.
05: Certificado de residencia: Documento que acredita la residencia fiscal.
06: Otro documento probatorio: Documento adicional que sirve como prueba de identidad.
07: No censado: El receptor no está registrado en el censo fiscal.

Available options:

02,

03,

04,

05,

06,

07

third_party_data.other_tax_id_number

string

Número de identificación, en el país de residencia del tercero que expide la factura. Ejemplo: L74JF44L2 para una empresa de DE.

rectificative_type_key

enum<string>

Campo que identifica si el tipo de factura rectificativa es por sustitución o por diferencias.

S: Por sustitución.
I: Por diferencias.

Available options:

S,

I

rectified_tax_base

number<decimal>

Base imponible rectificada. Valor con 12 dígitos en la parte entera y 2 decimales. Ejemplo: 2500.55.

Example:

2500.55

rectified_tax_quota

number<decimal>

Cuota de impuesto rectificada. Valor con 12 dígitos en la parte entera y 2 decimales. Ejemplo: 42.30.

Example:

42.3

rectified_equalization_tax_quota

number<decimal>

Cuota de recargo de equivalencia rectificada. Valor con 12 dígitos en la parte entera y 2 decimales. Ejemplo: 5.20.

Example:

5.2

rectified_invoices

object[]

Lista de facturas que se están rectificando.

Show child attributes

rectified_invoices.tax_id_number

string

required

NIF/CIF de la empresa emisora de la factura que quiere rectificar.

rectified_invoices.full_invoice_number

string

required

Serie+Nº Factura que identifica a la factura que se quiere rectificar. Ejemplo: 2025-00001.

rectified_invoices.issue_date

string<date>

required

Fecha de expedición de la factura que se quiere rectificar en formato yyyy-mm-dd. Ejemplo: 2025-02-26.

Example:

"2025-02-26"

substituted_invoices

object[]

Lista de facturas que se quieren sustituir.

Sólo podrá incluirse esta agrupación cuando el campo invoice_type_key sea F3.

Show child attributes

substituted_invoices.tax_id_number

string

required

NIF/CIF de la empresa emisora de la factura que quiere rectificar.

substituted_invoices.full_invoice_number

string

required

Serie+Nº Factura que identifica a la factura que se quiere rectificar. Ejemplo: 2025-00001.

substituted_invoices.issue_date

string<date>

required

Fecha de expedición de la factura que se quiere rectificar en formato yyyy-mm-dd. Ejemplo: 2025-02-26.

Example:

"2025-02-26"

coupon_key

enum<string>

Identificador que especifica si tiene minoración de la base imponible por la concesión de cupones, bonificaciones o descuentos cuando solo se expide el original de la factura. Si no se informa este campo, se entenderá que tiene valor "N".

Sólo se podrá rellenar con "S" si invoice_type_key es R5 o R1.

Available options:

S,

N

Example:

"N"

invoicing_agreement_registration_number

string

Número de registro obtenido al enviar la autorización en materia de facturación o de libros registro a que se refiere la disposición adicional primera del Real Decreto que aprueba el Reglamento.

sif_agreement_id

string

Identificación del acuerdo (resolución) a que se refiere el artículo 5 del Reglamento.

Response

Factura enviada con éxito.

data

object

Show child attributes

data.id

string<uuid>

Identificador (ID) de la factura en el sistema de KubiFACTU. Se utiliza para hacer referencia al registro de facturación desde otros endpoints como, por ejemplo, el de anulación de facturas.

data.record_type

enum<string>

Tipo de registro de facturación:

creation: Se trata de un registro de alta.
cancellation: Se trata de un registro de anulación.

Available options:

creation,

cancellation

data.request_id

string

Identificador de la petición como referencia para el soporte técnico.

Example:

"2cc8ef846029ec69613711ad1d85f6dfebf16ffb"

data.sif_id

string<uuid>

ID del SIF utilizado para la creación del registro.

Example:

"0995C42C-6708-44FB-BFBF-B363A5FE873E"

data.fiscal_year

integer

Año fiscal de la factura.

data.full_invoice_number

string

Número de la factura registrada.

data.issue_date

string<date>

Fecha de expedición del registro de facturación.

Example:

"2025-09-15"

data.created_at

string<date-time>

Fecha y hora de creación de la factura en nuestro sistema.

Example:

"2025-09-15T07:35:24.992854Z"

data.fingerprint

string | null

Huella SHA-256 del registro de facturación registrado.

data.csv

string | null

Código Seguro de Verificación del registro de facturación.

data.vf_post_status

enum<string> | null

Este campo indica si la factura ha sido enviada a Veri*Factu, pero no indica si el registro ha sido aceptado. Los valores posibles son:

success: Se ha realizado el envío a Veri*Factu.
failure: No se ha podido hacer el envío a Veri*Factu.

Available options:

success,

failure

data.vf_record_registration_status

enum<string> | null

Valores posibles para el campo vf_record_registration_status, que indican el estado del registro en Veri*Factu.

success: El registro ha sido correctamente registrado en Veri*Factu.
accepted_with_errors: El registro ha sido registrado en Veri*Factu, pero tiene errores que deben ser subsanados.
failed: El registro tiene errores no aceptables y ha sido rechazado por Veri*Factu.
not_registered: No se ha encontrado el registro en Veri*Factu.
cancelled: El registro está anulado.
unknown: Se desconoce el estado del registro.

Available options:

success,

accepted_with_errors,

failed,

not_registered,

cancelled,

unknown

data.has_warnings

boolean

Indica si el registro contiene errores que deban ser subsanados.

Example:

false

data.vf_error_descriptions

string | null

Cadena con la descripción de los errores devueltos por Veri*Factu.

data.next_request_waiting_time

integer

Tiempo que se debe esperar en segundos para que la empresa cliente pueda enviar una nueva petición.

data.next_request_datetime

string<date-time>

Fecha y hora en la que la empresa cliente pueda enviar una nueva petición en formato ISO-8601 (ej.- 1977-04-22T06:00:00Z) con zona horaria UTC.

Example:

"1977-04-22T06:00:00Z"

data.qr_value

string<uri> | null

URL que debe mostrarse en el QR de las facturas procesadas con VeriFactu. Esta URL sirve para que el receptor de la factura pueda validar que esta ha sido correctamente enviada a VeriFactu. Este campo será null cuando Veri*Factu rechace el registro de facturación.

data.qr_image

string<byte> | null

Imagen del QR (PNG) en formato Base64. Este campo será null cuando Veri*Factu rechace el registro de facturación.

data.xml_contents

string<byte> | null

XML del registro de facturación en formato Base64. Cuando la factura sea enviada en diferido este campo será null, ya que la generación del XML se realiza cuando llegue el momento de enviar el registro a VeriFactu. Además, si el registro de facturación forma parte de un envío en diferido, el XML puede contener información sobre otros registros de facturación incluidos en el envío.

API Reference

Authorizations

Body

Caso 1: Factura con todas las líneas al 21%

Caso 2: Factura con líneas al 21% y al 10%

Response