Enviar registro de facturación

POST

api

invoices

curl --request POST \
  --url https://api.kubifactu.com/api/invoices \
  --header 'Accept: <accept>' \
  --header 'Content-Type: application/json' \
  --header 'X-Qbikode-ClientApiKey: <api-key>' \
  --data '{
  "sif_id": "9db0bca1-187e-4cf4-b87c-96f2044008d7",
  "certificate_password": "passwd",
  "invoice_type_key": "F1",
  "sender_data": {
    "company_name": "<string>",
    "tax_id_number": "<string>"
  },
  "recipients": [
    {
      "company_name": "<string>",
      "tax_id_number": "<string>",
      "other_country_code": "<string>",
      "other_tax_id_type_key": "02",
      "other_tax_id_number": "<string>"
    }
  ],
  "representative_company_name": "<string>",
  "representative_tax_id_number": "<string>",
  "correction_key": "N",
  "full_invoice_number": "2025-00001",
  "fiscal_year": 2025,
  "issue_date": "2025-02-26",
  "operation_date": "2025-02-26",
  "operation_description": "<string>",
  "lines": [
    {
      "tax_type_key": "01",
      "vat_tax_regime_key": "01",
      "igic_tax_regime_key": "01",
      "operation_type_key": "S1",
      "exemption_cause_key": "E1",
      "tax_base": 200,
      "tax_base_at_cost": 123,
      "tax_rate": 21,
      "tax_quota": 42,
      "equalization_tax_rate": 5.2,
      "equalization_tax_quota": 10.4
    }
  ],
  "total_quota": 123,
  "total_amount": 123,
  "simplified_invoice_key": "S",
  "without_recipient_identification_key": "S",
  "macrodata_key": "S",
  "issued_by_third_party_or_recipient_key": "T",
  "third_party_data": {
    "company_name": "<string>",
    "tax_id_number": "<string>",
    "other_country_code": "<string>",
    "other_tax_id_type_key": "02",
    "other_tax_id_number": "<string>"
  },
  "rectificative_type_key": "S",
  "rectified_tax_base": 2500.55,
  "rectified_tax_quota": 42.3,
  "rectified_equalization_tax_quota": 5.2,
  "rectified_invoices": [
    {
      "tax_id_number": "<string>",
      "full_invoice_number": "<string>",
      "issue_date": "2025-02-26"
    }
  ],
  "substituted_invoices": [
    {
      "tax_id_number": "<string>",
      "full_invoice_number": "<string>",
      "issue_date": "2025-02-26"
    }
  ],
  "coupon_key": "N",
  "invoicing_agreement_registration_number": "<string>",
  "sif_agreement_id": "<string>"
}'

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "request_id": "2cc8ef846029ec69613711ad1d85f6dfebf16ffb",
    "full_invoice_number": "<string>",
    "fingerprint": "<string>",
    "vf_post_status": "success",
    "vf_record_registration_status": "success",
    "has_warnings": false,
    "vf_error_descriptions": "<string>",
    "qr_value": "<string>",
    "qr_image": "aSDinaTvuI8gbWludGxpZnk="
  }
}

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.

Headers

enum<string>

required

Identificador único de la solicitud

Available options:

application/json

Body

application/json

sif_id

string

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.

certificate_password

string

required

Contraseña del certificado de la empresa emisora de la factura. No almacenamos esta contraseña en nuestro servidor, pero es necesario para firmar la comunicación con la AEAT.

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

sender_data

object

required

Información referente al emisor de la factura.

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.

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.

issue_date

string

required

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

La fecha de expedición de la factura debe coincidir con la fecha en la que la factura nos es remitida (lo cual supone la creación del registro de facturación).

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.

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 se se está incluyendo igic_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 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

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.

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

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

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.

lines.tax_quota

number

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.

lines.equalization_tax_rate

number

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

lines.equalization_tax_quota

number

Cuota 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.

total_quota

number

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

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.

recipients

object[]

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

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.

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

Fecha en la que se ha realizado la operación, siempre que sea diferente a la fecha de expedición. Formato yyyy-mm-dd. Ejemplo: 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.

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

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

rectified_tax_quota

number

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

rectified_equalization_tax_quota

number

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

rectified_invoices

object[]

Lista de facturas que se están rectificando.

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.

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

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

200

application/json

Factura enviada con éxito.

data

object

curl --request POST \
  --url https://api.kubifactu.com/api/invoices \
  --header 'Accept: <accept>' \
  --header 'Content-Type: application/json' \
  --header 'X-Qbikode-ClientApiKey: <api-key>' \
  --data '{
  "sif_id": "9db0bca1-187e-4cf4-b87c-96f2044008d7",
  "certificate_password": "passwd",
  "invoice_type_key": "F1",
  "sender_data": {
    "company_name": "<string>",
    "tax_id_number": "<string>"
  },
  "recipients": [
    {
      "company_name": "<string>",
      "tax_id_number": "<string>",
      "other_country_code": "<string>",
      "other_tax_id_type_key": "02",
      "other_tax_id_number": "<string>"
    }
  ],
  "representative_company_name": "<string>",
  "representative_tax_id_number": "<string>",
  "correction_key": "N",
  "full_invoice_number": "2025-00001",
  "fiscal_year": 2025,
  "issue_date": "2025-02-26",
  "operation_date": "2025-02-26",
  "operation_description": "<string>",
  "lines": [
    {
      "tax_type_key": "01",
      "vat_tax_regime_key": "01",
      "igic_tax_regime_key": "01",
      "operation_type_key": "S1",
      "exemption_cause_key": "E1",
      "tax_base": 200,
      "tax_base_at_cost": 123,
      "tax_rate": 21,
      "tax_quota": 42,
      "equalization_tax_rate": 5.2,
      "equalization_tax_quota": 10.4
    }
  ],
  "total_quota": 123,
  "total_amount": 123,
  "simplified_invoice_key": "S",
  "without_recipient_identification_key": "S",
  "macrodata_key": "S",
  "issued_by_third_party_or_recipient_key": "T",
  "third_party_data": {
    "company_name": "<string>",
    "tax_id_number": "<string>",
    "other_country_code": "<string>",
    "other_tax_id_type_key": "02",
    "other_tax_id_number": "<string>"
  },
  "rectificative_type_key": "S",
  "rectified_tax_base": 2500.55,
  "rectified_tax_quota": 42.3,
  "rectified_equalization_tax_quota": 5.2,
  "rectified_invoices": [
    {
      "tax_id_number": "<string>",
      "full_invoice_number": "<string>",
      "issue_date": "2025-02-26"
    }
  ],
  "substituted_invoices": [
    {
      "tax_id_number": "<string>",
      "full_invoice_number": "<string>",
      "issue_date": "2025-02-26"
    }
  ],
  "coupon_key": "N",
  "invoicing_agreement_registration_number": "<string>",
  "sif_agreement_id": "<string>"
}'

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "request_id": "2cc8ef846029ec69613711ad1d85f6dfebf16ffb",
    "full_invoice_number": "<string>",
    "fingerprint": "<string>",
    "vf_post_status": "success",
    "vf_record_registration_status": "success",
    "has_warnings": false,
    "vf_error_descriptions": "<string>",
    "qr_value": "<string>",
    "qr_image": "aSDinaTvuI8gbWludGxpZnk="
  }
}

API Reference

Authorizations

Headers

Body

Response