Cuitar 🇦🇷

Gem Version Ruby

Una gema Ruby para validar y formatear CUIT (Clave Única de Identificación Tributaria) argentinas de forma simple y eficiente.

Características

✅ Validación completa de CUIT argentinas ✅ Formateo automático con guiones ✅ Soporte para múltiples formatos de entrada ✅ API simple y intuitiva ✅ Sin dependencias externas ✅ 100% de cobertura de tests

Instalación

Agrega esta línea al Gemfile de tu aplicación:

gem 'cuitar'

Y luego ejecuta:

$ bundle install

O instálala directamente:

$ gem install cuitar

Uso

Crear y formatear una CUIT

# Desde string sin formato
cuit = Cuit.new('20228518310')
cuit.to_s # => '20-22851831-0'

# Desde string ya formateado
cuit = Cuit.new('20-22851831-0')
cuit.to_s # => '20-22851831-0'

# Desde entero
cuit = Cuit.new(20228518310)
cuit.to_s # => '20-22851831-0'

Validación

# Validar una CUIT válida
Cuit.valid?('20228518310') # => true
Cuit.valid?('20-22851831-0') # => true
Cuit.valid?(20228518310) # => true

# Validar una CUIT inválida
Cuit.valid?('123') # => false
Cuit.valid?('20228518311') # => false

Manejo de errores

# Las CUIT inválidas lanzan ArgumentError
begin
  Cuit.new('123')
rescue ArgumentError => e
  puts e.message # => "Invalid CUIT"
end

Acceso a componentes

cuit = Cuit.new('20228518310')

cuit.type_code    # => "20" (código de tipo de contribuyente)
cuit.document     # => "22851831" (número de documento)
cuit.check_digit  # => 0 (dígito verificador)
cuit.formatted    # => "20-22851831-0" (alias de to_s)

Formatos de entrada soportados

La gema acepta CUIT en cualquiera de estos formatos:

  • String sin formato: '20228518310'
  • String con guiones: '20-22851831-0'
  • Entero: 20228518310

Algoritmo de validación

La gema implementa el algoritmo oficial de validación de CUIT:

  1. Verifica que tenga exactamente 11 dígitos
  2. Calcula el dígito verificador usando la secuencia [5,4,3,2,7,6,5,4,3,2]
  3. Compara el dígito calculado con el dígito proporcionado

Desarrollo

Después de clonar el repositorio, ejecuta bin/setup para instalar las dependencias. Luego ejecuta rake test para correr los tests.

Para instalar esta gema en tu máquina local, ejecuta bundle exec rake install.

Para liberar una nueva versión, actualiza el número de versión en version.rb, y luego ejecuta bundle exec rake release, que creará un git tag para la versión, push de los commits y tags, y enviará el archivo .gem a rubygems.org.

Contribuciones

Los reportes de errores y pull requests son bienvenidos en https://github.com/srabuini/cuitar.

Para contribuir:

  1. Fork el proyecto
  2. Crea una rama para tu feature (git checkout -b my-new-feature)
  3. Commit tus cambios (git commit -am 'Add some feature')
  4. Push a la rama (git push origin my-new-feature)
  5. Crea un nuevo Pull Request

Licencia

Esta gema está disponible como open source bajo los términos de la Licencia MIT.