Enviar registro de facturación

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.

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

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

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.

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

No puede ser una fecha futura.

Descripción del objeto de la factura.

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. Se compara con la suma de las cuotas y recargos del desglose, incluso cuando el resultado es cero. Una diferencia absoluta superior a 10,00 € devuelve HTTP 422 con incorrect_total_quota (en lotes, invoices.N.incorrect_total_quota). Esta comprobación se aplica a los envíos inmediatos, diferidos y por lotes, tanto con tax_breakdown como con su alias lines. Una diferencia de exactamente 10,00 € está dentro de la tolerancia. Excepciones por régimen: si existe al menos una línea válida de IVA (tax_type_key: "01") con vat_tax_regime_key igual a 03, 05, 06, 08 o 09, de IGIC ("03") con uno de esos valores en igic_tax_regime_key, o de IPSI ("02") con ipsi_tax_regime_key: "08", se omiten las comparaciones globales de total_amount y total_quota para toda esa factura. En facturas mixtas basta una línea con uno de esos regímenes, independientemente de su posición. Es un criterio conservador de KubiFACTU para evitar falsos rechazos: no se comprueba la coherencia de ambas sumas globales ni se compara solo el subtotal de las líneas ordinarias. La documentación consultada de la AEAT no concreta este criterio para mezclas. La excepción no elimina la obligatoriedad ni la validación del formato de los totales, del desglose o de los regímenes. El impuesto 05 (Otros) no es el régimen 05 y no activa la excepción. Cada factura de un lote se evalúa por separado.

Importe total de la factura. Con carácter general se compara con Ʃ(tax_base + tax_quota + equalization_tax_quota) de todas las entradas de tax_breakdown, salvo las excepciones por régimen indicadas a continuación. Valor con 12 dígitos en la parte entera y 2 decimales. Ejemplo: 2450.75. Se compara con la suma del desglose, incluso cuando el resultado es cero. Una diferencia absoluta superior a 10,00 € devuelve HTTP 422 con incorrect_total_amount (en lotes, invoices.N.incorrect_total_amount). Esta comprobación se aplica a los envíos inmediatos, diferidos y por lotes, tanto con tax_breakdown como con su alias lines. Una diferencia de exactamente 10,00 € está dentro de la tolerancia. Excepciones por régimen: si existe al menos una línea válida de IVA (tax_type_key: "01") con vat_tax_regime_key igual a 03, 05, 06, 08 o 09, de IGIC ("03") con uno de esos valores en igic_tax_regime_key, o de IPSI ("02") con ipsi_tax_regime_key: "08", se omiten las comparaciones globales de total_amount y total_quota para toda esa factura. En facturas mixtas basta una línea con uno de esos regímenes, independientemente de su posición. Es un criterio conservador de KubiFACTU para evitar falsos rechazos: no se comprueba la coherencia de ambas sumas globales ni se compara solo el subtotal de las líneas ordinarias. La documentación consultada de la AEAT no concreta este criterio para mezclas. La excepción no elimina la obligatoriedad ni la validación del formato de los totales, del desglose o de los regímenes. El impuesto 05 (Otros) no es el régimen 05 y no activa la excepción. Cada factura de un lote se evalúa por separado. Ejemplo ilustrativo de bienes usados (IVA, régimen 03): compra de 1.000 €, venta de 1.242 €, base de 200 € y cuota de 42 €. Se declara total_amount: 1242.00 y total_quota: 42.00; la diferencia entre precio total y suma del desglose (242 €) no genera este 422. Referencia: Validaciones y errores de la AEAT, versión 1.2.2 de 08/04/2026, apartados 3.1.3.15.6, 3.1.3.16 y 3.1.3.17.

Identificador único de la factura dentro del sistema del cliente.

URL a la que KubiFACTU llama con el resultado de la AEAT cuando procesa el registro de facturación: el envío de un registro de facturación en diferido, un reenvío o una consulta. No se llama por el resultado que ya devuelve la respuesta de un envío inmediato.

Un mismo registro puede generar varios callbacks. Correlaciona cada elemento por id y procésalo de forma idempotente.

