--- title: "API de contactos" description: "Endpoints v1 para clientes y proveedores: identificación tributaria, ubicación y banderas de retención por defecto." canonical: https://factura.com.do/desarrolladores/contactos lang: es generator: factura.com.do docs-index --- 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 create-customer.sh ``` 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" }' ``` create-customer.ts ``` 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 response.json ``` { "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. 200-tax-identification-duplicate.json ``` { "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 create-supplier.sh ``` 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](/desarrolladores/catalogo); ese endpoint sí golpea el padrón en tiempo real. Valida primero, registra después Si tu integración carga contactos en lote, llama primero a [la validación de RNC contra el padrón](/desarrolladores/catalogo) y descarta los suspendidos antes de registrarlos. La validación al guardar no lo hará por ti. ## Siguientes pasos Siguiente paso ## Continúa por aquí - [ Catálogo Validación de RNC, productos, impuestos y unidades disponibles. ](/desarrolladores/catalogo) - [ Facturas Emite el comprobante E31 al cliente recién creado. ](/desarrolladores/facturas) - [ Compras Registra comprobantes E41 al proveedor recién creado. ](/desarrolladores/compras)