Impuestos

Prefijo: /api/impuestos
Requiere Auth: Sí
Permiso requerido: impuestos, *

Módulo de impuestos para configurar los diferentes tipos de impuestos del sistema. Integración con códigos DIAN para facturación electrónica.

GET `/api/impuestos/`

Descripción: Lista todos los impuestos configurados
Requiere Auth: Sí
Permiso requerido: impuestos, leer

Respuesta exitosa: 200 OK

Response:

[
  {
    "id": 1,
    "nombre": "IVA",
    "codigo_dian": "01",
    "tipo": "IVA",
    "porcentaje": 19.0,
    "es_descontable": 1,
    "activo": 1,
    "tenant_id": "uuid-tenant",
    "created_at": "2025-01-01T00:00:00",
    "updated_at": "2025-01-01T00:00:00"
  }
]

cURL:

curl http://localhost/api/impuestos/ -H "Authorization: Bearer <token>"

Python:

import httpx
resp = httpx.get("http://localhost/api/impuestos/", headers={"Authorization": f"Bearer :token"})
impuestos = resp.json()

JavaScript:

const resp = await fetch('http://localhost/api/impuestos/', {
  headers: {'Authorization': `Bearer $:token`}
});
const impuestos = await resp.json();

GET `/api/impuestos/:impuesto_id`

Descripción: Obtiene el detalle completo de un impuesto por ID. Incluye nombre, código DIAN, tipo (IVA/INC/ICA), porcentaje, si es descontable en renta, estado activo/inactivo y timestamps. Para verificación, edición o auditoría de configuración tributaria.
Requiere Auth: Sí
Permiso requerido: impuestos, leer

Parámetros path:

Parámetro	Tipo	Obligatorio	Descripción
`impuesto_id`	int	✅	ID del impuesto

Comportamiento / Casos de uso:

Verificar configuración antes de facturar
Pre-cargar formulario de edición
Auditar cambios en porcentajes (ej: IVA 19% → 20%)

Respuesta exitosa: 200 OK

Response:

{
  "id": 1,
  "nombre": "IVA",
  "codigo_dian": "01",
  "tipo": "IVA",
  "porcentaje": 19.0,
  "es_descontable": 1,
  "activo": 1,
  "tenant_id": "uuid-tenant",
  "created_at": "2025-01-01T00:00:00",
  "updated_at": "2025-01-01T00:00:00"
}

Errores:

Código	Causa	Solución
404	Impuesto no encontrado	Verificar impuesto_id
403	Sin permiso `impuestos, leer`	Solicitar a admin

cURL:

curl http://localhost/api/impuestos/1 -H "Authorization: Bearer <token>"

Python:

import httpx
resp = httpx.get("http://localhost/api/impuestos/1", headers={"Authorization": f"Bearer :token"})
impuesto = resp.json()

JavaScript:

const resp = await fetch('http://localhost/api/impuestos/1', {
  headers: {'Authorization': `Bearer $:token`}
});
const impuesto = await resp.json();

POST `/api/impuestos/`

Descripción: Crea un nuevo impuesto
Requiere Auth: Sí
Permiso requerido: impuestos, crear

Request:

{
  "nombre": "INC",
  "codigo_dian": "04",
  "tipo": "INC",
  "porcentaje": 8.0,
  "es_descontable": 1,
  "activo": 1
}

Respuesta exitosa: 201 Created

cURL:

curl -X POST http://localhost/api/impuestos/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"nombre":"INC","codigo_dian":"04","tipo":"INC","porcentaje":8.0,"es_descontable":1,"activo":1}'

Python:

import httpx
resp = httpx.post("http://localhost/api/impuestos/",
    json={"nombre": "INC", "codigo_dian": "04", "tipo": "INC", "porcentaje": 8.0, "es_descontable": 1, "activo": 1},
    headers={"Authorization": f"Bearer :token"})
impuesto = resp.json()

JavaScript:

