Notas Crédito y Débito
Corrección Fiscal Directa DIAN

Lo que NO existe en la DIAN

El proceso correcto en DIAN

91 — Nota crédito

Documento para anular o disminuir el valor de una factura previamente validada. Impacto contable: disminuye ingresos. El IVA generado se revierte proporcionalmente y las retenciones se ajustan según la base corregida.

92 — Nota débito

Documento para aumentar el valor de una factura existente, agregando cargos no incluidos originalmente. Impacto contable: incrementa ingresos. Se genera IVA adicional y se calculan retenciones sobre el nuevo cargo.

Identificador interno SIIVRO de la factura a corregir. Retornado en el response de la factura original.

Código Único de Factura Electrónica emitido por la DIAN. Debe ser exactamente el retornado, sin modificaciones.

Código de motivo DIAN. 1-5 para nota crédito, 1-4 para nota débito. Ver catálogo vigente.

{
  "document_type": "91",
  "billing_reference": {
    "invoice_id": "inv_9x2kA7p3",
    "cufe": "a8f3c2d1e9b7e8273xf4a1c9d0e2b5...64chars",
    "reason": "1"
  }
}

91Nota crédito — motivos válidos

92Nota débito — motivos válidos

En nota crédito (91)

Se revierte sobre el valor de la nota crédito. Si devolución parcial: solo sobre el subtotal de los ítems devueltos.

En nota débito (92)

Se genera sobre el valor del cargo adicional. Tasa definida en items[].tax_rate del request.

En nota crédito (91)

Se ajusta proporcionalmente al valor de la nota. SIIVRO calcula según la base corregida y el tipo de cliente.

En nota débito (92)

Se calcula sobre el nuevo cargo. Depende de actividad económica y si supera la base mínima.

En nota crédito (91)

Se revierte sobre la base de la nota crédito. Ciudad y actividad económica determinan la tarifa.

En nota débito (92)

Se aplica sobre el cargo adicional. Tarifa municipal extraída del RUT del tenant.

{
  "document_type": "91",
  "external_id": "NC-2025-00847",
  "billing_reference": {
    "invoice_id": "inv_9x2kA7p3",
    "cufe": "a8f3c2d1e9b7e8273x...64chars",
    "reason": "1"
  },
  "items": [
    {
      "description": "Devolución 2 unidades — producto devuelto",
      "quantity": 2,
      "price": 80000,
      "tax_rate": "19.00"
    }
  ]
}

{
  "id": "nt_4hK7sR2p",
  "status": "DIAN_ACCEPTED",
  "cufe": "nota_cufe_b3d1f2...64chars",
  "dian_date": "2025-04-24T16:45:22-05:00",
  "totals": {
    "subtotal": 160000,
    "iva": 30400,
    "retefuente": 4800,
    "reteica": 880,
    "total": -184720
  },
  "pdf_path": "https://storage.siivro.com/pdf/nt_4hK7sR2p.pdf",
  "xml_path": "https://storage.siivro.com/xml/nt_4hK7sR2p.xml"
}

{
  "document_type": "91",
  "external_id": "NC-ANUL-2025-00042",
  "billing_reference": {
    "invoice_id": "inv_9x2kA7p3",
    "cufe": "a8f3c2d1e9b7e8273x...64chars",
    "reason": "2"
  }
}

{
  "document_type": "92",
  "external_id": "ND-INT-2025-00012",
  "billing_reference": {
    "invoice_id": "inv_9x2kA7p3",
    "cufe": "a8f3c2d1e9b7e8273x...64chars",
    "reason": "1"
  },
  "items": [
    {
      "description": "Intereses por mora — 30 días vencidos",
      "quantity": 1,
      "price": 15000,
      "tax_rate": "0.00"
    }
  ]
}

{
  "id": "nt_7pL2mN9q",
  "status": "DIAN_ACCEPTED",
  "cufe": "nota_debito_cufe_9e2a...64chars",
  "dian_date": "2025-04-24T17:10:05-05:00",
  "totals": {
    "subtotal": 15000,
    "iva": 0,
    "retefuente": 375,
    "reteica": 82,
    "total": 14543
  },
  "pdf_path": "https://storage.siivro.com/pdf/nt_7pL2mN9q.pdf"
}

