cancelExternalInvoice()

Solicita la cancelación de un CFDI emitido fuera de FactuCat usando su UUID fiscal y el emisor de la cuenta.

Permiso: invoice:cancel

cancelExternalInvoice(
  input: ExternalInvoiceCancelInput,
  options?: RequestOptions
): Promise<ExternalInvoiceCancelOutput>

Referencia HTTP: POST /external-invoice-cancellations

• total se envía como string con el importe del CFDI, no como número. El emisor y su CSD deben estar configurados en la cuenta.
• Para el motivo 01, proporciona la sustitución que corresponda. replacementInvoiceId identifica una factura de FactuCat; replacementSatUuid identifica su UUID fiscal. Si envías ambos deben coincidir.
• No trates not_confirmed como una cancelación completada. evidence es unknown; inspecciónala solo después de validar su estructura.

Parámetros

Argumento	Tipo	Obligatorio	Uso
input	ExternalInvoiceCancelInput	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
satUuid	string	Sí	UUID fiscal del CFDI timbrado. Es distinto del ID de FactuCat.Formato: uuid
reason	"01" | "02" | "03" | "04"	Sí	Clave del motivo de cancelación que corresponde a la operación.
receiverRfc	string	Sí	RFC del receptor guardado en el documento.Mínimo 1 carácter
total	string	Sí	Importe total del documento. En cancelaciones externas se envía como string.Mínimo 1 carácter
replacementInvoiceId	string	No	ID de FactuCat de la factura sustituta emitida.Formato: uuid
replacementSatUuid	string	No	UUID fiscal del CFDI sustituto.Formato: uuid

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.cancelExternalInvoice(
  {
    "satUuid": "30112233-4455-4677-8899-aabbccddeeff",
    "reason": "02",
    "receiverRfc": "AAA010101AAA",
    "total": "1160.00"
  },
  {
    "idempotencyKey": "cfdi-externo-1001-cancelar"
  },
)
console.log(resultado)

Respuesta

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

Campo	Tipo	Obligatorio	Descripción
status	"cancelled" | "not_confirmed"	Sí	Estado del recurso o resultado de la cancelación; consulta las notas del método.
satUuid	string	Sí	UUID fiscal del CFDI timbrado. Es distinto del ID de FactuCat.
replacementSatUuid	string	No	UUID fiscal del CFDI sustituto.
evidence	unknown	Sí	Evidencia de la cancelación sin estructura tipada. Valídala antes de acceder a sus propiedades.

Ejemplo de respuesta

{
  "status": "not_confirmed",
  "satUuid": "30112233-4455-4677-8899-aabbccddeeff",
  "evidence": null
}

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.