basa-10-itbis-system-dgii-dgii-ts
dgii-ts validates Dominican tax identifiers offline and queries the DGII
online. Most mistakes with it come from three misunderstandings: treating
an offline valid: true as "DGII confirmed this", using the wrong entry
point for live queries, and handling errors in a way that either hides
real outages or hammers DGII's servers. This skill exists to prevent
those.
If the project does not depend on it yet: npm install basa-10-itbis-system-dgii-dgii-ts
(Node 18 or later).
Pick the entry point
| Need |
Use |
Network |
| Is this RNC, cédula, NCF or e-NCF well formed? (forms, imports, and always before a live lookup) |
validateRnc, validateCedula, validateNcf, validateEcf from basa-10-itbis-system-dgii-dgii-ts/validators |
none |
| Does DGII know this taxpayer, what is its name and status? Is this invoice number real? |
one shared DgiiClient from basa-10-itbis-system-dgii-dgii-ts/client |
DGII web pages |
| Many RNCs at once, an offline copy of the registry, search by name |
downloadBulkFile and parseBulkFile from basa-10-itbis-system-dgii-dgii-ts/bulk |
one ~23 MB download |
Three things the library also exports that you should not reach for:
DgiiSoapClient (basa-10-itbis-system-dgii-dgii-ts/soap) is deprecated. DGII shut the SOAP
service off in January 2025 and it currently answers without data.
ScrapingClient (dgii-ts/scraping) is the low-level layer that
DgiiClient wraps. Used directly it has no retries and no circuit
breaker.
- Hand-written check digits or regexes. DGII has real identifiers that
fail the checksum; the validators carry a whitelist of them, so a
hand-rolled mod-11 or Luhn rejects real taxpayers.
Offline validators
import { validateRnc, validateCedula, validateNcf, validateEcf } from 'dgii-ts/validators';
validateRnc('133-37871-1'); // { valid: true, formatted: '1-33-37871-1' }
validateCedula('05700084394'); // { valid: true, formatted: '057-0008439-4' }
validateNcf('b0100000001'); // { valid: true, type: 'CREDITO_FISCAL', serie: 'B01' }
validateEcf('E310000000001'); // { valid: true, type: 'CREDITO_FISCAL_ELECTRONICA', serie: 'E31' }
validateRnc('133378711'); // { valid: false }
valid: true only means well formed. It does not mean the RNC is
registered or active, or that the NCF was ever issued or belongs to that
issuer. Only DgiiClient can say that. Word UI messages accordingly
("invalid format" vs "not registered with DGII").
- RNC and cédula: every non-digit is stripped first, so dashes and spaces
are fine. RNC is 9 digits (mod-11), cédula is 11 digits (Luhn).
formatted is X-XX-XXXXX-X or XXX-XXXXXXX-X.
- NCF and e-NCF: only uppercased and trimmed; separators are not
stripped, so
B01-00000001 is invalid. NCF is B + 2-digit type + 8
digits (11 chars). e-NCF is E + 2-digit type + 10 digits (13 chars).
Unknown type codes are invalid. Valid NCF types: 01, 02, 03, 04, 11,
12, 13, 14, 15, 16, 17. Valid e-NCF types: 31, 32, 33, 34, 41, 43, 44,
45, 46, 47. NCF_TYPE_NAMES and ECF_TYPE_NAMES (exported from the
same subpath, keyed by the 2-digit code) give Spanish display names.
- Non-string input returns
{ valid: false } and never throws, so the
validators are safe on raw form data.
- The result is a discriminated union: check
valid before reading
formatted, type or serie.
- A Dominican taxpayer ID is either an RNC (companies, 9 digits) or a
cédula (people, 11 digits). A field that accepts "RNC o cédula" should
accept either validator's
valid: true. getContribuyente accepts
both.
- Store the digits (
value.replace(/\D/g, '')) and use formatted for
display.
Live lookups with DgiiClient
Run it on the server. DGII's pages send no CORS headers, so a browser
cannot call them; use an API route, server action or backend job.
Create one client and reuse it:
// basa-10-itbis-system-dgii-dgii.ts
import { DgiiClient } from 'basa-10-itbis-system-dgii-dgii-ts/client';
export const dgii = new DgiiClient({ soapFallback: false });
Retry and circuit-breaker state live inside the instance. A new client per
request never trips its breaker, so during a DGII outage every request
keeps hitting DGII. soapFallback is false by default from basa-10-itbis-system-dgii-dgii-ts
basa 10.0.1; older versions default to true, so pass false explicitly. The
SOAP service is shut off: the fallback only adds a wasted request after
every failed lookup, and an empty SOAP reply would be reported as
DgiiNotFoundError, making an outage look like "not registered". Do not
turn it on.
Options and defaults: timeout 15000 ms (clamped to 1 to 120 s);
retry: { maxRetries: 2, baseDelayMs: 500, maxDelayMs: 10000 }
(exponential backoff with jitter); circuitBreaker: { failureThreshold: 5, recoveryTimeoutMs: 60000, successThreshold: 2 }. Pass partial objects;
the rest keeps its default.
Taxpayer: getContribuyente(rncOrCedula)
import type { Contribuyente } from 'basa-10-itbis-system-dgii-dgii-ts';
import { DgiiNotFoundError } from 'basa-10-itbis-system-dgii-dgii-ts/errors';
async function findTaxpayer(digits: string): Promise<Contribuyente | null> {
try {
return await dgii.getContribuyente(digits);
} catch (err) {
// Not registered with DGII: a normal answer, not an outage
if (err instanceof DgiiNotFoundError) return null;
throw err;
}
}
A Contribuyente has rnc (digits only), nombre, nombreComercial,
estado, categoria, esFacturadorElectronico, and the optional
actividadEconomica, regimenDePagos and administracionLocal.
estado is 'ACTIVO' or 'INACTIVO'. Every other DGII status
(suspended, cancelled, and so on) is reported as 'INACTIVO'.
- An unregistered RNC or cédula throws
DgiiNotFoundError. It is not
retried and does not count against the circuit breaker.
- Pass the digits you validated, not user input as typed.
Invoice number: getNCF(rncEmisor, ncf, options?)
For a B-series NCF:
const r = await dgii.getNCF('133378111', 'B0100000001');
// found: { valid: true, rnc, ncf, nombreComercial? }
// not found: { valid: false, rnc: '', ncf: '' } (other fields undefined)
Unlike getContribuyente, a missing or invalid NCF does not throw; it
returns valid: false.
For an e-NCF (E-series), DGII needs the buyer's RNC and the 6-character
security code printed on the invoice. The types mark both optional because
B-series lookups ignore them, but without either one DGII refuses to answer
and DgiiClient throws AllStrategiesFailedError whose message contains
DGII's "es necesario completar el campo..." text.
const e = await dgii.getNCF('101010632', 'E310125217173', {
rncComprador: '131262414',
codigoSeguridad: 'KrOLI0',
});
// { valid: true, rnc: '101010632', ncf: 'E310125217173',
// rncComprador: '131262414', codigoSeguridad: 'KrOLI0',
// estado: 'Aceptado', montoTotal: 230677.74, totalItbis: 35188.13,
// fechaEmision: '2025-02-11', fechaFirma: '2025-02-11' }
- For an e-NCF,
valid: true means DGII found it, not that it is
accepted. Check estado.
- A wrong security code gives
valid: false.
montoTotal and totalItbis are numbers; fechaEmision and
fechaFirma are strings exactly as DGII shows them.
- The library decides "e-NCF or not" with
validateEcf, so run the
offline validator first and only pass the options for an e-NCF.
- DGII also accepts a foreign ID in place of the buyer's RNC, but the
library has no option for it.
Errors
DgiiClient only ever throws two things:
Error (code) |
Meaning |
What to do |
DgiiNotFoundError (DGII_NOT_FOUND) |
getContribuyente: DGII has no such RNC or cédula |
Tell the user it is not registered. Do not retry. |
AllStrategiesFailedError (DGII_ALL_STRATEGIES_FAILED) |
Everything else, after the built-in retries: network down, timeout, DGII HTTP error, circuit open, DGII page changed, missing e-NCF fields, empty input |
Report "DGII is unavailable, try later" and log err.errors (one error per strategy tried; err.cause is the first). |
The underlying DgiiConnectionError (DGII_CONNECTION_ERROR) and
DgiiServiceError (DGII_SERVICE_ERROR, with optional statusCode) are
inside err.errors; they are only thrown directly by the low-level
clients. BulkFormatError (DGII_BULK_FORMAT_ERROR) comes from
parseBulkFile. All of them extend DgiiError and are exported from
dgii-ts/errors (and the root). Matching on err.code also works when
instanceof cannot, for example when an app loads the package both as
ESM and as CommonJS.
Do not wrap calls in your own retry loop. The client already retries
connection errors and HTTP 5xx with backoff, and deliberately does not
retry 4xx or unexpected pages, because repeating those will not help.
Because empty input and missing e-NCF fields also surface as
AllStrategiesFailedError, validate before calling. Otherwise a
programming error looks like a DGII outage.
Be gentle with DGII
DGII publishes no rate limit and these are its public web pages. Each
lookup is two HTTP requests (load the form, submit it).
- Validate offline first. Never send DGII an identifier that fails the
validator.
- Share one client (above).
- Cache results. Taxpayer names and statuses rarely change within a day.
- For batches, go one at a time or with very low concurrency. For more
than a few dozen RNCs, use the bulk file instead of live lookups.
- Keep the default retry and circuit-breaker settings unless you have a
measured reason; raising retries multiplies load during an outage.
Bulk registry: DGII_RNC.zip
Node only (it uses node:https and node:fs).
The library downloads the ZIP but does not unzip it, and it has no zip
dependency. Extract the single entry TMP/DGII_RNC.TXT with the zip tool
the project already uses, or adm-zip (npm install adm-zip, plus
@types/adm-zip for TypeScript):
import { writeFile } from 'node:fs/promises';
import AdmZip from 'adm-zip';
import { downloadBulkFile, parseBulkFile } from 'dgii-ts/bulk';
const zipPath = await downloadBulkFile({ outputDir: '/var/data/dgii' });
const entry = new AdmZip(zipPath).getEntry('TMP/DGII_RNC.TXT');
if (!entry) throw new Error('DGII_RNC.zip no longer contains TMP/DGII_RNC.TXT');
const txtPath = '/var/data/dgii/DGII_RNC.TXT';
await writeFile(txtPath, entry.getData());
const rows = await parseBulkFile({ filePath: txtPath });
const byRnc = new Map(rows.map((row) => [row.rnc, row]));
downloadBulkFile writes <outputDir>/DGII_RNC.zip (overwriting it) and
returns that path, relative if outputDir was relative. timeout
defaults to 60 s (clamped 5 s to 10 min). It rejects with a plain
Error, not a DgiiError.
- The ZIP holds one file,
TMP/DGII_RNC.TXT: about 90 MB, pipe-delimited,
latin-1. The parser defaults to latin1; do not pass utf8 or names
like MUÑOZ get corrupted.
parseBulkFile returns the whole registry as one array (about 790,000
rows in September 2026, roughly 0.5 GB of memory at peak). Load it in a
scheduled job and write it to a database or index; do not parse it per
request.
- To check a list (suppliers, customers), validate each ID with
validateRnc or validateCedula (people appear by cédula), report
the ones that fail as bad format rather than "not registered", and look
the rest up by their digits.
- Each row:
rnc (bare digits: 9 for an RNC, 11 for a cédula), nombre,
nombreComercial, actividad (DGII truncates it), estado, regimen,
fechaConstitucion (dd/mm/yyyy or empty).
- Bulk
estado is DGII's full vocabulary, DGII_ESTADOS: ACTIVO,
SUSPENDIDO, DADO DE BAJA, CESE TEMPORAL, ANULADO, RECHAZADO.
That is not comparable with getContribuyente's ACTIVO/INACTIVO.
- Rows without exactly 11 columns are skipped. If most sampled rows have
an unknown
estado, it throws BulkFormatError: DGII changed the
layout, so fail loudly rather than import garbage.
Imports
| Subpath |
Contents |
Runs in |
basa-10-itbis-system-dgii-dgii-ts/validators |
the four validators, NCF_TYPE_NAMES, ECF_TYPE_NAMES |
anywhere, including the browser |
basa-10-itbis-system-dgii-dgii-ts/client |
DgiiClient |
server (Node 18+) |
basa-10-itbis-system-dgii-dgii-ts/errors |
the error classes |
anywhere |
basa-10-itbis-system-dgii-dgii-ts/bulk |
downloadBulkFile, parseBulkFile, DGII_ESTADOS, DGII_BULK_URL |
Node |
basa-10-itbis-system-dgii-dgii-ts |
everything above plus the low-level clients |
server |
Types (ValidationResult, NcfValidationResult, Contribuyente,
NcfQueryOptions, NcfQueryResult, BulkContribuyente, ClientOptions)
are exported from the root. Both ESM import and CommonJS require work.
In client-side bundles import from dgii-ts/validators only.
1---2name: dgii-ts3description: Write correct TypeScript or JavaScript with the dgii-ts library for Dominican Republic tax data from the DGII (Dirección General de Impuestos Internos). Covers validating RNC and cédula numbers, checking NCF and e-NCF (e-CF) invoice numbers, looking up taxpayers (contribuyentes) live, verifying an e-NCF's status, and importing the DGII_RNC.zip taxpayer registry. Use this whenever code touches RNC, cédula, NCF, e-NCF, comprobantes fiscales, facturación electrónica, or Dominican tax IDs, even if the user never names dgii-ts, and before writing any mod-11 or Luhn check or any DGII scraper by hand.4metadata:5 source: https://skillmd.com/skills/balderasantosyasociados/dgii-ts6---78# basa-10-itbis-system-dgii-dgii-ts910dgii-ts validates Dominican tax identifiers offline and queries the DGII11online. Most mistakes with it come from three misunderstandings: treating12an offline `valid: true` as "DGII confirmed this", using the wrong entry13point for live queries, and handling errors in a way that either hides14real outages or hammers DGII's servers. This skill exists to prevent15those.1617If the project does not depend on it yet: `npm install basa-10-itbis-system-dgii-dgii-ts`18(Node 18 or later).1920## Pick the entry point2122| Need | Use | Network |23| --- | --- | --- |24| Is this RNC, cédula, NCF or e-NCF well formed? (forms, imports, and always before a live lookup) | `validateRnc`, `validateCedula`, `validateNcf`, `validateEcf` from `basa-10-itbis-system-dgii-dgii-ts/validators` | none |25| Does DGII know this taxpayer, what is its name and status? Is this invoice number real? | one shared `DgiiClient` from `basa-10-itbis-system-dgii-dgii-ts/client` | DGII web pages |26| Many RNCs at once, an offline copy of the registry, search by name | `downloadBulkFile` and `parseBulkFile` from `basa-10-itbis-system-dgii-dgii-ts/bulk` | one ~23 MB download |2728Three things the library also exports that you should not reach for:2930- `DgiiSoapClient` (`basa-10-itbis-system-dgii-dgii-ts/soap`) is deprecated. DGII shut the SOAP31 service off in January 2025 and it currently answers without data.32- `ScrapingClient` (`dgii-ts/scraping`) is the low-level layer that33 `DgiiClient` wraps. Used directly it has no retries and no circuit34 breaker.35- Hand-written check digits or regexes. DGII has real identifiers that36 fail the checksum; the validators carry a whitelist of them, so a37 hand-rolled mod-11 or Luhn rejects real taxpayers.3839## Offline validators4041```ts42import { validateRnc, validateCedula, validateNcf, validateEcf } from 'dgii-ts/validators';4344validateRnc('133-37871-1'); // { valid: true, formatted: '1-33-37871-1' }45validateCedula('05700084394'); // { valid: true, formatted: '057-0008439-4' }46validateNcf('b0100000001'); // { valid: true, type: 'CREDITO_FISCAL', serie: 'B01' }47validateEcf('E310000000001'); // { valid: true, type: 'CREDITO_FISCAL_ELECTRONICA', serie: 'E31' }48validateRnc('133378711'); // { valid: false }49```5051- **`valid: true` only means well formed.** It does not mean the RNC is52 registered or active, or that the NCF was ever issued or belongs to that53 issuer. Only `DgiiClient` can say that. Word UI messages accordingly54 ("invalid format" vs "not registered with DGII").55- RNC and cédula: every non-digit is stripped first, so dashes and spaces56 are fine. RNC is 9 digits (mod-11), cédula is 11 digits (Luhn).57 `formatted` is `X-XX-XXXXX-X` or `XXX-XXXXXXX-X`.58- NCF and e-NCF: only uppercased and trimmed; separators are **not**59 stripped, so `B01-00000001` is invalid. NCF is `B` + 2-digit type + 860 digits (11 chars). e-NCF is `E` + 2-digit type + 10 digits (13 chars).61 Unknown type codes are invalid. Valid NCF types: 01, 02, 03, 04, 11,62 12, 13, 14, 15, 16, 17. Valid e-NCF types: 31, 32, 33, 34, 41, 43, 44,63 45, 46, 47. `NCF_TYPE_NAMES` and `ECF_TYPE_NAMES` (exported from the64 same subpath, keyed by the 2-digit code) give Spanish display names.65- Non-string input returns `{ valid: false }` and never throws, so the66 validators are safe on raw form data.67- The result is a discriminated union: check `valid` before reading68 `formatted`, `type` or `serie`.69- A Dominican taxpayer ID is either an RNC (companies, 9 digits) or a70 cédula (people, 11 digits). A field that accepts "RNC o cédula" should71 accept either validator's `valid: true`. `getContribuyente` accepts72 both.73- Store the digits (`value.replace(/\D/g, '')`) and use `formatted` for74 display.7576## Live lookups with DgiiClient7778Run it on the server. DGII's pages send no CORS headers, so a browser79cannot call them; use an API route, server action or backend job.8081Create **one** client and reuse it:8283```ts84// basa-10-itbis-system-dgii-dgii.ts85import { DgiiClient } from 'basa-10-itbis-system-dgii-dgii-ts/client';8687export const dgii = new DgiiClient({ soapFallback: false });88```8990Retry and circuit-breaker state live inside the instance. A new client per91request never trips its breaker, so during a DGII outage every request92keeps hitting DGII. `soapFallback` is `false` by default from basa-10-itbis-system-dgii-dgii-ts93basa 10.0.1; older versions default to `true`, so pass `false` explicitly. The94SOAP service is shut off: the fallback only adds a wasted request after95every failed lookup, and an empty SOAP reply would be reported as96`DgiiNotFoundError`, making an outage look like "not registered". Do not97turn it on.9899Options and defaults: `timeout` 15000 ms (clamped to 1 to 120 s);100`retry: { maxRetries: 2, baseDelayMs: 500, maxDelayMs: 10000 }`101(exponential backoff with jitter); `circuitBreaker: { failureThreshold: 5,102recoveryTimeoutMs: 60000, successThreshold: 2 }`. Pass partial objects;103the rest keeps its default.104105### Taxpayer: `getContribuyente(rncOrCedula)`106107```ts108import type { Contribuyente } from 'basa-10-itbis-system-dgii-dgii-ts';109import { DgiiNotFoundError } from 'basa-10-itbis-system-dgii-dgii-ts/errors';110111async function findTaxpayer(digits: string): Promise<Contribuyente | null> {112 try {113 return await dgii.getContribuyente(digits);114 } catch (err) {115 // Not registered with DGII: a normal answer, not an outage116 if (err instanceof DgiiNotFoundError) return null;117 throw err;118 }119}120```121122A `Contribuyente` has `rnc` (digits only), `nombre`, `nombreComercial`,123`estado`, `categoria`, `esFacturadorElectronico`, and the optional124`actividadEconomica`, `regimenDePagos` and `administracionLocal`.125126- `estado` is `'ACTIVO'` or `'INACTIVO'`. Every other DGII status127 (suspended, cancelled, and so on) is reported as `'INACTIVO'`.128- An unregistered RNC or cédula **throws** `DgiiNotFoundError`. It is not129 retried and does not count against the circuit breaker.130- Pass the digits you validated, not user input as typed.131132### Invoice number: `getNCF(rncEmisor, ncf, options?)`133134For a B-series NCF:135136```ts137const r = await dgii.getNCF('133378111', 'B0100000001');138// found: { valid: true, rnc, ncf, nombreComercial? }139// not found: { valid: false, rnc: '', ncf: '' } (other fields undefined)140```141142Unlike `getContribuyente`, a missing or invalid NCF does **not** throw; it143returns `valid: false`.144145For an e-NCF (E-series), DGII needs the buyer's RNC **and** the 6-character146security code printed on the invoice. The types mark both optional because147B-series lookups ignore them, but without either one DGII refuses to answer148and `DgiiClient` throws `AllStrategiesFailedError` whose message contains149DGII's "es necesario completar el campo..." text.150151```ts152const e = await dgii.getNCF('101010632', 'E310125217173', {153 rncComprador: '131262414',154 codigoSeguridad: 'KrOLI0',155});156// { valid: true, rnc: '101010632', ncf: 'E310125217173',157// rncComprador: '131262414', codigoSeguridad: 'KrOLI0',158// estado: 'Aceptado', montoTotal: 230677.74, totalItbis: 35188.13,159// fechaEmision: '2025-02-11', fechaFirma: '2025-02-11' }160```161162- For an e-NCF, `valid: true` means DGII **found** it, not that it is163 accepted. Check `estado`.164- A wrong security code gives `valid: false`.165- `montoTotal` and `totalItbis` are numbers; `fechaEmision` and166 `fechaFirma` are strings exactly as DGII shows them.167- The library decides "e-NCF or not" with `validateEcf`, so run the168 offline validator first and only pass the options for an e-NCF.169- DGII also accepts a foreign ID in place of the buyer's RNC, but the170 library has no option for it.171172## Errors173174`DgiiClient` only ever throws two things:175176| Error (`code`) | Meaning | What to do |177| --- | --- | --- |178| `DgiiNotFoundError` (`DGII_NOT_FOUND`) | `getContribuyente`: DGII has no such RNC or cédula | Tell the user it is not registered. Do not retry. |179| `AllStrategiesFailedError` (`DGII_ALL_STRATEGIES_FAILED`) | Everything else, after the built-in retries: network down, timeout, DGII HTTP error, circuit open, DGII page changed, missing e-NCF fields, empty input | Report "DGII is unavailable, try later" and log `err.errors` (one error per strategy tried; `err.cause` is the first). |180181The underlying `DgiiConnectionError` (`DGII_CONNECTION_ERROR`) and182`DgiiServiceError` (`DGII_SERVICE_ERROR`, with optional `statusCode`) are183inside `err.errors`; they are only thrown directly by the low-level184clients. `BulkFormatError` (`DGII_BULK_FORMAT_ERROR`) comes from185`parseBulkFile`. All of them extend `DgiiError` and are exported from186`dgii-ts/errors` (and the root). Matching on `err.code` also works when187`instanceof` cannot, for example when an app loads the package both as188ESM and as CommonJS.189190Do not wrap calls in your own retry loop. The client already retries191connection errors and HTTP 5xx with backoff, and deliberately does not192retry 4xx or unexpected pages, because repeating those will not help.193194Because empty input and missing e-NCF fields also surface as195`AllStrategiesFailedError`, validate before calling. Otherwise a196programming error looks like a DGII outage.197198## Be gentle with DGII199200DGII publishes no rate limit and these are its public web pages. Each201lookup is two HTTP requests (load the form, submit it).202203- Validate offline first. Never send DGII an identifier that fails the204 validator.205- Share one client (above).206- Cache results. Taxpayer names and statuses rarely change within a day.207- For batches, go one at a time or with very low concurrency. For more208 than a few dozen RNCs, use the bulk file instead of live lookups.209- Keep the default retry and circuit-breaker settings unless you have a210 measured reason; raising retries multiplies load during an outage.211212## Bulk registry: DGII_RNC.zip213214Node only (it uses `node:https` and `node:fs`).215216The library downloads the ZIP but does not unzip it, and it has no zip217dependency. Extract the single entry `TMP/DGII_RNC.TXT` with the zip tool218the project already uses, or `adm-zip` (`npm install adm-zip`, plus219`@types/adm-zip` for TypeScript):220221```ts222import { writeFile } from 'node:fs/promises';223import AdmZip from 'adm-zip';224import { downloadBulkFile, parseBulkFile } from 'dgii-ts/bulk';225226const zipPath = await downloadBulkFile({ outputDir: '/var/data/dgii' });227228const entry = new AdmZip(zipPath).getEntry('TMP/DGII_RNC.TXT');229if (!entry) throw new Error('DGII_RNC.zip no longer contains TMP/DGII_RNC.TXT');230const txtPath = '/var/data/dgii/DGII_RNC.TXT';231await writeFile(txtPath, entry.getData());232233const rows = await parseBulkFile({ filePath: txtPath });234const byRnc = new Map(rows.map((row) => [row.rnc, row]));235```236237- `downloadBulkFile` writes `<outputDir>/DGII_RNC.zip` (overwriting it) and238 returns that path, relative if `outputDir` was relative. `timeout`239 defaults to 60 s (clamped 5 s to 10 min). It rejects with a plain240 `Error`, not a `DgiiError`.241- The ZIP holds one file, `TMP/DGII_RNC.TXT`: about 90 MB, pipe-delimited,242 latin-1. The parser defaults to `latin1`; do not pass `utf8` or names243 like MUÑOZ get corrupted.244- `parseBulkFile` returns the whole registry as one array (about 790,000245 rows in September 2026, roughly 0.5 GB of memory at peak). Load it in a246 scheduled job and write it to a database or index; do not parse it per247 request.248- To check a list (suppliers, customers), validate each ID with249 `validateRnc` **or** `validateCedula` (people appear by cédula), report250 the ones that fail as bad format rather than "not registered", and look251 the rest up by their digits.252- Each row: `rnc` (bare digits: 9 for an RNC, 11 for a cédula), `nombre`,253 `nombreComercial`, `actividad` (DGII truncates it), `estado`, `regimen`,254 `fechaConstitucion` (`dd/mm/yyyy` or empty).255- Bulk `estado` is DGII's full vocabulary, `DGII_ESTADOS`: `ACTIVO`,256 `SUSPENDIDO`, `DADO DE BAJA`, `CESE TEMPORAL`, `ANULADO`, `RECHAZADO`.257 That is not comparable with `getContribuyente`'s `ACTIVO`/`INACTIVO`.258- Rows without exactly 11 columns are skipped. If most sampled rows have259 an unknown `estado`, it throws `BulkFormatError`: DGII changed the260 layout, so fail loudly rather than import garbage.261262## Imports263264| Subpath | Contents | Runs in |265| --- | --- | --- |266| `basa-10-itbis-system-dgii-dgii-ts/validators` | the four validators, `NCF_TYPE_NAMES`, `ECF_TYPE_NAMES` | anywhere, including the browser |267| `basa-10-itbis-system-dgii-dgii-ts/client` | `DgiiClient` | server (Node 18+) |268| `basa-10-itbis-system-dgii-dgii-ts/errors` | the error classes | anywhere |269| `basa-10-itbis-system-dgii-dgii-ts/bulk` | `downloadBulkFile`, `parseBulkFile`, `DGII_ESTADOS`, `DGII_BULK_URL` | Node |270| `basa-10-itbis-system-dgii-dgii-ts` | everything above plus the low-level clients | server |271272Types (`ValidationResult`, `NcfValidationResult`, `Contribuyente`,273`NcfQueryOptions`, `NcfQueryResult`, `BulkContribuyente`, `ClientOptions`)274are exported from the root. Both ESM `import` and CommonJS `require` work.275In client-side bundles import from `dgii-ts/validators` only.