# UrbanStock DGII RNC API

> Free, zero-auth REST API and lookup engine for the Dominican Republic DGII National Taxpayer Registry (Padrón Nacional de Contribuyentes — RNC & Cédula), maintained by UrbanStock POS. Automatically synchronized every early morning from official DGII registries with complete legal names (Razón Social), commercial names (Nombre Comercial), economic activity (Actividad Económica), payment regime, start date, and tax status (ACTIVO / SUSPENDIDO / DADO DE BAJA).

- Base URL: https://rnc.urbanstockpos.com
- Country / Jurisdiction: Dominican Republic (República Dominicana — DGII)
- Auth: Public access (no API key required for standard lookups; optional `X-API-Key` header for high-volume POS systems)
- CORS: Enabled (`*`) for browser apps, server backends, and AI agents
- Last updated: 2026-11-07 (797,960 taxpayers indexed)
- Machine specs: [OpenAPI 3.1 JSON](https://rnc.urbanstockpos.com/openapi.json) · [AI Plugin Manifest](https://rnc.urbanstockpos.com/.well-known/ai-plugin.json) · [HTML Docs](https://rnc.urbanstockpos.com/docs) · [Sitemap XML](https://rnc.urbanstockpos.com/sitemap.xml)

## Public Endpoints (Ready for AI Agents & Applications)

- `GET https://rnc.urbanstockpos.com/api/v1/rnc/{rnc}`: Exact lookup by 9-digit RNC (e.g. `1-XX-XXXXX-X` or `1XXXXXXXX`) or 11-digit Cédula (e.g. `001-XXXXXXX-X`), with or without hyphens.
- `GET https://rnc.urbanstockpos.com/api/v1/search?q={name}&estado=ACTIVO&limit=15`: Accent-insensitive fuzzy partial search by legal name (Razón Social) or commercial name (Nombre Comercial). Minimum 3 characters with at least one 3+ letter word. Optional `estado`: `ACTIVO`, `SUSPENDIDO`, `DADO DE BAJA`, `CESE TEMPORAL`, `ANULADO`, `RECHAZADO`. Max `limit`: 25.
- `POST https://rnc.urbanstockpos.com/api/v1/rnc/batch`: Bulk lookup of up to 100 RNC/Cédula values in one JSON body `{"rncs": ["..."]}` (also accepts `GET https://rnc.urbanstockpos.com/api/v1/rnc/batch?rncs=00000000000,000000000`).
- `GET https://rnc.urbanstockpos.com/api/v1/meta` and `GET https://rnc.urbanstockpos.com/health`: Current DGII update date, taxpayer counts, and service availability.

## Non-Real Sandbox Test Examples (Safe Dummy Data)

For connectivity tests or demonstrations without querying real individuals or businesses, this API reserves synthetic test identifiers that return `isTestExample: true`, `isActive: false`, and `estado: "PRUEBA (TEST)"`:

- Test RNC (9 digits): `GET https://rnc.urbanstockpos.com/api/v1/rnc/000000000` (or `0-00-00000-0`)
- Test Cédula (11 digits): `GET https://rnc.urbanstockpos.com/api/v1/rnc/00000000000` (or `000-0000000-0`)
- Test Company Search: `GET https://rnc.urbanstockpos.com/api/v1/search?q=EMPRESA%20DE%20PRUEBA`
- Test Batch: `POST https://rnc.urbanstockpos.com/api/v1/rnc/batch` with `{"rncs":["00000000000","000000000"]}` or `GET https://rnc.urbanstockpos.com/api/v1/rnc/batch?rncs=00000000000,000000000`

*Note for POS / Fiscal Software:* Always verify `data.isActive === true` before issuing NCF / e-CF fiscal credit receipts (B01 / E31). Synthetic test examples always return `isActive: false`.

## Complete Response Schema (`RncRecord`)

| Field | Type | Description |
| --- | --- | --- |
| `rnc` | string | Clean digits only (8–11 digits, no hyphens). Required by DGII 606/607/e-CF XML. |
| `formattedRnc` | string | Official DGII display format: `X-XX-XXXXX-X` for 9-digit RNC or `XXX-XXXXXXX-X` for 11-digit Cédula. |
| `tipoDocumento` | string | `"RNC"`, `"CEDULA"`, or `"OTRO"`. |
| `razonSocial` | string | Complete legal taxpayer name from the official DGII registry. |
| `nombreComercial` | string \| null | Trade/commercial name (when registered). |
| `actividadEconomica` | string | Full economic activity description (up to 199 chars). |
| `fechaInicio` | string \| null | Operations start date (`DD/MM/YYYY`). |
| `estado` | string | Tax status: `ACTIVO`, `SUSPENDIDO`, `DADO DE BAJA`, `CESE TEMPORAL`, `ANULADO`, `RECHAZADO`, or `PRUEBA (TEST)` for synthetic sandbox IDs. |
| `isActive` | boolean | `true` only when real taxpayer `estado === "ACTIVO"`. |
| `regimenPago` | string | Payment regime (e.g. `NORMAL`, `RST`). |
| `isTestExample` | boolean (optional) | Present and `true` only for synthetic demo records (`000000000`, `00000000000`). |

## Example Usage (cURL & JavaScript)

```bash
# Test connectivity with synthetic RNC
curl -s "https://rnc.urbanstockpos.com/api/v1/rnc/000000000"

# Search Dominican businesses by name (active only)
curl -s -G "https://rnc.urbanstockpos.com/api/v1/search" --data-urlencode "q=ferreteria" -d "estado=ACTIVO" -d "limit=10"
```

```ts
const res = await fetch("https://rnc.urbanstockpos.com/api/v1/rnc/000000000");
if (res.ok) {
  const { data } = await res.json();
  console.log(data.formattedRnc, data.razonSocial, data.isActive);
}
```

## HTTP Caching, Rate Limits & Error Handling

- Single lookups return `ETag` + `Cache-Control: public, max-age=3600, s-maxage=21600`. Send `If-None-Match` for ultra-fast `304 Not Modified` responses.
- Public rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `Retry-After` on HTTP `429`.
- HTTP `503` with `Retry-After: 15` may occur briefly only during cold-start initial database loading.