addDraftItem()

Agrega un concepto al borrador y devuelve el documento completo con los totales actualizados.

Permiso: invoice:write

addDraftItem(
  id: string,
  input: DraftAddItemInput,
  options?: RequestOptions
): Promise<DraftRecord>

Referencia HTTP: POST /invoice-drafts/{id}/items

• No requiere dar de alta un producto previamente. unitPrice es el precio unitario antes de impuestos.
• El tipo TypeScript requiere quantity, aunque el validador HTTP pueda completarla con 1. Guarda el ID del concepto desde items; la respuesta no es solo el concepto agregado.

Parámetros

Argumento	Tipo	Obligatorio	Uso
id	string	Sí	ID de FactuCat del borrador, en formato UUID. No es el UUID fiscal.
input	DraftAddItemInput	Sí	Objeto con los campos indicados abajo.
options	RequestOptions	No	signal e idempotencyKey; consulta las opciones por solicitud.

Opciones por solicitud: signal e idempotencyKey.

Los campos siguientes corresponden a input en TypeScript. Un campo opcional se puede omitir; null solo se admite cuando aparece en su tipo. Las validaciones de negocio se ejecutan en el servidor.

Campo	Tipo	Obligatorio	Descripción
position	number (entero)	No	Posición del concepto; comienza en 0.Mínimo: 0. Máximo: 9007199254740991
productCode	string	No	Clave del producto o servicio del catálogo SAT.
unitCode	string	No	Clave de unidad del catálogo SAT.
description	string	Sí	Descripción del bien o servicio.Mínimo 1 carácter
quantity	number	Sí	Cantidad del concepto.Mayor que 0. Valor del validador: 1
unitPrice	number	Sí	Precio unitario antes de impuestos.Mínimo: 0
vatTreatment	"iva_16" | "iva_8" | "tasa_0" | "exento" | "no_objeto"	No	Tratamiento de IVA opcional: iva_16, iva_8, tasa_0, exento o no_objeto. Omitirlo conserva la inferencia fiscal; un tratamiento explícito se guarda como manual. Si también envías vatRate, deben coincidir; de lo contrario, la API responde HTTP 400 con invalid_input. Se devuelve en los conceptos de borradores y facturas; no representa la tasa histórica de 10%.
vatRate	0 | 0.08 | 0.1 | 0.16	No	Tasa de IVA como fracción decimal, por ejemplo 0.16; no envíes 16. vatRate: 0 por sí solo significa Tasa 0%.
vatSource	"manual" | "inferred" | "default"	No	Origen de la tasa de IVA seleccionada.
isrWithholdingRate	0 | 0.0125 | 0.1	No	Tasa de retención de ISR como fracción decimal.
isrWithholdingSource	"manual" | "inferred" | "default"	No	Origen de la retención de ISR seleccionada.
suggestedProductCode	string	No	Clave de producto o servicio sugerida.
suggestionConfidence	number	No	Confianza de la sugerencia.Mínimo: 0. Máximo: 1
suggestionSource	"ai" | "memory" | "manual" | "review"	No	Origen de la sugerencia.

Ejemplo

Usa el cliente factucat de Instala y conecta. Los IDs y datos fiscales de este ejemplo son ilustrativos: reemplázalos por los registros de tu cuenta y ambiente.

const resultado = await factucat.addDraftItem(
  "00112233-4455-4677-8899-aabbccddeeff",
  {
    "productCode": "81111500",
    "unitCode": "E48",
    "description": "Desarrollo de aplicaciones",
    "quantity": 1,
    "unitPrice": 1000,
    "vatRate": 0.16,
    "isrWithholdingRate": 0
  },
  {
    "idempotencyKey": "pedido-1001-concepto-1"
  },
)
console.log(resultado)

Respuesta

Resuelve una Promise<DraftRecord>. El valor recibido es directamente data, sin el envoltorio HTTP ni sus metadatos.