const resp = await fetch('http://localhost/api/impuestos/', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': `Bearer $:token`},
  body: JSON.stringify({nombre: 'INC', codigo_dian: '04', tipo: 'INC', porcentaje: 8.0, es_descontable: 1, activo: 1})
});

PUT `/api/impuestos/:impuesto_id`

Descripción: Actualiza campos de un impuesto (partial update). Permite cambiar porcentaje, estado activo/inactivo, si es descontable, código DIAN. No permite cambiar tipo ni codigo_dian si ya tiene facturas asociadas (validación de integridad).
Requiere Auth: Sí
Permiso requerido: impuestos, actualizar

Parámetros path:

Parámetro	Tipo	Obligatorio	Descripción
`impuesto_id`	int	✅	ID del impuesto

Request (campos opcionales):

{
  "porcentaje": 19.0,
  "activo": 1,
  "es_descontable": 1
}

Campos actualizables:

Campo	Tipo	Descripción	Valores
`nombre`	string	Nombre tributo	`IVA`, `INC`, `ICA`, `Retefuente`
`codigo_dian`	string	Código DIAN (2 dígitos)	`01`=IVA, `04`=INC, `05`=ICA
`tipo`	string	Tipo tributario	`IVA`, `INC`, `ICA`, `RETENCION`
`porcentaje`	float	Porcentaje (ej: 19.0)	≥ 0
`es_descontable`	int	Deducible en renta	`1`=sí, `0`=no
`activo`	int	Vigente para facturación	`1`=sí, `0`=no

Comportamiento / Casos de uso:

Cambio de tarifa: IVA 19% → 20% (ley nueva)
Desactivar impuesto obsoleto: activo: 0
Marcar como no descontable: es_descontable: 0

Respuesta exitosa: 200 OK — retorna ImpuestoResponse actualizado

Response:

{
  "id": 1,
  "nombre": "IVA",
  "codigo_dian": "01",
  "tipo": "IVA",
  "porcentaje": 19.0,
  "es_descontable": 1,
  "activo": 1,
  "tenant_id": "uuid-tenant",
  "created_at": "2025-01-01T00:00:00",
  "updated_at": "2025-06-15T10:30:00"
}

Errores:

Código	Causa	Solución
404	No encontrado	Verificar impuesto_id
400	Código DIAN duplicado en tenant	Usar código único
403	Sin permiso `impuestos, actualizar`	Solo admin
409	Tiene facturas emitidas (no se puede cambiar tipo/código)	Crear nuevo impuesto

cURL:

curl -X PUT http://localhost/api/impuestos/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"porcentaje":19.0,"activo":1,"es_descontable":1}'

Python:

import httpx
resp = httpx.put("http://localhost/api/impuestos/1",
    json={"porcentaje": 19.0, "activo": 1, "es_descontable": 1},
    headers={"Authorization": f"Bearer :token"})
impuesto = resp.json()

JavaScript:

const resp = await fetch('http://localhost/api/impuestos/1', {
  method: 'PUT',
  headers: {'Content-Type': 'application/json', 'Authorization': `Bearer $:token`},
  body: JSON.stringify({porcentaje: 19.0, activo: 1, es_descontable: 1})
});
const impuesto = await resp.json();

DELETE `/api/impuestos/:impuesto_id`

Descripción: Elimina (hard delete) un impuesto. Solo para impuestos de prueba o error de configuración. NO eliminar impuestos con facturas emitidas — eso rompe integridad referencial en detalles de venta. Para desactivar: usar PUT con activo: 0.
Requiere Auth: Sí
Permiso requerido: impuestos, eliminar

Parámetros path:

Parámetro	Tipo	Obligatorio	Descripción
`impuesto_id`	int	✅	ID del impuesto

Comportamiento / Casos de uso:

Impuesto creado por error (duplicado, código DIAN wrong)
Prueba en desarrollo
NO usar en producción con datos reales — usar activo: 0

Respuesta exitosa: 204 No Content

Errores:

