Cómo emitir una nota de crédito por API: anulación y devolución parcial

Respuesta corta: una nota de crédito (tipo 03) se emite con POST /documents/nota-credito. Lleva las líneas que se acreditan y un bloque referencia obligatorio con la clave de 50 dígitos de la factura, su fecha y el código del motivo: 01 para anularla entera, 02 para corregir el monto (por ejemplo, una devolución parcial). Los CABYS de la nota tienen que existir en la factura original, o Hacienda rechaza con -509.

La nota de crédito es el único camino para bajar o anular una factura ya aceptada: el Reglamento de Comprobantes Electrónicos (Decreto 44739-H, art. 10) dice que un comprobante válido no se anula directamente, sino con notas de crédito o débito, y el original queda inalterable. Esta guía cubre cómo armarla por API sin rechazos.

La estructura de una nota de crédito

Es un comprobante completo, con su propio detalle, más la referencia al documento que corrige:

POST /documents/nota-credito
Idempotency-Key: nc-pedido-4471

{
  "emisorLegalId": "3101000000",
  "condicionVenta": "01",
  "medioPago": ["01"],
  "receptor": {
    "tipoIdentificacion": "01",
    "numeroIdentificacion": "100000002",
    "nombre": "Juan Ejemplo"
  },
  "detalle": [{
    "cantidad": 1,
    "unidadMedida": "Unid",
    "codigoCabys": "2999999999007",
    "detalle": "Pan pita 400g",
    "precioUnitario": 1000,
    "impuesto": [{ "codigo": "01", "codigoTarifa": "08", "tarifa": 13 }]
  }],
  "referencia": [{
    "tipoDocumento": "01",
    "numero": "50624072600310100000000100001010000000866142351111",
    "fechaEmision": "2026-07-25T01:07:52-06:00",
    "codigo": "01",
    "razon": "Anulación por devolución total"
  }]
}

En la referencia:

Campo	Qué va
tipoDocumento	Qué estás referenciando: 01 factura, 04 tiquete, 19 factura de exportación, 20 recibo de pago…
numero	La clave de 50 dígitos del original (se valida el largo)
fechaEmision	La fecha de emisión del original
codigo	El motivo. Obligatorio en notas: de él depende el saldo del original
razon	Texto libre. Opcional; si no va, se escribe «Referencia a otro documento»

Qué código de referencia usar

Situación	Código	En qué período pesa
Anular la factura completa (venta cancelada, cliente equivocado)	01	El de la nota
Corregir el monto: devolución parcial, descuento posterior	02	El de la nota
Anular una factura emitida con un error de digitación	13	El de la factura original
Corregir un monto mal digitado o mal calculado	14	El de la factura original
El cliente obtuvo una exoneración después de facturarle	12	El de la nota

El 13 y el 14 son los códigos de error material que publicó Hacienda en la actualización del Anexo v4.4 (bitácora al 22/04/2026), obligatorios para los sistemas desde el 1 de noviembre de 2026. Su efecto se declara en el mes del comprobante que corrigen, no en el de la nota. Cuándo usar cada uno: nota de crédito por error material.

Dos códigos que no sirven en notas: el 03 no existe en la v4.4 (era «corrige monto» en la v4.3) y el 17 es exclusivo del Recibo Electrónico de Pago; Hacienda lo rechaza en una NC.

Devolución parcial: solo las líneas devueltas

Para devolver parte de una venta, la nota lleva solo las líneas devueltas, con sus cantidades, y codigo: "02":

"detalle": [
  { "codigoCabys": "2999999999005", "cantidad": 1, "unidadMedida": "Unid",
    "detalle": "Pan tostado 200g (devuelto)", "precioUnitario": 1200,
    "impuesto": [{ "codigo": "01", "codigoTarifa": "08", "tarifa": 13 }] },
  { "codigoCabys": "2999999999007", "cantidad": 1, "unidadMedida": "Unid",
    "detalle": "Pan pita 400g (devuelto)", "precioUnitario": 1000,
    "impuesto": [{ "codigo": "01", "codigoTarifa": "02", "tarifa": 1 }] }
],
"referencia": [{ "tipoDocumento": "01", "numero": "506…", "fechaEmision": "…",
                 "codigo": "02", "razon": "Devolución parcial de dos líneas" }]

