--- title: "Catalog API" description: "v1 endpoints for products, taxes, withholdings, units, payment terms, currencies and RNC validation." canonical: https://factura.com.do/en/desarrolladores/catalogo lang: en generator: factura.com.do docs-index --- Resource · Workspace catalog # Catalog API Catalog calls are the foundation of any integration: products, taxes, withholdings, units, payment terms, currencies and RNC validation. The identifiers they return are used in the body of every document. ## Overview The workspace catalog is managed with a uniform pattern: paginated list, get by id and, for products, mutations (create, update, delete). The other resources (taxes, withholdings, units, payment terms, currencies) are platform-managed lists. ## Products Products are reused across invoices, notes and purchases. Each product defines a default unit, default price and default taxes. Lines can override any product field at issuance time. [ GET /api/v1/products X-Api-Key Stable Devuelve un PagedResult de productos del catálogo del espacio de trabajo. ](#) | Name | Type | Description | | ---------------- | ---------------- | ----------------------------------------------------------------------- | | pageNumber query | integer Optional | Página solicitada. Por defecto 1. | | pageSize query | integer Optional | Tamaño de página. Por defecto 10\. La API no impone un máximo. | | search query | string Optional | Filtra por código o nombre del producto. | | isActive query | boolean Optional | Filtra por estado del producto. Sin valor devuelve activos e inactivos. | [ GET /api/v1/products/{id} X-Api-Key Stable Devuelve el detalle completo de un producto del catálogo. ](#) | Name | Type | Description | | ------- | ---------------------- | --------------------------- | | id path | string (uuid) Required | Identificador del producto. | [ POST /api/v1/products X-Api-Key Stable Registra un producto en el catálogo del espacio de trabajo. ](#) | Name | Type | Description | | ---------------- | -------------------------- | -------------------------------------------------------------------------------------- | | code body | string Required | Código único del producto en el espacio de trabajo. | | reference body | string Optional | Referencia interna del producto (alias o código secundario). | | isService body | boolean Optional | Marca si el producto es un servicio en lugar de un bien físico. Por defecto \`false\`. | | description body | string Required | Descripción del producto que se imprime en el comprobante. | | unitId body | integer Required | Identificador de la unidad de medida del catálogo. | | price body | decimal Required | Precio por defecto. Se puede sobreescribir en cada línea de factura. | | currencyId body | integer Required | Identificador de la moneda asociada al precio del producto. | | taxes body | string\[\] (uuid) Optional | Impuestos por defecto a aplicar en el comprobante. | [ PUT /api/v1/products/{id} X-Api-Key Stable Modifica los datos de un producto del catálogo. ](#) | Name | Type | Description | | ---------------- | -------------------------- | ----------------------------------------------------------------------- | | id path | string (uuid) Required | Identificador del producto. | | code body | string Required | Código del producto. Debe seguir siendo único en el espacio de trabajo. | | reference body | string Optional | Referencia interna del producto. | | isService body | boolean Optional | Marca si el producto es un servicio en lugar de un bien físico. | | description body | string Required | Descripción del producto. | | unitId body | integer Required | Identificador de la unidad de medida. | | price body | decimal Required | Precio por defecto. | | currencyId body | integer Required | Identificador de la moneda asociada al precio del producto. | | taxes body | string\[\] (uuid) Optional | Impuestos por defecto. | [ DELETE /api/v1/products/{id} X-Api-Key Stable Marca un producto como eliminado (soft-delete) sin afectar comprobantes históricos. ](#) | Name | Type | Description | | ------- | ---------------------- | --------------------------- | | id path | string (uuid) Required | Identificador del producto. | ### Example: create a product 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"] }' ``` Response response.json ``` { "productId": "2d7e9b1c-4a6f-4e3d-8b2a-9c1f0e5d7a38", "success": true, "message": "The product has been successfully saved" } ``` ## Taxes and withholdings Platform-managed lists. Taxes cover ITBIS, ISC and other levies. Withholdings cover the mandatory withholding schemes for supplier payments and payments to non-domiciled parties. [ GET /api/v1/taxes X-Api-Key Stable Devuelve el catálogo de impuestos vigentes en República Dominicana. ](#) | Name | Type | Description | | ---------------- | ---------------- | -------------------------------------------------------------- | | search query | string Optional | Filtra por nombre o código del impuesto. | | pageNumber query | integer Optional | Página solicitada. Por defecto 1. | | pageSize query | integer Optional | Tamaño de página. Por defecto 10\. La API no impone un máximo. | [ GET /api/v1/withholdings X-Api-Key Stable Devuelve el catálogo de retenciones vigentes en República Dominicana. ](#) | Name | Type | Description | | ---------------- | ---------------- | -------------------------------------------------------------- | | search query | string Optional | Filtra por nombre de la retención. | | pageNumber query | integer Optional | Página solicitada. Por defecto 1. | | pageSize query | integer Optional | Tamaño de página. Por defecto 10\. La API no impone un máximo. | ### Example: taxes response 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 } ``` ## Units and payment terms Units of measure (unit, hour, kilogram, litre, service, etc.) and payment terms (new workspaces come with 15, 30, 50, 70 and 90-day credit; no cash term is seeded) are lists with identifiers used when creating products and issuing documents. [ GET /api/v1/units X-Api-Key Stable Devuelve el catálogo de unidades de medida (codificadas por la DGII). ](#) | Name | Type | Description | | ------------ | --------------- | --------------------------------------------------------------------------------- | | search query | string Optional | Filtra por nombre de la unidad. La API devuelve la lista completa sin paginación. | [ GET /api/v1/payment-terms X-Api-Key Stable Devuelve el catálogo de términos de pago configurados en el espacio de trabajo. ](#) | Name | Type | Description | | ---------------- | ---------------- | -------------------------------------------------------------- | | search query | string Optional | Filtra por nombre del término de pago. | | pageNumber query | integer Optional | Página solicitada. Por defecto 1. | | pageSize query | integer Optional | Tamaño de página. Por defecto 10\. La API no impone un máximo. | ## Currencies Available currencies include DOP, USD and EUR at minimum. The exchange rate is sent in the document body (`currencyRate`) and the API persists it without recalculating. [ GET /api/v1/currencies X-Api-Key Stable Devuelve el catálogo de monedas disponibles para emisión de comprobantes. ](#) | Name | Type | Description | | ---------------- | ---------------- | -------------------------------------------------------------- | | search query | string Optional | Filtra por nombre, código o símbolo de la moneda. | | pageNumber query | integer Optional | Página solicitada. Por defecto 1. | | pageSize query | integer Optional | Tamaño de página. Por defecto 10\. La API no impone un máximo. | ## RNC validation Query the RNC before creating a customer or supplier: those routes do not validate it against the DGII. The API forwards the query to the taxpayer service and returns the body as-is, **flat and with Spanish field names**: `rncCedula`, `razonSocial`, `nombreComercial`, `categoria`, `regimenPagos`, `estado`, `actividadEconomica`, `administracionLocal`, `facturadorElectronico` and `licenciasComercializacionVhm`. There is no `contributor` wrapper and no `isSuccess` field. If the service responds with an error (for example, because the RNC does not exist), the API responds `404` with `{ message }`. [ GET /api/v1/rnc/{rnc} X-Api-Key Stable Consulta un RNC o cédula en el servicio de contribuyentes de la DGII y devuelve sus datos tal como llegan. ](#) | Name | Type | Description | | -------- | --------------- | ----------------------------------------------- | | rnc path | string Required | 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 ``` Response response.json ``` { "rncCedula": "131000001", "razonSocial": "EMPRESA RECEPTORA SRL", "nombreComercial": "EMPRESA RECEPTORA", "categoria": "…", "regimenPagos": "…", "estado": "…", "actividadEconomica": "…", "administracionLocal": "…", "facturadorElectronico": "SI", "licenciasComercializacionVhm": "…" } ``` This is a proxy, not a format validator The endpoint forwards the query to the Nubeteck DGII service and returns its payload as-is; it does not validate the check digit locally. Any change in the registry is visible on the next query. Cache the result only for the duration of the transaction you are processing. ## Flat lookups for integrations These routes return flat arrays, without pagination, meant to fill selectors. They were built for installed plugins, but they also accept the `X-Api-Key`. `accounts` is the exception: it is paginated and served by the accounting plugin, so it responds `503` if the plugin is installed but does not answer. [ GET /api/v1/payment-methods X-Api-Key Stable 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 Stable 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 Stable Devuelve, paginado, el catálogo de cuentas del plugin de contabilidad. Responde 503 si el plugin está instalado pero no contesta. ](#) | Name | Type | Description | | ------------------ | ---------------- | --------------------------------------------------------------------------------------------- | | search query | string Optional | Filtra por código o nombre de la cuenta. | | pageNumber query | integer Optional | Página solicitada. Por defecto 1. | | pageSize query | integer Optional | Tamaño de página. Por defecto 100, máximo 500. | | isActive query | boolean Optional | Filtra por cuentas activas o inactivas. | | postableOnly query | boolean Optional | Con \`true\`, devuelve solo las cuentas que admiten asientos. Por defecto se devuelven todas. | [ GET /api/v1/currencies-lookup X-Api-Key Stable Devuelve hasta 100 monedas como arreglo plano (currencyId, code, symbol, name, isActive), incluidas las inactivas. ](#) [ GET /api/v1/countries-lookup X-Api-Key Stable Devuelve los países como arreglo plano (countryId, name), ordenados por nombre. ](#) [ GET /api/v1/taxes-lookup X-Api-Key Stable Devuelve los impuestos vigentes como arreglo plano (taxId, taxName, taxTypeName, taxRate, isExempt, taxCode). ](#) [ GET /api/v1/withholdings-lookup X-Api-Key Stable Devuelve las retenciones vigentes como arreglo plano (withholdingId, withholdingName, rate, isBaseOnTax). ](#) [ GET /api/v1/customers-lookup X-Api-Key Stable Devuelve clientes activos como arreglo plano (id, legalName, taxIdentification, phone, email). ](#) | Name | Type | Description | | -------------- | ---------------- | ---------------------------------------------- | | search query | string Optional | Término de búsqueda. | | pageSize query | integer Optional | Cantidad máxima de resultados. Por defecto 20. | [ GET /api/v1/suppliers-lookup X-Api-Key Stable Devuelve proveedores activos como arreglo plano (id, legalName, taxIdentification, phone, email). ](#) | Name | Type | Description | | -------------- | ---------------- | ---------------------------------------------- | | search query | string Optional | Término de búsqueda. | | pageSize query | integer Optional | Cantidad máxima de resultados. Por defecto 20. | [ GET /api/v1/users-lookup X-Api-Key Stable 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 Stable Devuelve el detalle resumido (monto, estado, secuencia…) de los documentos cuyos ids envías. ](#) | Name | Type | Description | | ---------------- | -------------------------- | -------------------------------------------------------------------------------- | | documentIds body | string (uuid)\[\] Required | Ids de los documentos. Se descartan los repetidos y se procesan como máximo 200. | ## Next steps Next step ## Continue here - [ Contacts Create customers or suppliers backed by RNC validation. ](/en/desarrolladores/contactos) - [ Invoices Use product, tax and unit identifiers when issuing documents. ](/en/desarrolladores/facturas) - [ Pagination PagedResult convention for listing products, taxes and currencies. ](/en/desarrolladores/paginacion)