stampDraft()

Valida y timbra un borrador con el CSD de la cuenta. En producción emite un CFDI y registra consumo.

Permiso: invoice:stamp

stampDraft(
  id: string,
  input?: DraftStampInput,
  options?: RequestOptions
): Promise<InvoiceRecord>

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

• Antes de llamar: datos fiscales y CSD configurados, acceso al plan, receptor, pago y conceptos completos. Sigue la guía de emisión para preparar esos datos.
• La respuesta conserva el ID de FactuCat y agrega satUuid. Después, usa getInvoice() para consultar el documento.
• Ante un timeout no crees otro borrador: consulta el documento original y conserva la clave de la operación. Una respuesta ambigua requiere reconciliar el timbrado.
• allowPaidStampOverdraft se interpreta como true por defecto en la API pública. Los planes y reglas de consumo siguen aplicando; false no convierte el timbrado en gratuito.

Parámetros

Argumento	Tipo	Obligatorio	Uso
id	string	Sí	ID de FactuCat del borrador, en formato UUID. No es el UUID fiscal.
input	DraftStampInput	No	Se puede omitir; el valor predeterminado es {}.
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
issueDate	string	No	Fecha de emisión: YYYY-MM-DD o datetime ISO (día en la zona horaria del código postal de expedición). La fecha de emisión puede ser hoy o hasta 72 horas antes del timbrado (máximo 3 días de calendario atrás), nunca futura, en la zona horaria del código postal de expedición (regla 2.7.2.9 RMF). INVALID_ISSUE_DATE si no es válida.
skipIssuedEmailSend	boolean	No	Suprime el envío de correo de emisión. No desactiva por sí solo WhatsApp.
sendToCustomerContacts	boolean	No	Al activarlo, usa los contactos del cliente. Las opciones de cada canal tienen prioridad; false por sí solo no garantiza que se suprima la entrega al receptor.
sendCustomerEmail	boolean	No	Controla explícitamente el envío de correo al cliente.
sendCustomerWhatsApp	boolean	No	Controla explícitamente el envío de WhatsApp al cliente.
allowPaidStampOverdraft	boolean	No	Controla el uso de excedentes donde el plan lo admite; la API pública usa true al omitirlo.
cfdi_relacionados	object	No	Relación con uno o más CFDI, cuando aplica a la operación.
substitution	object	No	Solicita la sustitución de un CFDI y la cancelación automática del comprobante original.

Campos de cfdi_relacionados

Campo	Tipo	Obligatorio	Descripción
tipo_relacion	string	Sí	Clave de dos dígitos del tipo de relación.Patrón: ^\d{2}$
cfdi_relacionado	Array<string>	Sí	Lista de UUID fiscales de los CFDI relacionados.Mínimo 1 elementos

Campos de substitution

Campo	Tipo	Obligatorio	Descripción
cancel_original	true	Sí	Debe ser true para cancelar automáticamente el CFDI original después del timbrado sustituto.
original_invoice_id	string	No	ID de FactuCat del CFDI original interno que será sustituido y cancelado.Formato: uuid
external_original_sat_uuid	string	No	UUID fiscal del CFDI original externo que será sustituido y cancelado.Formato: uuid
external_original_receiver_rfc	string	No	RFC del receptor del CFDI original externo; requerido para solicitar su cancelación.Mínimo 1 carácter
external_original_total	string	No	Total del CFDI original externo como string; requerido para solicitar su cancelación.Mínimo 1 carácter

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.stampDraft(
  "00112233-4455-4677-8899-aabbccddeeff",
  {
    "sendToCustomerContacts": false,
    "sendCustomerEmail": false,
    "sendCustomerWhatsApp": false,
    "skipIssuedEmailSend": true
  },
  {
    "idempotencyKey": "pedido-1001-timbrar"
  },
)
console.log(resultado)

Respuesta

Resuelve una Promise<InvoiceRecord>. 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": "issued",
  "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
    }
  ],
  "satUuid": "30112233-4455-4677-8899-aabbccddeeff",
  "issuedAt": "2026-09-08T12:00:00Z"
}

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.