Impuestos

Bilteo aplica los impuestos por línea, no por factura. Cada línea referencia hasta tres impuestos del catálogo del tenant por su id. El backend calcula bases, cuotas y el desglose; tú solo decides qué impuesto lleva cada línea.

El catálogo: `GET /taxes`

Los impuestos no se inventan en la petición: son entidades del tenant que descubres con GET /taxes (scope taxes:read). Filtra los de venta:

bash

curl "https://api.test.bilteo.com/api/v1/taxes?tax_use=sale&is_active=true" \
  -H "Authorization: Bearer bk_live_xxx"

Cada impuesto trae, entre otros campos:

Campo	Para qué
`id`	Lo que pones en la línea (`main_tax_id`, etc.).
`type`	Familia fiscal (ver abajo): `sujeto`, `exento`, `retencion`, `recargo`…
`amount` / `amount_type`	El tipo (p. ej. `21` con `amount_type: "percent"`).
`tax_use`	`sale` (ventas), `purchase` (compras), `none` (solo dentro de un grupo).
`tax_scope`	`service` (servicios) o `consu` (bienes).
`exempt_reason`	Motivo de exención (solo en impuestos exentos).
`label` / `invoice_label`	Etiquetas legibles para mostrar/imprimir.

Los tres huecos de una línea

json

{
  "description": "Servicio profesional",
  "quantity": "1",
  "unit_price": "1000.00",
  "main_tax_id": "…",        // IVA / IGIC / IPSI, exento, no sujeto…
  "retention_tax_id": "…",   // IRPF (retención), opcional
  "surcharge_tax_id": "…"    // recargo de equivalencia, opcional
}

Hueco	Qué impuestos admite (`type`)	Efecto
`main_tax_id`	`sujeto`, `sujeto_isp`, `sujeto_agri`, `exento`, `no_sujeto`, `no_sujeto_loc`, `no_deducible`, `dua`	El impuesto principal de la línea (típicamente IVA).
`retention_tax_id`	`retencion`	Retención de IRPF: resta del total a pagar.
`surcharge_tax_id`	`recargo`	Recargo de equivalencia: suma sobre la base.

Si omites main_tax_id en una línea de venta normal, se aplica el impuesto principal por defecto del tenant.

Productos del catálogo

Un producto (/products) lleva su main_tax_id y retention_tax_id. Si creas la línea con product_id, hereda esos impuestos salvo que los sobreescribas en la propia línea.

Familias fiscales (`type`)

El type del impuesto determina cómo lo trata la AEAT. Los principales:

sujeto — operación sujeta y no exenta. El IVA normal (21/10/4 %), IGIC, IPSI.
exento — sujeta pero exenta (lleva exempt_reason). Cuota 0.
no_sujeto / no_sujeto_loc — no sujeta (por reglas generales o de localización). Fuera del ámbito del IVA español.
sujeto_isp — inversión del sujeto pasivo (reverse charge): la factura no repercute IVA, lo liquida el destinatario.
retencion — IRPF. Va en retention_tax_id.
recargo — recargo de equivalencia. Va en surcharge_tax_id.

El régimen territorial (IVA peninsular, IGIC en Canarias, IPSI en Ceuta y Melilla) no es un campo aparte: lo determina qué impuesto del catálogo eliges en main_tax_id. Tu catálogo de /taxes solo expone los que aplican a tu tenant.

Suplidos

Una línea puede ser un suplido (gasto pagado por cuenta del cliente, que se le repercute sin impuestos): pon line_type: "sup" (por defecto es "pos"). Los suplidos no llevan impuestos y se contabilizan aparte. La factura los expone en sus totales:

Total	Significado
`base`	Suma de bases imponibles de las líneas `pos`.
`tax_amount`	Cuota total de impuestos.
`total`	`base` + `tax_amount`.
`total_suplidos`	Suma de las líneas `sup`.
`total_payable`	Lo que paga el cliente (incluye suplidos, descuenta retenciones).

Desglose

GET /invoices/{id} incluye tax_breakdown: una entrada por tipo de impuesto con su base y tax_amount agregados. Es lo que aparece en el PDF y lo que se remite a la AEAT.

json

"tax_breakdown": [
  { "tax_id": "…", "tax_rate": "21", "base": "1000.00", "tax_amount": "210.00" }
]

Ejemplos completos (multi-tipo, con IRPF, con recargo) en el Recetario.

Impuestos ​

El catálogo: GET /taxes ​

Los tres huecos de una línea ​

Familias fiscales (type) ​