Recurso · Clientes y proveedores

API de contactos

Dos slices simétricos: /customers y /suppliers. Comparten la misma forma de cuerpo y los mismos verbos (list, get, create, update, delete). La diferencia es a qué tipo de comprobante se asocian al usar el contacto: clientes en E31/E32, proveedores en E41.

Resumen

Un contacto (cliente o proveedor) reside en el espacio de trabajo y se reutiliza en cada comprobante. El cuerpo es simétrico para ambos slices: identificationTypeId, taxIdentification, legalName, phone, email, address más la ubicación (countryId, provinceId?, municipalityId?). El handler no consulta el padrón DGII al guardar; los chequeos vivos son los que listamos abajo.

La diferencia entre customers y suppliers: en clientes taxIdentification es obligatorio y se valida unicidad por espacio de trabajo (rechaza duplicados con { success: false, message: "Un cliente con esta identificación ya existe en el sistema" }); en proveedores taxIdentification es opcional, no se valida unicidad y la bandera isRegisteredInDGII decide después si el proveedor entra en el flujo E41 (informal) o si tu sistema debe esperar un E31 emitido por él.

Clientes

Los clientes se asocian a comprobantes de venta (E31, E32, E33, E34). Al emitir el comprobante el handler de facturas vuelve a validar que el cliente referenciado esté activo (customer.IsActive); si está inactivo responde 400 con El cliente está inactivo y no puede ser utilizado en documentos.

GET /api/v1/customers X-Api-Key Estable

Devuelve un PagedResult de clientes registrados en el 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 RNC, nombre o correo del cliente.
`isActive` query	`boolean` Opcional	Filtra por estado del cliente. Sin valor devuelve activos e inactivos.

GET /api/v1/customers/{id} X-Api-Key Estable

Devuelve el detalle completo de un cliente.

Nombre	Tipo	Descripción
`id` path	`string (uuid)` Requerido	Identificador del cliente.

POST /api/v1/customers X-Api-Key Estable

Registra un cliente en el espacio de trabajo.

Nombre	Tipo	Descripción
`identificationTypeId` body	`integer` Requerido	Tipo de identificación tributaria (RNC, cédula, pasaporte, etc.) según el catálogo.
`taxIdentification` body	`string` Requerido	Número de identificación tributaria (RNC o cédula). La API no lo consulta en la DGII; si quieres verificarlo, usa antes `GET /api/v1/rnc/{rnc}`. Rechaza un número que ya exista en otro cliente.
`countryId` body	`integer` Requerido	Identificador del país del cliente.
`provinceId` body	`integer` Opcional	Identificador de la provincia del cliente.
`municipalityId` body	`integer` Opcional	Identificador del municipio del cliente.
`legalName` body	`string` Requerido	Razón social o nombre legal del cliente.
`phone` body	`string` Requerido	Teléfono de contacto del cliente.
`email` body	`string` Requerido	Correo del cliente para envío de comprobantes.
`address` body	`string` Requerido	Dirección física del cliente.
`defaultSecuenceTypeId` body	`integer` Opcional	Tipo de NCF por defecto a usar cuando se emite un comprobante a este cliente.
`isRegisteredInDGII` body	`boolean` Opcional	Marca si el cliente está formalmente inscrito en la DGII.
`withholdings` body	`string[] (uuid)` Opcional	Retenciones por defecto aplicables a este cliente.

PUT /api/v1/customers/{id} X-Api-Key Estable

Modifica los datos de un cliente existente.

Nombre	Tipo	Descripción
`id` path	`string (uuid)` Requerido	Identificador del cliente.
`identificationTypeId` body	`integer` Requerido	Tipo de identificación tributaria.
`taxIdentification` body	`string` Requerido	Número de identificación tributaria (RNC o cédula). La API no lo consulta en la DGII.
`countryId` body	`integer` Requerido	Identificador del país del cliente.
`provinceId` body	`integer` Opcional	Identificador de la provincia del cliente.
`municipalityId` body	`integer` Opcional	Identificador del municipio del cliente.
`legalName` body	`string` Requerido	Razón social o nombre legal del cliente.
`phone` body	`string` Requerido	Teléfono de contacto del cliente.
`email` body	`string` Requerido	Correo del cliente.
`address` body	`string` Requerido	Dirección física del cliente.
`defaultSecuenceTypeId` body	`integer` Opcional	Tipo de NCF por defecto para este cliente.
`isRegisteredInDGII` body	`boolean` Opcional	Marca si el cliente está formalmente inscrito en la DGII.
`withholdings` body	`string[] (uuid)` Opcional	Retenciones por defecto aplicables a este cliente.

DELETE /api/v1/customers/{id} X-Api-Key Estable

Marca un cliente como eliminado (soft-delete) sin afectar comprobantes históricos.

Nombre	Tipo	Descripción
`id` path	`string (uuid)` Requerido	Identificador del cliente.

Ejemplo: crear cliente con RNC

POST /api/v1/customers

cURL TypeScript

curl -X POST https://tuempresa.factura.com.do/api/v1/customers \
  -H "X-Api-Key: $FACTURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identificationTypeId": 1,
    "taxIdentification": "131000001",
    "countryId": 214,
    "provinceId": 1,
    "municipalityId": 1,
    "legalName": "Empresa Receptora SRL",
    "phone": "+1-809-555-0100",
    "email": "facturas@empresa-receptora.do",
    "address": "Av. 27 de Febrero 100, Santo Domingo"
  }'

