FacturaApiReferenciaDto

Reference to a prior document. It is required when issuing a credit note (NC) or a debit note (ND).

Fields

interface FacturaApiReferenciaDto {
  /** REQUIRED. Type of the referenced document. See Hacienda catalog. */
  tipoDocumento: string;
 
  /** REQUIRED. 50-digit key or 20-digit consecutive number of the original document. */
  numero: string;
 
  /** Issue date of the original document. ISO 8601 UTC. */
  fechaEmision?: string | null;
 
  /** 2-digit reason code. See Hacienda catalog. */
  codigo?: string | null;
 
  /** Description of the reason, or the code if it wasn't sent in `codigo`. */
  razon?: string | null;
}

The reason code: codigo or razon

The system needs a 2-digit code from the catalog, and looks for it first in codigo and then in razon. It’s enough for one of the two to carry it:

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

{ "razon": "01" }

If neither of the two is a valid code, the issuance is rejected with 400 and the message lists the codes the tenant accepts. A reference with only free text — { "razon": "Anulación total por error en el monto" } — does not get issued.

numero: key or consecutive number

numero carries the reference to the original document and accepts the two forms Hacienda recognizes:

• Key of 50 digits: 50615012600310112345600100001010000000123456789012
• Consecutive number of 20 digits: 00100001010000000123

The system detects which one it is by its length. Don’t confuse numero with codigo: one identifies the document, the other says why it’s being referenced.

Example

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