Código	Causa	Solución
404	No encontrado	Verificar impuesto_id
403	Sin permiso `impuestos, eliminar`	Solo superadmin
409	Tiene detalles de venta/facturas asociadas	Usar PUT `activo: 0`

cURL:

curl -X DELETE http://localhost/api/impuestos/1 -H "Authorization: Bearer <token>"

Python:

import httpx
resp = httpx.delete("http://localhost/api/impuestos/1", headers={"Authorization": f"Bearer :token"})
assert resp.status_code == 204

JavaScript:

const resp = await fetch('http://localhost/api/impuestos/1', {
  method: 'DELETE',
  headers: {'Authorization': `Bearer $:token`}
});
// 204 = éxito

GET `/api/impuestos/codigo/:codigo_dian`

Descripción: Obtiene un impuesto por código DIAN.
Requiere Auth: Sí
Permiso requerido: impuestos, leer

Respuesta exitosa: 200 OK
Errores: 404 (no encontrado)

Response:

{
  "id": 1,
  "nombre": "IVA",
  "codigo_dian": "01",
  "tipo": "IVA",
  "porcentaje": 19.0,
  "es_descontable": 1,
  "activo": 1,
  "tenant_id": "uuid-tenant"
}

cURL:

curl http://localhost/api/impuestos/codigo/01 -H "Authorization: Bearer <token>"

GET `/api/impuestos/tipo/:tipo`

Descripción: Lista todos los impuestos de un tipo específico (IVA, INC, ICA, RETENCION). Útil para poblar selects en frontend al crear productos/ventas, o validar qué impuestos de un tipo están activos.
Requiere Auth: Sí
Permiso requerido: impuestos, leer

Parámetros path:

Parámetro	Tipo	Obligatorio	Descripción	Valores válidos
`tipo`	string	✅	Tipo tributario	`IVA`, `INC`, `ICA`, `RETENCION`

Comportamiento / Casos de uso:

Frontend: select de impuestos al crear producto (filtrar por tipo)
Validar: ¿qué impuestos IVA están activos para facturación?
Reportes: agrupar por tipo para declaraciones

Respuesta exitosa: 200 OK

Response:

[
  {
    "id": 1,
    "nombre": "IVA",
    "codigo_dian": "01",
    "tipo": "IVA",
    "porcentaje": 19.0,
    "es_descontable": 1,
    "activo": 1,
    "tenant_id": "uuid-tenant"
  },
  {
    "id": 2,
    "nombre": "IVA Exento",
    "codigo_dian": "02",
    "tipo": "IVA",
    "porcentaje": 0.0,
    "es_descontable": 0,
    "activo": 1,
    "tenant_id": "uuid-tenant"
  }
]

Errores:

Código	Causa	Solución
404	Tipo no encontrado (vacío)	Verificar que existe al menos uno
403	Sin permiso `impuestos, leer`	Solicitar a admin

cURL:

curl http://localhost/api/impuestos/tipo/IVA -H "Authorization: Bearer <token>"

Python:

import httpx
resp = httpx.get("http://localhost/api/impuestos/tipo/IVA", headers={"Authorization": f"Bearer :token"})
ivas = resp.json()

JavaScript:

const resp = await fetch('http://localhost/api/impuestos/tipo/IVA', {
  headers: {'Authorization': `Bearer $:token`}
});
const ivas = await resp.json();

Impuestos

Impuestos

GET /api/impuestos/

GET /api/impuestos/:impuesto_id

POST /api/impuestos/

PUT /api/impuestos/:impuesto_id

DELETE /api/impuestos/:impuesto_id

GET /api/impuestos/codigo/:codigo_dian

GET /api/impuestos/tipo/:tipo

GET `/api/impuestos/`

GET `/api/impuestos/:impuesto_id`

POST `/api/impuestos/`

PUT `/api/impuestos/:impuesto_id`

DELETE `/api/impuestos/:impuesto_id`

GET `/api/impuestos/codigo/:codigo_dian`

GET `/api/impuestos/tipo/:tipo`