--- title: "API de catálogo" description: "Endpoints v1 de productos, impuestos, retenciones, unidades, términos de pago, monedas y validación de RNC." canonical: https://factura.com.do/desarrolladores/catalogo lang: es generator: factura.com.do docs-index --- Recurso · Catálogo del espacio de trabajo # API de catálogo Las llamadas de catálogo son la base de cualquier integración: productos, impuestos, retenciones, unidades, términos de pago, monedas y validación de RNC. Los identificadores que devuelven se usan en el cuerpo de cada comprobante. ## Resumen El catálogo del espacio de trabajo se gestiona con un patrón uniforme: list paginado, get por id y, para productos, mutaciones (create, update, delete). Los demás recursos (impuestos, retenciones, unidades, términos de pago, monedas) son listas administradas por la plataforma. ## Productos Los productos se reutilizan en facturas, notas y compras. Cada producto define unidad, precio por defecto e impuestos por defecto. Las líneas pueden sobreescribir cualquier campo del producto al emitir. [ GET /api/v1/products X-Api-Key Estable Devuelve un PagedResult de productos del catálogo del espacio de trabajo. ](#) | Nombre | Tipo | Descripción | | ---------------- | ---------------- | ----------------------------------------------------------------------- | | pageNumber query | integer Opcional | Página solicitada. Por defecto 1. | | pageSize query | integer Opcional | Tamaño de página. Por defecto 10\. La API no impone un máximo. | | search query | string Opcional | Filtra por código o nombre del producto. | | isActive query | boolean Opcional | Filtra por estado del producto. Sin valor devuelve activos e inactivos. | [ GET /api/v1/products/{id} X-Api-Key Estable Devuelve el detalle completo de un producto del catálogo. ](#) | Nombre | Tipo | Descripción | | ------- | ----------------------- | --------------------------- | | id path | string (uuid) Requerido | Identificador del producto. | [ POST /api/v1/products X-Api-Key Estable Registra un producto en el catálogo del espacio de trabajo. ](#) | Nombre | Tipo | Descripción | | ---------------- | -------------------------- | -------------------------------------------------------------------------------------- | | code body | string Requerido | Código único del producto en el espacio de trabajo. | | reference body | string Opcional | Referencia interna del producto (alias o código secundario). | | isService body | boolean Opcional | Marca si el producto es un servicio en lugar de un bien físico. Por defecto \`false\`. | | description body | string Requerido | Descripción del producto que se imprime en el comprobante. | | unitId body | integer Requerido | Identificador de la unidad de medida del catálogo. | | price body | decimal Requerido | Precio por defecto. Se puede sobreescribir en cada línea de factura. | | currencyId body | integer Requerido | Identificador de la moneda asociada al precio del producto. | | taxes body | string\[\] (uuid) Opcional | Impuestos por defecto a aplicar en el comprobante. | [ PUT /api/v1/products/{id} X-Api-Key Estable Modifica los datos de un producto del catálogo. ](#) | Nombre | Tipo | Descripción | | ---------------- | -------------------------- | ----------------------------------------------------------------------- | | id path | string (uuid) Requerido | Identificador del producto. | | code body | string Requerido | Código del producto. Debe seguir siendo único en el espacio de trabajo. | | reference body | string Opcional | Referencia interna del producto. | | isService body | boolean Opcional | Marca si el producto es un servicio en lugar de un bien físico. | | description body | string Requerido | Descripción del producto. | | unitId body | integer Requerido | Identificador de la unidad de medida. | | price body | decimal Requerido | Precio por defecto. | | currencyId body | integer Requerido | Identificador de la moneda asociada al precio del producto. | | taxes body | string\[\] (uuid) Opcional | Impuestos por defecto. | [ DELETE /api/v1/products/{id} X-Api-Key Estable Marca un producto como eliminado (soft-delete) sin afectar comprobantes históricos. ](#) | Nombre | Tipo | Descripción | | ------- | ----------------------- | --------------------------- | | id path | string (uuid) Requerido | Identificador del producto. | ### Ejemplo: crear producto POST /api/v1/products cURL create-product.sh ``` curl -X POST https://tuempresa.factura.com.do/api/v1/products \ -H "X-Api-Key: $FACTURA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "code": "SRV-001", "reference": "CONS", "isService": true, "description": "Consultoría", "unitId": 1, "price": 4500.00, "currencyId": 1, "taxes": ["3a5e98e0-33ff-44be-bd37-e3f9b35a25e2"] }' ``` Respuesta response.json ``` { "productId": "2d7e9b1c-4a6f-4e3d-8b2a-9c1f0e5d7a38", "success": true, "message": "The product has been successfully saved" } ``` ## Impuestos y retenciones Listas administradas por la plataforma. Los impuestos cubren ITBIS, ISC y demás tributos. Las retenciones cubren los esquemas de retención obligatorios en pagos a proveedores y a no domiciliados. [ GET /api/v1/taxes X-Api-Key Estable Devuelve el catálogo de impuestos vigentes en República Dominicana. ](#) | Nombre | Tipo | Descripción | | ---------------- | ---------------- | -------------------------------------------------------------- | | search query | string Opcional | Filtra por nombre o código del impuesto. | | pageNumber query | integer Opcional | Página solicitada. Por defecto 1. | | pageSize query | integer Opcional | Tamaño de página. Por defecto 10\. La API no impone un máximo. | [ GET /api/v1/withholdings X-Api-Key Estable Devuelve el catálogo de retenciones vigentes en República Dominicana. ](#) | Nombre | Tipo | Descripción | | ---------------- | ---------------- | -------------------------------------------------------------- | | search query | string Opcional | Filtra por nombre de la retención. | | pageNumber query | integer Opcional | Página solicitada. Por defecto 1. | | pageSize query | integer Opcional | Tamaño de página. Por defecto 10\. La API no impone un máximo. | ### Ejemplo: respuesta de impuestos taxes-list.json ``` { "items": [ { "taxId": "3a5e98e0-33ff-44be-bd37-e3f9b35a25e2", "taxName": "ITBIS", "taxTypeId": 1, "taxTypeName": "ITBIS", "taxRate": "18.00", "stillValid": true, "taxCode": "ITBIS18", "isExempt": false, "sequenceTypeId": [1, 2, 7, 8, 9], "fullName": ["ITBIS 18%"] } ], "totalCount": 1, "pageNumber": 1, "pageSize": 10, "totalPages": 1 } ``` ## Unidades y términos de pago Las unidades de medida (unidad, hora, kilo, litro, servicio, etc.) y los términos de pago (las plantillas nuevas traen crédito a 15, 30, 50, 70 y 90 días; no hay uno de contado sembrado) son listas con identificadores que se usan al crear productos y al emitir comprobantes. [ GET /api/v1/units X-Api-Key Estable Devuelve el catálogo de unidades de medida (codificadas por la DGII). ](#) | Nombre | Tipo | Descripción | | ------------ | --------------- | --------------------------------------------------------------------------------- | | search query | string Opcional | Filtra por nombre de la unidad. La API devuelve la lista completa sin paginación. | [ GET /api/v1/payment-terms X-Api-Key Estable Devuelve el catálogo de términos de pago configurados en el espacio de trabajo. ](#) | Nombre | Tipo | Descripción | | ---------------- | ---------------- | -------------------------------------------------------------- | | search query | string Opcional | Filtra por nombre del término de pago. | | pageNumber query | integer Opcional | Página solicitada. Por defecto 1. | | pageSize query | integer Opcional | Tamaño de página. Por defecto 10\. La API no impone un máximo. | ## Monedas Las monedas disponibles incluyen DOP, USD y EUR como mínimo. La tasa de cambio se envía en el cuerpo del comprobante (`currencyRate`) y la API la persiste sin recalcularla. [ GET /api/v1/currencies X-Api-Key Estable Devuelve el catálogo de monedas disponibles para emisión de comprobantes. ](#) | Nombre | Tipo | Descripción | | ---------------- | ---------------- | -------------------------------------------------------------- | | search query | string Opcional | Filtra por nombre, código o símbolo de la moneda. | | pageNumber query | integer Opcional | Página solicitada. Por defecto 1. | | pageSize query | integer Opcional | Tamaño de página. Por defecto 10\. La API no impone un máximo. | ## Validación de RNC Consulta el RNC antes de crear un cliente o un proveedor: esas rutas no lo validan contra la DGII. La API reenvía la consulta al servicio de contribuyentes y devuelve el cuerpo tal cual, **plano y en español**: `rncCedula`, `razonSocial`, `nombreComercial`, `categoria`, `regimenPagos`, `estado`, `actividadEconomica`, `administracionLocal`, `facturadorElectronico` y `licenciasComercializacionVhm`. No hay envoltorio `contributor` ni campo `isSuccess`. Si el servicio responde con error (por ejemplo, porque el RNC no existe), la API responde `404` con `{ message }`. [ GET /api/v1/rnc/{rnc} X-Api-Key Estable Consulta un RNC o cédula en el servicio de contribuyentes de la DGII y devuelve sus datos tal como llegan. ](#) | Nombre | Tipo | Descripción | | -------- | ---------------- | ----------------------------------------------- | | rnc path | string Requerido | RNC a consultar. Acepta formato 9 u 11 dígitos. | GET /api/v1/rnc/{rnc} cURL TypeScript validate-rnc.sh ``` curl -X GET https://tuempresa.factura.com.do/api/v1/rnc/131000001 \ -H "X-Api-Key: $FACTURA_API_KEY" ``` validate-rnc.ts ``` const res = await fetch( `https://tuempresa.factura.com.do/api/v1/rnc/${rnc}`, { headers: { "X-Api-Key": process.env.FACTURA_API_KEY! }, }, ); if (!res.ok) throw new Error(`factura.com.do: ${res.status}`); const payload = await res.json(); // cuerpo plano: payload.razonSocial, payload.estado, payload.facturadorElectronico… // 404 con { message } cuando el servicio responde con error ``` Respuesta response.json ``` { "rncCedula": "131000001", "razonSocial": "EMPRESA RECEPTORA SRL", "nombreComercial": "EMPRESA RECEPTORA", "categoria": "…", "regimenPagos": "…", "estado": "…", "actividadEconomica": "…", "administracionLocal": "…", "facturadorElectronico": "SI", "licenciasComercializacionVhm": "…" } ``` Es un proxy, no una validación de formato El endpoint reenvía la consulta al servicio Nubeteck DGII y devuelve su payload tal cual; no valida la cifra de control localmente. Cualquier cambio en el padrón se ve en la siguiente consulta. Cachea el resultado solo durante la transacción que estás procesando. ## Consultas planas para integraciones Estas rutas devuelven arreglos planos, sin paginación, pensados para llenar selectores. Nacieron para los plugins instalados, pero también aceptan la `X-Api-Key`. `accounts` es la excepción: es paginada y la sirve el plugin de contabilidad, así que responde `503` si está instalado pero no contesta. [ GET /api/v1/payment-methods X-Api-Key Estable Devuelve las formas de pago de la empresa como arreglo plano, con id, name, isCredit y codigoDgii. ](#) [ GET /api/v1/company-branding X-Api-Key Estable Devuelve nombre comercial, razón social, RNC, contacto, dirección y el logo en base64 de la empresa; si no hay logo, el de factura.com.do. ](#) [ GET /api/v1/accounts X-Api-Key Estable Devuelve, paginado, el catálogo de cuentas del plugin de contabilidad. Responde 503 si el plugin está instalado pero no contesta. ](#) | Nombre | Tipo | Descripción | | ------------------ | ---------------- | --------------------------------------------------------------------------------------------- | | search query | string Opcional | Filtra por código o nombre de la cuenta. | | pageNumber query | integer Opcional | Página solicitada. Por defecto 1. | | pageSize query | integer Opcional | Tamaño de página. Por defecto 100, máximo 500. | | isActive query | boolean Opcional | Filtra por cuentas activas o inactivas. | | postableOnly query | boolean Opcional | Con \`true\`, devuelve solo las cuentas que admiten asientos. Por defecto se devuelven todas. | [ GET /api/v1/currencies-lookup X-Api-Key Estable Devuelve hasta 100 monedas como arreglo plano (currencyId, code, symbol, name, isActive), incluidas las inactivas. ](#) [ GET /api/v1/countries-lookup X-Api-Key Estable Devuelve los países como arreglo plano (countryId, name), ordenados por nombre. ](#) [ GET /api/v1/taxes-lookup X-Api-Key Estable Devuelve los impuestos vigentes como arreglo plano (taxId, taxName, taxTypeName, taxRate, isExempt, taxCode). ](#) [ GET /api/v1/withholdings-lookup X-Api-Key Estable Devuelve las retenciones vigentes como arreglo plano (withholdingId, withholdingName, rate, isBaseOnTax). ](#) [ GET /api/v1/customers-lookup X-Api-Key Estable Devuelve clientes activos como arreglo plano (id, legalName, taxIdentification, phone, email). ](#) | Nombre | Tipo | Descripción | | -------------- | ---------------- | ---------------------------------------------- | | search query | string Opcional | Término de búsqueda. | | pageSize query | integer Opcional | Cantidad máxima de resultados. Por defecto 20. | [ GET /api/v1/suppliers-lookup X-Api-Key Estable Devuelve proveedores activos como arreglo plano (id, legalName, taxIdentification, phone, email). ](#) | Nombre | Tipo | Descripción | | -------------- | ---------------- | ---------------------------------------------- | | search query | string Opcional | Término de búsqueda. | | pageSize query | integer Opcional | Cantidad máxima de resultados. Por defecto 20. | [ GET /api/v1/users-lookup X-Api-Key Estable Devuelve todos los usuarios del espacio de trabajo, incluidos los inactivos, como arreglo plano (id, name, email). ](#) [ POST /api/v1/products/documents/lookup X-Api-Key Estable Devuelve el detalle resumido (monto, estado, secuencia…) de los documentos cuyos ids envías. ](#) | Nombre | Tipo | Descripción | | ---------------- | --------------------------- | -------------------------------------------------------------------------------- | | documentIds body | string (uuid)\[\] Requerido | Ids de los documentos. Se descartan los repetidos y se procesan como máximo 200. | ## Siguientes pasos Siguiente paso ## Continúa por aquí - [ Contactos Crea clientes o proveedores apoyado en la validación de RNC. ](/desarrolladores/contactos) - [ Facturas Usa los identificadores de producto, impuesto y unidad al emitir. ](/desarrolladores/facturas) - [ Paginación Convención PagedResult para listar productos, impuestos y monedas. ](/desarrolladores/paginacion)