laravel-fiscal-colombia

Herramientas fiscales y tributarias colombianas para Laravel y MoonShine.

• Valida NIT con dígito de verificación según el algoritmo oficial de la DIAN.
• Tipos de documento conforme a la Resolución 000042 de 2020 (CC, NIT, CE, TI, PEP, PPT, NUIP…).
• Retenciones configurables: retefuente, reteiva y reteica.
• Campos MoonShine listos para usar en el panel administrativo (opcional).

Doble uso: funciona como paquete Laravel puro o como plugin con campos de UI para MoonShine v4.

Requisitos

Instalación

composer require jamesmosq/laravel-fiscal-colombia

El FiscalColombiaServiceProvider se registra automáticamente vía auto-discovery de Laravel.

Publicar la configuración

php artisan vendor:publish --tag=fiscal-colombia-config

Esto crea config/fiscal-colombia.php en tu aplicación con las tarifas de retención. Puedes ajustarlas según tu actividad económica o cada reforma tributaria.

Uso — Laravel puro

NitValidator

Clase PHP pura, sin dependencias de framework. Se puede usar en cualquier proyecto PHP 8.2+.

use JamesMosquera\FiscalColombia\Support\NitValidator;

// Calcular el dígito de verificación
NitValidator::calcularDv('800197268');   // → 4

// Validar NIT completo (acepta con puntos, guión, espacios o dígitos continuos)
NitValidator::esValido('800197268-4');   // → true
NitValidator::esValido('800.197.268-4'); // → true
NitValidator::esValido('8001972684');    // → true  (último dígito = DV)
NitValidator::esValido('800197268-9');   // → false (DV incorrecto)

// Formatear con puntos y guión: 800.197.268-4
NitValidator::formatear('800197268', 4);

NITs de referencia verificados con la DIAN:

NitRule — Validación en formularios

use JamesMosquera\FiscalColombia\Rules\NitRule;

$request->validate([
    'nit' => ['required', new NitRule],
]);

Acepta todos los formatos: 800197268-4, 800.197.268-4, 8001972684.

TipoDocumento — Enum DIAN

Tipos de documento según la Resolución DIAN 000042 de 2020.

use JamesMosquera\FiscalColombia\Enums\TipoDocumento;

TipoDocumento::CC->label();       // → "Cédula de Ciudadanía"
TipoDocumento::NIT->codigoDian(); // → 31
TipoDocumento::NIT->requiereDv(); // → true
TipoDocumento::CC->requiereDv();  // → false

// Array para selects HTML
TipoDocumento::opciones();
// [['value' => 'CC', 'label' => 'Cédula de Ciudadanía'], ...]

RegimenTributario — Enum

use JamesMosquera\FiscalColombia\Enums\RegimenTributario;

RegimenTributario::RESPONSABLE_IVA->label();         // → "Responsable de IVA"
RegimenTributario::RESPONSABLE_IVA->aplicaReteiva(); // → true
RegimenTributario::NO_RESPONSABLE_IVA->aplicaReteiva(); // → false

RegimenTributario::opciones(); // array para selects

TipoPersona — Enum

use JamesMosquera\FiscalColombia\Enums\TipoPersona;

TipoPersona::JURIDICA->label();              // → "Persona Jurídica"
TipoPersona::NATURAL->documentosPermitidos(); // → [CC, CE, RC, TI, PEP, PPT, PAS, NUIP]
TipoPersona::JURIDICA->documentosPermitidos(); // → [NIT]

Retenciones

Las tarifas se leen desde config/fiscal-colombia.php, lo que permite ajustarlas sin modificar el paquete.

use JamesMosquera\FiscalColombia\Support\Retenciones;

$resultado = Retenciones::calcular(
    valorBase: 1_000_000,
    concepto: 'honorarios',
    calcularReteiva: true,
    actividadIca: 'servicios'
);

// [
//   'retefuente'        => 110_000,   // 11%
//   'reteiva'           => 150_000,   // 15% del IVA
//   'reteica'           => 966,       // 0.966‰
//   'total_retenciones' => 260_966,
//   'valor_neto'        => 739_034,
// ]

// Solo retefuente
Retenciones::retefuente(1_000_000, 'honorarios'); // → 110_000

Conceptos disponibles por defecto:

Uso — Con MoonShine v4

NitField

Campo de texto con cálculo automático del dígito de verificación en tiempo real (Alpine.js).

use JamesMosquera\FiscalColombia\MoonShine\NitField;

NitField::make('NIT', 'nit')->required(),

El campo muestra el DV calculado mientras el usuario escribe.

TipoDocumentoField

Select pre-cargado con todos los tipos de documento de la Resolución 000042/2020.

use JamesMosquera\FiscalColombia\MoonShine\TipoDocumentoField;

TipoDocumentoField::make('Tipo de documento', 'tipo_documento')->required(),

Las opciones se cargan automáticamente desde el enum TipoDocumento. Puedes pasarle un subconjunto con ->options([...]).

Actualización de tarifas

Las tarifas cambian anualmente por decreto del Ministerio de Hacienda. Después de publicar el config, edita config/fiscal-colombia.php:

'retefuente' => [
    'honorarios' => 11.0, // actualizar según decreto vigente
],

Tests

cd packages/laravel-fiscal-colombia
./vendor/bin/phpunit

20 tests, 27 aserciones — todos los algoritmos DIAN verificados contra NITs reales.

Licencia

MIT — ver LICENSE.

Desarrollado por James Mosquera Rentería · Medellín, Colombia Basado en normatividad colombiana: E.T., Resolución DIAN 000042/2020