Los reintentos automáticos también llaman a esta URL, incluidos los de un envío inmediato que falló: cada nuevo retry, el paso a attention y el final de la recuperación (resolved). Por eso callback_url también sirve en los envíos inmediatos.

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 emisora.
• sender_tax_id_number: string. CIF/NIF de la empresa emisora.
• fiscal_year: integer. Año fiscal del registro de facturación.
• full_invoice_number: string. Número de factura.
• fingerprint: string|null. Huella del registro de facturación.
• csv: string|null. Código Seguro de Verificación (CSV) de la remisión que contiene el registro. Puede ser null aunque el registro esté aceptado: para saber si está acreditado, usa vf_record_registration_status, no la presencia del csv. Leer más en la FAQ.
• vf_post_status: string|null. 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|null. 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.
• vf_response_body: string|null. Cuerpo de la respuesta de Veri*Factu en formato Base64. Contiene el XML completo devuelto por la AEAT tras el envío del registro de facturación.
• xml_url: string|null. URL para descargar el XML del registro de facturación enviado a Veri*Factu mediante el endpoint Descargar XML del registro de facturación. Será null si el XML aún no está disponible.
• qr_value: string|null. URL del código QR para validación de la factura en Veri*Factu. Será null si el registro fue rechazado o no aplica mostrar QR.
• qr_image_url: string|null. URL para descargar la imagen PNG del código QR generado por KubiFACTU mediante el endpoint Descargar imagen QR del registro de facturación. Será null si el registro fue rechazado o no aplica mostrar QR.
• recovery: object o null. Siempre presente. Vale null si la recuperación automática no sigue el registro; en ese caso puedes ignorarlo. Mismo formato que el campo recovery de la respuesta de envío de registros de facturación.

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.

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.

Indicador de rechazo previo que, en las subsanaciones, distingue si la factura ya está registrada en la AEAT o si se subsana sin registro previo.

En una subsanación se informa correction_key = S y se utiliza el valor de previous_rejection_key que corresponda a la situación de la factura en la AEAT.

Un rechazo no debe confundirse con un error técnico en el envío (timeout, error de red, fallo del servicio, ausencia de respuesta, error SOAP técnico, etc.) que tendrá el campo vf_post_status = failure. En esos casos el registro no se considera rechazado, y debe reenviarse exactamente igual, sin modificar datos y sin informar correction_key ni previous_rejection_key. Ver más información al respecto.

Los errores SOAP causados por el NIF o el nombre del obligado a emitir o del representante (códigos 4104, 4105, 4107, 4109, 4115, 4116, 4117, 4123 y 4124) sí son un rechazo: se guardan con vf_post_status = success y vf_record_registration_status = failed, porque reenviar los mismos datos no los resuelve. Corrige los datos y subsana con correction_key = S y previous_rejection_key = X. Ver más información al respecto.

• X: El alta inicial fue rechazada y la factura no está registrada en la AEAT. También corresponde a las operativas especiales de subsanación sin registro previo. Solo puede informarse cuando correction_key = S; no significa simplemente que el último envío fue rechazado.
• S: La factura ya está registrada en la AEAT, pero una subsanación posterior fue rechazada. Solo puede informarse cuando correction_key = S.
• N u omitido: En una subsanación habitual de una factura ya registrada en la AEAT, se informa correction_key = S. También corresponde a un alta normal/inicial, sin subsanación.

Con correction_key = S y previous_rejection_key = X, la API busca en KubiFACTU un registro de alta de la misma factura (mismo número y mismo ejercicio o fecha de expedición, en la misma empresa cliente) y devuelve HTTP 422 con el error en previous_rejection_key si ese registro:

• Está registrado en la AEAT (vf_record_registration_status = success, accepted_with_errors o cancelled). La AEAT rechazaría la subsanación como registro duplicado (código 3000), porque con X la factura no debe existir previamente en la AEAT. No envíes X: para corregir el contenido del registro aceptado, envía la subsanación con previous_rejection_key = N.
• Está pendiente de envío a la AEAT. Espera a conocer su resultado, mediante callback_url o consultando el registro, antes de decidir cómo subsanarlo.

X sigue admitiéndose cuando el alta original fue rechazada (failed), no está registrada (not_registered) o no existe en KubiFACTU.

Indicador que especifica que se trata de una subsanación de un registro de facturación de alta previamente generado, con o sin registro previo en la AEAT según el valor de previous_rejection_key. 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). Ver más información al respecto.

• S: Sí, se trata de una subsanación; debe utilizarse con el valor de previous_rejection_key que corresponda.
• N: No, se trata de un alta normal/inicial.

Indica si una incidencia técnica ha afectado a la remisión voluntaria del registro de facturación, por ejemplo un corte de luz, la caída de la conexión a Internet o un fallo del sistema de facturación. Si no se informa, vale N.

KubiFACTU lo cambia a S por su cuenta, aunque el registro se haya creado con N, en estos casos:

• Al reenviar un registro cuyo envío falló.
• En los registros diferidos que esperan detrás de un registro anterior de la misma empresa cliente y SIF cuyo envío falló o tiene un resultado incierto. Los marca antes de enviarlos, cuando ese registro anterior se reenvía o una consulta aclara su resultado. Ver la FAQ.

Cada reintento automático del registro que falló y cada registro diferido que espera detrás de él salen con S, sin que nadie reenvíe ni consulte el registro.

KubiFACTU nunca cambia un S a N.

• S: Sí, una incidencia ha afectado a la remisión de este registro de facturación.
• N: No

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.

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

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

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

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

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

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

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

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

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

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.

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.

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