FacturaApiReferenciaDto

Referencia a un comprobante previo. Es obligatoria cuando se emite una nota de crédito (NC) o una nota de débito (ND).

Campos

interface FacturaApiReferenciaDto {
  /** OBLIGATORIO. Tipo de documento referenciado. Ver catálogo Hacienda. */
  tipoDocumento: string;
 
  /** OBLIGATORIO. Clave de 50 dígitos o consecutivo de 20 del documento original. */
  numero: string;
 
  /** Fecha de emisión del documento original. ISO 8601 UTC. */
  fechaEmision?: string | null;
 
  /** Código de motivo de 2 dígitos. Ver catálogo Hacienda. */
  codigo?: string | null;
 
  /** Descripción del motivo, o el código si no se envió en `codigo`. */
  razon?: string | null;
}

El código de motivo: codigo o razon

El sistema necesita un código de 2 dígitos del catálogo, y lo busca primero en codigo y luego en razon. Basta con que uno de los dos lo traiga:

{ "codigo": "01", "razon": "Anulación total por error en el monto" }

{ "razon": "01" }

Si ninguno de los dos es un código válido, la emisión se rechaza con 400 y el mensaje lista los códigos que acepta el tenant. Una referencia con solo texto libre —{ "razon": "Anulación total por error en el monto" }— no emite.

numero: clave o consecutivo

numero lleva la referencia al documento original y acepta las dos formas que reconoce Hacienda:

• Clave de 50 dígitos: 50615012600310112345600100001010000000123456789012
• Consecutivo de 20 dígitos: 00100001010000000123

El sistema detecta cuál es por la longitud. No confundir numero con codigo: uno identifica el documento, el otro dice por qué se lo referencia.

Ejemplo

{
  "tipoDocumento": "01",
  "numero": "50615012600310112345600100001010000000123456789012",
  "fechaEmision": "2026-05-10T10:00:00Z",
  "codigo": "01",
  "razon": "Anulación total por error en el monto"
}