Resource · Customers and suppliers

Contacts API

Two symmetric slices: /customers and /suppliers. They share the same request body shape and the same verbs (list, get, create, update, delete). The difference is which document type the contact is associated with: customers in E31/E32, suppliers in E41.

Overview

A contact (customer or supplier) lives in the workspace and is reused in every document. The body is symmetric for both slices: identificationTypeId, taxIdentification, legalName, phone, email, address plus location fields (countryId, provinceId?, municipalityId?). The handler does not query the DGII registry on save; the live checks are listed below.

The difference between customers and suppliers: for customers, taxIdentification is required and uniqueness is validated per workspace (rejects duplicates with { success: false, message: "Un cliente con esta identificación ya existe en el sistema" }); for suppliers, taxIdentification is optional, uniqueness is not validated, and the isRegisteredInDGII flag later decides whether the supplier enters the E41 flow (informal) or whether your system should wait for an E31 they issue themselves.

Customers

Customers are associated with sales documents (E31, E32, E33, E34). When issuing a document the invoice handler re-validates that the referenced customer is active (customer.IsActive); if inactive it responds 400 with El cliente está inactivo y no puede ser utilizado en documentos.

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

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

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

Devuelve el detalle completo de un cliente.

Name	Type	Description
`id` path	`string (uuid)` Required	Identificador del cliente.

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

Registra un cliente en el espacio de trabajo.

Name	Type	Description
`identificationTypeId` body	`integer` Required	Tipo de identificación tributaria (RNC, cédula, pasaporte, etc.) según el catálogo.
`taxIdentification` body	`string` Required	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` Required	Identificador del país del cliente.
`provinceId` body	`integer` Optional	Identificador de la provincia del cliente.
`municipalityId` body	`integer` Optional	Identificador del municipio del cliente.
`legalName` body	`string` Required	Razón social o nombre legal del cliente.
`phone` body	`string` Required	Teléfono de contacto del cliente.
`email` body	`string` Required	Correo del cliente para envío de comprobantes.
`address` body	`string` Required	Dirección física del cliente.
`defaultSecuenceTypeId` body	`integer` Optional	Tipo de NCF por defecto a usar cuando se emite un comprobante a este cliente.
`isRegisteredInDGII` body	`boolean` Optional	Marca si el cliente está formalmente inscrito en la DGII.
`withholdings` body	`string[] (uuid)` Optional	Retenciones por defecto aplicables a este cliente.

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

Modifica los datos de un cliente existente.

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

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

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

Name	Type	Description
`id` path	`string (uuid)` Required	Identificador del cliente.

Example: create a customer with 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();

Response

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

Example: duplicate tax identification

The customer slice verifies uniqueness of taxIdentification within the workspace; if another customer already has the same value it responds with 200 OK and success: false (same pattern as void). Always read success before assuming a successful create.

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

Suppliers

Suppliers are associated with purchase documents (E41). taxIdentification is optional in the DTO; what controls the flow is the isRegisteredInDGII flag: when false the supplier is considered informal and the API lets you issue an E41 on their behalf; when true the handler blocks E41 (that supplier must issue their own E31). For disbursements with no identifiable supplier, use the minor expense flow (E43).

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

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

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

Devuelve el detalle completo de un proveedor.

Name	Type	Description
`id` path	`string (uuid)` Required	Identificador del proveedor.

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

Registra un proveedor en el espacio de trabajo.

Name	Type	Description
`identificationTypeId` body	`integer` Required	Tipo de identificación tributaria del proveedor (RNC, cédula, etc.).
`taxIdentification` body	`string` Optional	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` Required	Identificador del país del proveedor.
`provinceId` body	`integer` Optional	Identificador de la provincia del proveedor.
`municipalityId` body	`integer` Optional	Identificador del municipio del proveedor.
`legalName` body	`string` Required	Razón social o nombre legal del proveedor.
`phone` body	`string` Required	Teléfono de contacto del proveedor.
`email` body	`string` Required	Correo del proveedor.
`address` body	`string` Required	Dirección física del proveedor.
`defaultSecuenceTypeId` body	`integer` Optional	Tipo de NCF por defecto a usar al registrar una compra a este proveedor.
`isRegisteredInDGII` body	`boolean` Optional	Marca si el proveedor está formalmente inscrito en la DGII.
`withholdings` body	`string[] (uuid)` Optional	Retenciones por defecto aplicables a este proveedor.

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

Modifica los datos de un proveedor existente.

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

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

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

Name	Type	Description
`id` path	`string (uuid)` Required	Identificador del proveedor.

Example: create a supplier

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

RNC validation

The contacts handler does not query the DGII registry on save; it only verifies uniqueness of taxIdentification for customers. If your integration needs to confirm that an RNC exists in the registry before registering it, use the dedicated endpoint GET /api/v1/rnc/{rnc} documented in catalog; that endpoint does hit the registry in real time.

Next steps

Next step