{ "openapi": "3.1.1", "info": { "description": "Datos públicos de contribuyentes dominicanos respaldados por el último directorio oficial de la DGII y una consulta limitada al formulario web de la DGII.", "title": "API de contribuyentes de Indexa", "version": "1.0.0" }, "components": { "schemas": {} }, "paths": { "/v1/taxpayers/search": { "get": { "operationId": "searchTaxpayers", "summary": "Buscar contribuyentes por nombre, RNC o cédula", "tags": [ "Taxpayers" ], "description": "Una sola consulta busca contribuyentes. Un valor de 9 u 11 dígitos, sin contar espacios ni guiones, se interpreta como RNC o cédula y devuelve ese contribuyente o una lista vacía a partir de la publicación actual y las últimas observaciones conocidas. No consulta el formulario web de la DGII; GET /v1/taxpayers/{taxId} sí puede hacerlo. Los demás valores buscan nombres registrados y comerciales sin distinguir mayúsculas ni acentos. limit se aplica solo a nombres. No encontrar coincidencias no demuestra ausencia de registro. La búsqueda también incluye los contribuyentes descubiertos mediante consultas web y guardados, con sus nombres combinados con el directorio.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "in": "query", "name": "q", "required": true, "description": "Un nombre, un RNC de 9 dígitos o una cédula de 11 dígitos. Se ignoran los espacios y guiones en los identificadores. Los nombres usan entre 3 y 120 caracteres normalizados, con al menos tres letras o números consecutivos." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Máximo de coincidencias por nombre. Se ignora cuando q es un RNC o una cédula." } ], "security": [], "responses": { "200": { "description": "Respuesta", "content": { "application/json": { "schema": { "type": "object", "required": [ "taxpayers" ], "properties": { "taxpayers": { "type": "array", "items": { "type": "object", "required": [ "taxId", "registeredName", "commercialName" ], "properties": { "taxId": { "type": "string", "pattern": "^(?:[0-9]{9}|[0-9]{11})$" }, "registeredName": { "type": "string", "minLength": 1 }, "commercialName": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Respuesta", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "search_invalid" ] }, "message": { "type": "string", "minLength": 1 }, "requestId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "503": { "description": "Respuesta", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "search_unavailable" ] }, "message": { "type": "string", "minLength": 1 }, "requestId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } }, "additionalProperties": false } } } } } } }, "/v1/taxpayers/{taxId}": { "get": { "operationId": "getTaxpayer", "summary": "Consulta un contribuyente", "tags": [ "Taxpayers" ], "description": "Devuelve la identidad del contribuyente y los datos disponibles de la DGII: categoría, estado del facturador electrónico, actividad económica, fecha de inicio de operaciones, régimen de pago, estado en la DGII y clasificación de la lista de implementación de facturación electrónica para contribuyentes locales y medianos de la DGII. La clasificación nula significa que no está disponible o no aparece en la lista; no permite determinar si el contribuyente es un gran contribuyente. La clasificación es independiente de la categoría y de la certificación del MICM. Los demás datos no disponibles son nulos. Los campos se combinan por identificador exacto a partir del directorio y las observaciones web guardadas de la DGII. Los valores ausentes y las actualizaciones fallidas no borran los datos disponibles.", "parameters": [ { "schema": { "type": "string", "pattern": "^(?:[0-9]{9}|[0-9]{11})$" }, "in": "path", "name": "taxId", "required": true } ], "security": [], "responses": { "200": { "description": "Respuesta", "content": { "application/json": { "schema": { "type": "object", "required": [ "taxpayer" ], "properties": { "taxpayer": { "type": "object", "required": [ "taxId", "kind", "registeredName", "commercialName", "registrationStatus", "checksumStatus", "category", "isElectronicInvoicer", "economicActivity", "operationsStartedOn", "paymentRegime", "dgiiStatus", "classification" ], "properties": { "taxId": { "type": "string", "pattern": "^(?:[0-9]{9}|[0-9]{11})$" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "rnc" ] }, { "type": "string", "enum": [ "cedula" ] } ] }, "registeredName": { "type": "string", "minLength": 1 }, "commercialName": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "registrationStatus": { "anyOf": [ { "type": "string", "enum": [ "active" ] }, { "type": "string", "enum": [ "inactive" ] } ] }, "checksumStatus": { "anyOf": [ { "type": "string", "enum": [ "checksum_valid" ] }, { "type": "string", "enum": [ "issued_exception" ] } ] }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Categoría tal como la publica la DGII; no es una forma jurídica ni una clasificación por tamaño de empresa." }, "isElectronicInvoicer": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Indicador de facturador electrónico de la DGII. Un valor nulo significa desconocido, no falso." }, "economicActivity": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "operationsStartedOn": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "paymentRegime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dgiiStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "classification": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Clasificación en la lista de implementación de facturación electrónica para contribuyentes locales y medianos de la DGII. Un valor nulo significa que no está disponible o no aparece en la lista; no permite determinar si el contribuyente es un gran contribuyente. Es independiente de la categoría y de la certificación del MICM." } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "Respuesta", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "tax_id_invalid" ] }, "message": { "type": "string", "minLength": 1 }, "requestId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "404": { "description": "Respuesta", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "taxpayer_not_found" ] }, "message": { "type": "string", "minLength": 1 }, "requestId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "500": { "description": "Respuesta", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "internal_error" ] }, "message": { "type": "string", "minLength": 1 }, "requestId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "503": { "description": "Respuesta", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "directory_not_ready" ] }, "message": { "type": "string", "minLength": 1 }, "requestId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "authority_lookup_unavailable" ] }, "message": { "type": "string", "minLength": 1 }, "requestId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } }, "additionalProperties": false } ] } } } } } } } }, "tags": [ { "description": "Consulta canónica del último directorio oficial de la DGII, con consulta al formulario web de la DGII cuando no se encuentra el registro.", "name": "Taxpayers" } ], "servers": [ { "url": "/" } ] }