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.

Example: create a product

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"]
  }'

{
  "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.

Example: taxes response

{
  "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.

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.

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 }.

curl -X GET https://tuempresa.factura.com.do/api/v1/rnc/131000001 \
  -H "X-Api-Key: $FACTURA_API_KEY"

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

{
  "rncCedula": "131000001",
  "razonSocial": "EMPRESA RECEPTORA SRL",
  "nombreComercial": "EMPRESA RECEPTORA",
  "categoria": "…",
  "regimenPagos": "…",
  "estado": "…",
  "actividadEconomica": "…",
  "administracionLocal": "…",
  "facturadorElectronico": "SI",
  "licenciasComercializacionVhm": "…"
}

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.

Next steps