Cada línea lleva la misma tarifa de IVA que tenía en la factura. Si la factura era al 1 % y acreditás al 13 %, tu declaración no va a cuadrar aunque Hacienda acepte la nota.

Precargar la nota desde la factura

No tenés que reconstruir la factura desde tu base. GET /documents/{id}?include=prefill devuelve un objeto prefill con lo necesario para la nota: líneas, receptor, medioPago y plazoCredito del original.

Los rechazos típicos y cómo evitarlos

• -509: CABYS que no está en el original. Hacienda cruza los códigos de la nota contra los de la factura. Usá exactamente los mismos. Si necesitás cobrar o acreditar algo que no estaba, va en otro comprobante.
• Medio de pago ausente. El XSD lo marca opcional, pero Hacienda rechaza la nota sin él (-496 en NC). Por eso la API lo exige con un 400, salvo con condicionVenta 02, 08 o 10 (créditos). Usá el mismo medio de la factura.
• -58: plazo de crédito. Con condicionVenta: "02", plazoCredito es obligatorio y es un string con los días.
• Tarifas transitorias. Las notas son los únicos comprobantes que las admiten (en factura o tiquete son -505).
• Factura de exportación. La nota tiene que repetir la línea tal cual, con el mismo codigoCabys y la misma partidaArancelaria (si no, -503 o -509).

Hacienda no valida la referencia (y por qué importa)

Hacienda no comprueba el contenido de InformacionReferencia: acepta una nota que apunte a una clave inexistente. Un «aceptado» significa que el XML de la nota está bien, no que la factura quedó anulada.

Por eso la plataforma reconcilia sola: cuando la nota es aceptada, el documento original se actualiza con un bloque credito que trae lo acreditado, el saldo, si quedó anulado y la lista de notas que lo afectaron. Y al emitir te devuelve avisos —nunca bloqueos— si la clave no aparece, si el emisor es otro o si estás acreditando más que el total.

Lo que no se hace con una nota de crédito

No se emite una nota sobre un comprobante rechazado. El mismo artículo 10 del Reglamento lo dice: el rechazado carece de validez y no lleva nota de crédito ni débito. La API lo corta con 422 reference_rejected. Lo que corresponde es un comprobante nuevo que lo sustituya: qué hacer si Hacienda rechaza una factura.

Tampoco hay que confundirla con la nota de débito (POST /documents/nota-debito), que tiene la misma forma pero suma al original: intereses, cargos omitidos, correcciones al alza. La diferencia completa está en nota de crédito vs nota de débito.

Preguntas frecuentes

¿La nota de crédito lleva receptor?

Es opcional: una nota sobre un tiquete no lo lleva. Si la factura tenía receptor, conviene repetirlo.

¿Puedo referenciar varias facturas en una nota?

referencia es una lista y admite hasta 10 elementos. Lo habitual es una nota por factura, para que la reconciliación sea clara.

¿Cómo sé si la factura quedó anulada?

Consultá la factura con GET /documents/{id} después de que la nota sea aceptada: credito.anulado y credito.saldo ya vienen calculados.

¿El cliente tiene que hacer algo?

Su crédito de IVA se ajusta con la nota. Si le enviás los comprobantes por correo, la nota sale igual que una factura cuando Hacienda la acepta.

Con la API de Facturaencr las notas de crédito usan el mismo flujo que la factura, con precarga desde el original y la reconciliación del saldo hecha. Si emitís desde el navegador, el portal de facturación precarga la nota desde la factura con un clic. Todos los catálogos están en la documentación.