Campo	Tipo	Obligatorio	Descripción
id	string	Sí	ID de FactuCat del recurso. No es el UUID fiscal.Formato: uuid
userId	string	Sí	ID de la cuenta propietaria del recurso.Mínimo 1 carácter
customerId	string	No	ID de FactuCat del cliente vinculado. Consulta las notas del método sobre la copia de datos fiscales.Formato: uuid
receiverRfc	string	Sí	RFC del receptor guardado en el documento.
receiverLegalName	string	Sí	Nombre fiscal del receptor guardado en el documento.
receiverPostalCode	string	Sí	Código postal fiscal del receptor, como cadena de cinco dígitos.
receiverTaxRegime	string	Sí	Clave del régimen fiscal del receptor.
receiverFiscalResidence	string	No	Clave del país de residencia fiscal del receptor, cuando aplica.
receiverTaxId	string	No	Identificación tributaria extranjera del receptor, cuando aplica.
receiverEmail	string	No	Correo del receptor guardado en el documento.Formato: email
receiverInvoiceLanguage	"es" | "en"	Sí	Idioma del receptor para este documento.
serie	string	No	Serie asignada por la cuenta emisora.
folio	string	No	Folio del documento.
satUuid	string	No	UUID fiscal del CFDI timbrado. Es distinto del ID de FactuCat.
status	"draft" | "issued" | "error" | "cancelled"	Sí	Estado del recurso o resultado de la cancelación; consulta las notas del método.
cfdiType	string	Sí	Tipo de comprobante.
cfdiUse	string	Sí	Clave del uso de CFDI solicitado por el receptor.
exportacion	"01" | "02" | "03" | "04"	Sí	Clave del catálogo SAT c_Exportacion.
paymentMethod	string	No	Clave del método de pago del comprobante.
paymentForm	string	No	Clave de la forma de pago; conserva los ceros iniciales.
currency	"MXN" | "USD" | "EUR"	Sí	Moneda del cliente o del comprobante.
exchangeRate	number	Sí	Tipo de cambio aplicado a la moneda del comprobante.
exchangeRateDate	string	No	Fecha de referencia del tipo de cambio en formato ISO 8601.Formato: date-time
subtotal	number	Sí	Subtotal del documento antes de impuestos.
vatRate	0 | 0.08 | 0.1 | 0.16	Sí	Tasa de IVA como fracción decimal, por ejemplo 0.16; no envíes 16. vatRate: 0 por sí solo significa Tasa 0%.
taxTotal	number	Sí	Total de impuestos del documento.
total	number	Sí	Importe total del documento. En cancelaciones externas se envía como string.
customerNotes	string	No	Notas visibles en el documento.
pdfLanguage	"es" | "en"	Sí	Idioma de la representación PDF.
errorMessage	string	No	Mensaje asociado a un error del documento, cuando está disponible.
issueDate	string	No	Fecha de emisión seleccionada, en formato ISO 8601.Formato: date-time
issuedAt	string	No	Fecha y hora de emisión, cuando está disponible.Formato: date-time
cancelledAt	string	No	Fecha y hora de cancelación, cuando está disponible.Formato: date-time
createdAt	string	Sí	Fecha y hora de creación en formato ISO 8601; se devuelve como string.Formato: date-time
updatedAt	string	Sí	Fecha y hora de última actualización en formato ISO 8601.Formato: date-time
items	Array<object>	Sí	Conceptos del documento; cada concepto tiene su propio ID.

Campos de items[]

