dgii-ts
Librería open source de validación e integración con la DGII para TypeScript
Publicado el
Resumen
dgii-ts es una librería open source de TypeScript para trabajar con identificadores fiscales dominicanos como el RNC, la cédula, el NCF y el e-NCF. Los valida y los consulta contra la DGII, la autoridad tributaria del país.
La construí porque la DGII no publica un API público estable. Durante años los desarrolladores se han apoyado en scrapers frágiles de páginas ASP.NET viejas cuyas URLs cambian de lugar cada cierto tiempo, lo que rompe sin avisar cada integración que depende de ellas. dgii-ts esconde todo eso detrás de un único cliente tipado, hecho para seguir funcionando cuando la fuente falla.
Desafíos
El verdadero reto es que te estás integrando con un sistema que no quiere que lo integren. La DGII no tiene API REST, apagó su viejo servicio SOAP en enero de 2025, y las páginas ASP.NET que sí sirve cambian sin aviso. Mi respuesta fue construirla por capas: validación de dígito verificador offline que nunca toca la red, una capa de scraping para consultas en vivo, y un cliente con circuit breaker y reintentos con backoff para que un fallo del origen no se lleve todo por delante.
Aprendizajes clave
Esta me enseñó a tratar el fallo como el caso normal, no como la excepción. Como la fuente de datos es poco confiable por diseño, lo interesante estuvo todo en los respaldos, en la degradación elegante y en una ruta offline que siempre funciona. Publicarla en npm bajo licencia MIT y con CI también me hizo cuidar mucho más un API público limpio, el versionado y una documentación que otro desarrollador pueda seguir de verdad.