const res = await fetch(
  "https://tuempresa.factura.com.do/api/v1/customers",
  {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.FACTURA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      identificationTypeId: 1,
      taxIdentification: "131000001",
      countryId: 214,
      legalName: "Empresa Receptora SRL",
      phone: "+1-809-555-0100",
      email: "facturas@empresa-receptora.do",
      address: "Av. 27 de Febrero 100, Santo Domingo",
    }),
  },
);
if (!res.ok) throw new Error(`factura.com.do: ${res.status}`);
const { customerId, success, message } = await res.json();

Respuesta

{
  "customerId": "5f0c3a8e-2b7d-4c1e-9a6f-3d8b2e1c7a40",
  "success": true,
  "message": "The customer has been successfully saved"
}

Ejemplo: identificación duplicada

El slice de clientes verifica unicidad de taxIdentification dentro del espacio de trabajo; si ya existe otro cliente con el mismo valor responde con 200 OK y success: false (mismo patrón que void). Lee siempre success antes de asumir alta.

{
  "customerId": "00000000-0000-0000-0000-000000000000",
  "success": false,
  "message": "Un cliente con esta identificación ya existe en el sistema"
}

Proveedores

Los proveedores se asocian a comprobantes de compra (E41). taxIdentification es opcional en el DTO; lo que decide el flujo es la bandera isRegisteredInDGII: en false el proveedor se considera informal y la API te deja emitir un E41 a su nombre, en true el handler bloquea el E41 (ese proveedor debe emitir su propio E31). Para egresos sin proveedor identificable usa el flujo de gasto menor (E43).

GET /api/v1/suppliers X-Api-Key Estable

Devuelve un PagedResult de proveedores registrados en el 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 RNC, nombre o correo del proveedor.
`isActive` query	`boolean` Opcional	Filtra por estado del proveedor. Sin valor devuelve activos e inactivos.

GET /api/v1/suppliers/{id} X-Api-Key Estable

Devuelve el detalle completo de un proveedor.

Nombre	Tipo	Descripción
`id` path	`string (uuid)` Requerido	Identificador del proveedor.

POST /api/v1/suppliers X-Api-Key Estable

Registra un proveedor en el espacio de trabajo.

Nombre	Tipo	Descripción
`identificationTypeId` body	`integer` Requerido	Tipo de identificación tributaria del proveedor (RNC, cédula, etc.).
`taxIdentification` body	`string` Opcional	Número de identificación tributaria (RNC o cédula). La API no lo consulta en la DGII; si quieres verificarlo, usa antes `GET /api/v1/rnc/{rnc}`.
`countryId` body	`integer` Requerido	Identificador del país del proveedor.
`provinceId` body	`integer` Opcional	Identificador de la provincia del proveedor.
`municipalityId` body	`integer` Opcional	Identificador del municipio del proveedor.
`legalName` body	`string` Requerido	Razón social o nombre legal del proveedor.
`phone` body	`string` Requerido	Teléfono de contacto del proveedor.
`email` body	`string` Requerido	Correo del proveedor.
`address` body	`string` Requerido	Dirección física del proveedor.
`defaultSecuenceTypeId` body	`integer` Opcional	Tipo de NCF por defecto a usar al registrar una compra a este proveedor.
`isRegisteredInDGII` body	`boolean` Opcional	Marca si el proveedor está formalmente inscrito en la DGII.
`withholdings` body	`string[] (uuid)` Opcional	Retenciones por defecto aplicables a este proveedor.

PUT /api/v1/suppliers/{id} X-Api-Key Estable

Modifica los datos de un proveedor existente.

Nombre	Tipo	Descripción
`id` path	`string (uuid)` Requerido	Identificador del proveedor.
`identificationTypeId` body	`integer` Requerido	Tipo de identificación tributaria.
`taxIdentification` body	`string` Opcional	Número de identificación tributaria (RNC o cédula). La API no lo consulta en la DGII.
`countryId` body	`integer` Requerido	Identificador del país del proveedor.
`provinceId` body	`integer` Opcional	Identificador de la provincia del proveedor.
`municipalityId` body	`integer` Opcional	Identificador del municipio del proveedor.
`legalName` body	`string` Requerido	Razón social o nombre legal del proveedor.
`phone` body	`string` Requerido	Teléfono de contacto del proveedor.
`email` body	`string` Requerido	Correo del proveedor.
`address` body	`string` Requerido	Dirección física del proveedor.
`defaultSecuenceTypeId` body	`integer` Opcional	Tipo de NCF por defecto para este proveedor.
`isRegisteredInDGII` body	`boolean` Opcional	Marca si el proveedor está formalmente inscrito en la DGII.
`withholdings` body	`string[] (uuid)` Opcional	Retenciones por defecto aplicables a este proveedor.

DELETE /api/v1/suppliers/{id} X-Api-Key Estable

Marca un proveedor como eliminado (soft-delete) sin afectar comprobantes históricos.

Nombre	Tipo	Descripción
`id` path	`string (uuid)` Requerido	Identificador del proveedor.

Ejemplo: crear proveedor

curl -X POST https://tuempresa.factura.com.do/api/v1/suppliers \
  -H "X-Api-Key: $FACTURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identificationTypeId": 1,
    "taxIdentification": "131000002",
    "countryId": 214,
    "legalName": "Insumos Generales SRL",
    "phone": "+1-809-555-0200",
    "email": "ventas@insumos.do",
    "address": "Calle Duarte 45, Santiago",
    "isRegisteredInDGII": true
  }'

Validación de RNC

El handler de contactos no consulta el padrón DGII al guardar; solo verifica unicidad de taxIdentification en clientes. Si tu integración necesita confirmar que un RNC existe en el padrón antes de registrarlo, usa el endpoint dedicado GET /api/v1/rnc/{rnc} documentado en catálogo; ese endpoint sí golpea el padrón en tiempo real.

Siguientes pasos

Siguiente paso