Campo	Tipo	Obligatorio	Descripción
id	string	Sí	ID de FactuCat del recurso. No es el UUID fiscal.Formato: uuid
invoiceId	string	Sí	ID de FactuCat del documento al que pertenece el concepto.Formato: uuid
position	number (entero)	Sí	Posición del concepto; comienza en 0.Mínimo: 0. Máximo: 9007199254740991
productCode	string	No	Clave del producto o servicio del catálogo SAT.
unitCode	string	Sí	Clave de unidad del catálogo SAT.
description	string	Sí	Descripción del bien o servicio.
quantity	number	Sí	Cantidad del concepto.
unitPrice	number	Sí	Precio unitario antes de impuestos.
amount	number	Sí	Importe del concepto antes de impuestos.
objetoImp	"01" | "02" | "03" | "04" | "05" | "06" | "07" | "08"	No	Objeto de impuesto del concepto, devuelto en borradores y facturas; 01 indica No objeto de impuesto.
vatKind	"none" | "tasa" | "exento"	No	Tipo de IVA del concepto, devuelto en borradores y facturas: tasa, exento o none (No objeto de impuesto).
vatTreatment	"iva_16" | "iva_8" | "tasa_0" | "exento" | "no_objeto"	No	Tratamiento de IVA opcional: iva_16, iva_8, tasa_0, exento o no_objeto. Omitirlo conserva la inferencia fiscal; un tratamiento explícito se guarda como manual. Si también envías vatRate, deben coincidir; de lo contrario, la API responde HTTP 400 con invalid_input. Se devuelve en los conceptos de borradores y facturas; no representa la tasa histórica de 10%.
vatRate	0 | 0.08 | 0.1 | 0.16	Sí	Tasa de IVA como fracción decimal, por ejemplo 0.16; no envíes 16. vatRate: 0 por sí solo significa Tasa 0%.
vatSource	"manual" | "inferred" | "default"	No	Origen de la tasa de IVA seleccionada.
vatReason	string	No	Explicación de la tasa de IVA, cuando está disponible.
isrWithholdingRate	0 | 0.0125 | 0.1	Sí	Tasa de retención de ISR como fracción decimal.
isrWithholdingSource	"manual" | "inferred" | "default"	No	Origen de la retención de ISR seleccionada.
isrWithholdingReason	string	No	Explicación de la retención de ISR, cuando está disponible.
suggestedProductCode	string	No	Clave de producto o servicio sugerida.
suggestionConfidence	number	No	Confianza de la sugerencia.
suggestionSource	"ai" | "memory" | "manual" | "review"	No	Origen de la sugerencia.

Ejemplo de respuesta

{
  "id": "00112233-4455-4677-8899-aabbccddeeff",
  "userId": "usuario_ejemplo",
  "customerId": "10112233-4455-4677-8899-aabbccddeeff",
  "receiverRfc": "AAA010101AAA",
  "receiverLegalName": "EMPRESA DE EJEMPLO",
  "receiverPostalCode": "06000",
  "receiverTaxRegime": "601",
  "receiverInvoiceLanguage": "es",
  "status": "draft",
  "cfdiType": "I",
  "cfdiUse": "G03",
  "exportacion": "01",
  "paymentMethod": "PUE",
  "paymentForm": "03",
  "currency": "MXN",
  "exchangeRate": 1,
  "subtotal": 1000,
  "vatRate": 0.16,
  "taxTotal": 160,
  "total": 1160,
  "pdfLanguage": "es",
  "createdAt": "2026-09-08T12:00:00Z",
  "updatedAt": "2026-09-08T12:00:00Z",
  "items": [
    {
      "id": "20112233-4455-4677-8899-aabbccddeeff",
      "invoiceId": "00112233-4455-4677-8899-aabbccddeeff",
      "position": 0,
      "productCode": "81111500",
      "unitCode": "E48",
      "description": "Desarrollo de aplicaciones",
      "quantity": 1,
      "unitPrice": 1000,
      "amount": 1000,
      "vatRate": 0.16,
      "isrWithholdingRate": 0
    }
  ]
}

Las fechas se entregan como cadenas ISO 8601. Un campo opcional puede estar ausente. Tipos, paginación y archivos.

La promesa se rechaza si la API devuelve un error, falla la conexión o los datos no cumplen el contrato. Cómo manejar los errores.