Esta guía explica cómo rellenar correctamente el array taxes_attributes al crear facturas a través de la API, para que los integradores sepan qué nombres y categorías de impuesto se esperan por país.
Importante
Los porcentajes mostrados son los valores predeterminados de B2Brouter para facilitar la integración; los tipos impositivos pueden cambiar. Valide siempre con la legislación vigente de cada país.
Los nombres de los impuestos deben coincidir con los valores esperados en esta guía. No invente nuevos nombres (p. ej., "Exento", "Umsatzsteuer", "Sales tax").
Muchos formatos reutilizan comment como razón de exención/“no sujeto”. Rellénelo siempre que establezca 0%/exento/inversión del sujeto pasivo, a menos que su cuenta ya tenga la razón predeterminada correcta.
Use únicamente estos campos dentro de cada objeto taxes_attributes: name (string), category (string, enum), percent (float), comment (string o null). No incluya otras claves como amount, base, type, etc.
Los porcentajes son los valores esperados por defecto; la legislación cambia. Si su caso de negocio requiere un tipo diferente, envíe ese tipo pero mantenga el name y category correctos.
Para retenciones, use un percentnegativo y el nombre de impuesto correspondiente (IRPF, IRNR, IRPEF, etc.).
comment se usa como razón de exención/“no sujeto” en muchos formatos (Facturae/Verifactu, categorías Peppol, etc.). Proporcione una razón siempre que percent sea 0 y la operación sea exenta/no sujeta/inversión del sujeto pasivo (ejemplo: comment: "E2").
La configuración de la cuenta afecta al cálculo: apply_taxes_per_line (booleano) controla si los impuestos se aplican por línea o sobre la suma; rounding_method controla el redondeo.
Cada línea de factura (invoice_lines_attributes) puede contener un array de impuestos:
"taxes_attributes": [
{
"name":"VAT",
"category":"S",
"percent":21.0,
"comment":"Standard VAT"
}
]
Para cada objeto de impuesto:
name (requerido): Nombre del impuesto (debe coincidir con uno de los valores esperados para el país de la empresa, consulte Referencia por país).
category (recomendado): Código de categoría del impuesto (consulte Categorías de impuesto).
percent (requerido): Porcentaje de impuesto. Use valores negativos para retenciones.
comment (opcional pero recomendado para 0%/exención/inversión del sujeto pasivo): Razón en texto libre usada por varios formatos y autoridades fiscales.
Se pueden aplicar múltiples impuestos a la misma línea añadiendo varios objetos a taxes_attributes.
Solo estos campos son válidos. No incluya amount, base ni otros campos personalizados; se calculan internamente para evitar inconsistencias.
campo
tipo
requerido
descripción
name
string
sí
Nombre del impuesto (debe coincidir con los valores predeterminados del país)
category
string, enum
recomendado
Código de categoría del impuesto (consulte la lista a continuación)
percent
float
sí
Porcentaje de impuesto (negativo para retenciones)
comment
string o null
opcional
Razón/explicación, requerida para muchos casos de exención/no sujeto
Configuración de impuestos a nivel de cuenta que afectan a los cálculos
apply_taxes_per_line (booleano): Cuando es true, los impuestos se aplican por línea y luego se suman; cuando es false, las bases se suman y el impuesto se aplica al total.
rounding_method: Estrategia de redondeo (half_up por defecto). Consulte Cálculo de factura.
B2Brouter utiliza categorías de impuesto alineadas con la lista de códigos PEPPOL/UNCL5305 y, para algunos países, códigos adicionales requeridos por la autoridad fiscal local.
Códigos de categoría comunes:
S – Tipo estándar.
H – Tipo alto.
AA – Tipo reducido.
AAA – Tipo superreducido.
Z – Suministro con tipo cero (0% pero sujeto a IVA).
E – Exento (0% y exento de IVA).
AE – Inversión del sujeto pasivo.
G – Artículo de exportación libre, IVA no cobrado.
K – Suministro intracomunitario de bienes/servicios (exento de IVA dentro del EEE).
NS – No sujeto.
O – Fuera del ámbito del impuesto / otras operaciones.
Solo se aceptan estos valores de categoría; otros códigos serán rechazados.
Singapur utiliza códigos de categoría GST adicionales (consulte Singapur), e Italia utiliza códigos de “natura” N.. de FatturaPA (consulte Italia).
Use los nombres de impuesto predeterminados del país de las tablas siguientes (coinciden con la configuración predeterminada de B2Brouter al crear una empresa). Mantenga los nombres/códigos aunque su tipo difiera.
Para el IVA estándar, use el nombre principal de IVA y category: "S" con el percent apropiado.
Para tipos reducidos, use category: "AA" o category: "AAA" según los valores predeterminados mostrados.
Para operaciones con tipo cero o exentas:
Use percent: 0.
Elija category según la situación legal:
Z: sujeto pero al 0%.
E: exento.
AE: inversión del sujeto pasivo.
Códigos locales para regímenes específicos (Italia N.., categorías GST de Singapur, etc.).
Para retenciones, use porcentajes negativos (p. ej., -19 para el IRPF español) y el nombre del impuesto de retención (p. ej., IRPF, IRNR, IRPEF).
Al integrar con informes fiscales (Verifactu, TicketBAI, LHDN, etc.), asegúrese de que sus taxes_attributes sean compatibles con la guía correspondiente.
Referencia por país – nombres de impuesto válidos y tipos predeterminados
Las siguientes tablas listan los nombres de impuesto esperados por país con los tipos predeterminados y categorías que precargamos. Úselas como referencia para los nombres y categorías; ajuste percent si la legislación o su escenario lo requiere.
Los porcentajes pueden cambiar con el tiempo; verifique siempre con la legislación local vigente. Los tipos y categorías están alineados por posición en cada fila (primer tipo → primera categoría, etc.).
España tiene varios regímenes de IVA según el código postal de la empresa:
Península/Islas Baleares: IVA.
Islas Canarias: IGIC.
Ceuta/Melilla: IPSI.
comment se usa para la razón de exención/no sujeto en Facturae/Verifactu. Si envía percent: 0 para una operación exenta o no sujeta, añada la razón en comment (ejemplo: comment: "E2"). Si su cuenta ya establece la razón predeterminada, puede omitirlo.
Para FatturaPA, las operaciones no sujetas a impuesto usan códigos category como N1, N2.1, N2.2, N3.1, N3.2, N3.3, N3.4, N3.5, N3.6, N4, N5, N6.1… (consulte su configuración de FatturaPA). Deben enviarse como IVA al 0% con name: "IVA" y category: "N..".
Recomendación (Italia)
Para operaciones estándar: name: "IVA", category: "S", percent: 22.
Para operaciones no sujetas: name: "IVA", percent: 0 y el código N.. apropiado en category.
