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.

Ejemplo: crear producto

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

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.

Ejemplo: respuesta de impuestos

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

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.

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

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": "…"
}

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.

Siguientes pasos