91 Nota crédito — efectos contables

92 Nota débito — efectos contables

El valor acumulado de todas las notas crédito sobre una factura no puede superar el valor original de la misma. SIIVRO valida el saldo antes de transmitir. Si la factura ya tiene notas crédito, el saldo disponible es menor.

Solo se pueden emitir notas sobre facturas en estado DIAN_ACCEPTED. Una factura rechazada no existe ante la DIAN y no puede ser corregida. Si necesitas corrección, la factura base debe estar aceptada.

Una factura que ya fue completamente anulada (nota crédito total, reason: '2') tiene saldo cero y no puede recibir más correcciones. SIIVRO detecta esto antes de enviar a la DIAN.

Si el motivo es una devolución parcial, ajuste de precio u otro que no sea anulación total, el array items[] es obligatorio. Sin ítems, no hay forma de calcular el ajuste exacto.

Los catálogos de motivos son distintos para tipo 91 y tipo 92. Un reason code válido para crédito puede ser inválido para débito y generar rechazo NC06.

Sin external_id (peligroso)

Doble clic → dos requests → dos notas crédito → doble anulación fiscal → saldo imposible → problema DIAN en declaración.

Con external_id (correcto)

Doble clic → dos requests con mismo external_id → SIIVRO retorna el primer resultado → una sola nota crédito → corrección fiscal única.

{
  "event": "invoice.updated",
  "note_id": "nt_4hK7sR2p",
  "invoice_id": "inv_9x2kA7p3",
  "document_type": "91",
  "external_id": "NC-2025-00847",
  "status": "DIAN_ACCEPTED",
  "cufe": "nota_cufe_b3d1f2...64chars",
  "pdf_path": "https://storage.siivro.com/pdf/nt_4hK7sR2p.pdf",
  "totals": {
    "subtotal": 160000,
    "iva": 30400,
    "retefuente": 4800,
    "reteica": 880,
    "total": -184720
  },
  "timestamp": "2025-04-24T16:45:22-05:00",
  "signature": "sha256=HMAC_SHA256_FIRMA"
}

Actualizar estado de la nota — ajustar contabilidad con los totals — habilitar descarga del PDF

Marcar nota como rechazada — mostrar error al usuario — permitir corrección y reenvío

// POST /api/credit-note
app.post("/api/credit-note", async (req, res) => {
  const { invoice_id, cufe, reason, items, external_id } = req.body;

  // Validaciones de negocio antes de SIIVRO
  if (!invoice_id || !cufe) {
    return res.status(400).json({ error: "billing_reference incompleto" });
  }
  if (cufe.length !== 64) {
    return res.status(400).json({ error: "CUFE debe tener 64 caracteres" });
  }

  const siivroRes = await fetch("https://api.siivro.com/v1/invoices", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.SIIVRO_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      document_type: "91",
      external_id: external_id || `NC-${Date.now()}`,
      billing_reference: { invoice_id, cufe, reason },
      items // undefined = anulación total si reason === '2'
    })
  });

  const note = await siivroRes.json();

  // Actualiza cartera si la nota fue aceptada
  if (note.status === "DIAN_ACCEPTED") {
    await db.invoices.updateBalance(invoice_id, note.totals.total);
  }

  return res.json({
    note_id: note.id,
    cufe: note.cufe,
    pdf_path: note.pdf_path,
    status: note.status,
    totals: note.totals
  });
});

// app/Http/Controllers/CreditNoteController.php
public function store(Request $request)
{
    $validated = $request->validate([
        'invoice_id' => 'required|string',
        'cufe'       => 'required|string|size:64',
        'reason'     => 'required|in:1,2,3,4,5',
        'items'      => 'array',
    ]);

    $payload = [
        'document_type'     => '91',
        'external_id'       => 'NC-' . now()->timestamp . '-' . auth()->id(),
        'billing_reference' => [
            'invoice_id' => $validated['invoice_id'],
            'cufe'       => $validated['cufe'],
            'reason'     => $validated['reason'],
        ],
    ];

    if ($validated['reason'] !== '2') {
        $payload['items'] = $validated['items'];
    }

    $response = Http::withToken(config('services.siivro.key'))
        ->post('https://api.siivro.com/v1/invoices', $payload);

    $note = $response->json();

    if ($note['status'] === 'DIAN_ACCEPTED') {
        Invoice::find($validated['invoice_id'])
            ->adjustBalance($note['totals']['total']);
    }

    return response()->json([
        'note_id'  => $note['id'],
        'status'   => $note['status'],
        'cufe'     => $note['cufe'] ?? null,
        'pdf_path' => $note['pdf_path'] ?? null,
    ]);
}

Devoluciones de compras online

Ajustes rápidos en punto de venta

Conciliación contable empresarial

Correcciones por facturación incorrecta

Ajustes en servicios de transporte

Correcciones en facturación hotelera

Aislamiento total

Para SaaS multi-empresa

Para ERP empresarial

SIIVRO los calcula automáticamente. Si envías totales precalculados o intentas pasar campos de impuestos en el request, generarás inconsistencias con el motor fiscal del tenant.

Si una nota fue rechazada (DIAN_REJECTED), genera un nuevo external_id para el reenvío corregido. Reutilizar el mismo external_id retornará la respuesta rechazada original por idempotencia.

Si el cliente devuelve 3 de 10 ítems, la nota debe ser por esas 3 unidades con reason '1'. Una nota de anulación total (reason '2') anularía la factura completa, incluyendo los 7 ítems no devueltos.

El CUFE tiene exactamente 64 caracteres hexadecimales. Cualquier modificación lo invalida para el billing_reference. Guárdalo en un campo de texto largo sin truncar, convertir ni transformar.

Solo se pueden corregir facturas aceptadas. Intentar emitir una nota sobre una factura en PROCESSING o DIAN_REJECTED genera error NC01 inmediato.

El campo total en el response de una nota crédito viene negativo (ej: -184720) para indicar la disminución de ingresos. Es correcto. Toma el valor absoluto para los ajustes contables que lo requieran.

Checklist de salida a producción — notas

{
  "invoice_id": "inv_9x2kA7p3",
  "original_total": 402150,
  "current_balance": 217430,
  "notes": [
    {
      "note_id": "nt_4hK7sR2p",
      "document_type": "91",
      "status": "DIAN_ACCEPTED",
      "reason": "1",
      "cufe": "nota_cufe_b3d1f2...64chars",
      "totals": { "total": -184720 },
      "created_at": "2025-04-24T16:45:22-05:00"
    }
  ]
}

Versión actual

El mismo endpoint sirve facturas (01), notas crédito (91), notas débito (92) y documentos soporte (95/96). El document_type determina la estructura.

SIIVRO actualiza el motor de notas cuando la DIAN cambia catálogos de motivos, formatos de CUFE o estructura del XML. Sin cambios en tu código. Notificación mínima 30 días antes.

¿Cuándo emitir nota crédito (91)?

Cuando el valor de la factura debe disminuir: devolución total o parcial, error en precio hacia arriba, descuento posterior, anulación.

¿Cuándo emitir nota débito (92)?

Cuando el valor de la factura debe aumentar: cargos adicionales no incluidos, intereses por mora, ajuste de precio hacia arriba.

¿Qué campos son siempre obligatorios?

document_type (91 o 92), billing_reference.invoice_id, billing_reference.cufe (64 chars exactos), billing_reference.reason.

¿Cuándo son obligatorios los items?

Siempre, excepto en anulación total (reason '2') donde son opcionales. Para cualquier otro motivo, items[] debe incluir los ítems a ajustar.

¿Calculo los impuestos antes de enviar?

No. SIIVRO los calcula automáticamente. Solo envías price y tax_rate por ítem.

¿Qué hago si está en PROCESSING?

Nada. Esperar el webhook invoice.updated. No reenviar.