Skip to content

Nota de débito ​

POST /api/Invoice/add_debit_note

Emite una nota de débito sobre una factura ya emitida, con productos o conceptos nuevos que aumentan el monto adeudado (cargos adicionales, intereses, diferencias de precio, etc.). La nota recibe un número de control, se firma electrónicamente y puede registrar sus métodos de pago. Devuelve el número de control y el enlace al PDF.

Autenticación: Authorization: Bearer <token> (cómo obtenerlo) · Content-Type: application/json

Cuerpo de la solicitud ​

CampoTipoObligatorioDescripción y reglas
numeroFacturastringSíNúmero de la factura a afectar, exactamente como se registró (se respetan los ceros a la izquierda). Solo dígitos, máximo 19 caracteres.
numeroNotaDebitostringSíNúmero que tendrá la nota de débito. Solo dígitos, máximo 19 caracteres. No puede estar ya usado por otra nota de débito del negocio.
descripcionstringSíMotivo u observación de la nota, máximo 50 caracteres.
tasa_del_diastringSíTasa de cambio del día con hasta 6 enteros y hasta 8 decimales, separador . o , (por ejemplo "342.8633"). Mayor que cero. También se acepta con los nombres exchange_rate, current_exchange_rate o tasa_de_cambio.
fecha_tasastringSíFecha de la tasa de cambio, en formato DD-MM-YYYY o YYYY-MM-DD. También se acepta como current_exchange, fecha_tasa_de_cambio o fecha_tasa_del_dia.
productos_nuevosarraySíProductos o conceptos que se cargan en la nota. Al menos uno. Ver productos_nuevos[].
order_payment_methodsarrayNoMétodos de pago de la nota, máximo 5. Si se omite, la nota se registra como pago a crédito. También se acepta como metodos_pago. Ver order_payment_methods[].

productos_nuevos[] ​

CampoTipoObligatorioDescripción y reglas
codigoProductostringSíCódigo del producto, máximo 13 caracteres, sin espacios. Si el código no existe en el negocio, el producto se crea automáticamente.
nombreProductostringSíNombre del producto, máximo 400 caracteres. Se usa al crear el producto.
descripcionProductostringSíDescripción que se imprime en la línea de la nota, máximo 400 caracteres.
tipoImpuestostringSíAlícuota de IVA: E (exento, 0 %), R (reducida, 8 %), G (general, 16 %), A (adicional, 31 %), P (percibido, 0 %).
cantidadAdquiridanumber o stringSíCantidad, mayor que 0, con punto decimal (por ejemplo 15.63 o "2"). Sin signo ni separadores de miles.
precioProductostring o numberSíPrecio unitario sin IVA, mayor que 0, con hasta 2 decimales y separador . o , (por ejemplo "1,55" o "120.50"). Sin separadores de miles.

No se permiten dos líneas con el mismo codigoProducto y descripcionProducto.

order_payment_methods[] ​

CampoTipoObligatorioDescripción y reglas
order_payment_methodstringSíNombre del método de pago, máximo 20 caracteres (si se excede, el documento se rechaza): transferencia, efectivo, pago movil o divisa (ver Métodos de pago). divisa solo puede aparecer una vez y debe ser el primer elemento del arreglo. Cualquier otro nombre (por ejemplo Zelle o Tarjeta débito) se registra como Otro y se muestra con ese nombre en el panel y en el PDF; se trata como pago en Bs (sin IGTF). Ver Otros métodos de pago.
montostringSíMonto pagado con ese método: hasta 9 enteros y exactamente 2 decimales, separador . o , (por ejemplo "120.50"). Sin separadores de miles. Mayor que cero.
bancostringPara transferencia y pago movilNombre del banco, tal como aparece en Bancos.
numero_de_referencia_de_operacionstringPara transferencia y pago movilExactamente 4 dígitos (los últimos de la referencia).
telefono_pago_movilstringPara pago movilTeléfono con exactamente 11 dígitos, por ejemplo "04141234567".
notestringNoNota libre que se guarda con el pago.

Suma de los pagos. Si envías métodos de pago, la suma de los monto debe ser igual al total calculado de la nota (bases + IVA). Si hay un pago en divisa y el negocio está sujeto a IGTF, se acepta tanto el total de la nota (el IGTF del 3 % se suma automáticamente al pago en divisa) como el total más el IGTF. Si la nota es a crédito o aún no se ha pagado, omite order_payment_methods.

Ejemplo de solicitud ​

json
{
  "numeroFactura": "000313",
  "numeroNotaDebito": "000021",
  "descripcion": "Cargo por flete adicional",
  "tasa_del_dia": "342.8633",
  "fecha_tasa": "21-10-2026",
  "productos_nuevos": [
    {
      "codigoProducto": "FLETE-01",
      "nombreProducto": "FLETE",
      "descripcionProducto": "FLETE ADICIONAL CARACAS - VALENCIA",
      "tipoImpuesto": "G",
      "cantidadAdquirida": 1,
      "precioProducto": "100,00"
    }
  ],
  "order_payment_methods": [
    {
      "order_payment_method": "transferencia",
      "monto": "116.00",
      "banco": "Banco de Venezuela",
      "numero_de_referencia_de_operacion": "4821"
    }
  ]
}

Respuesta exitosa ​

HTTP 200

json
{
  "success": true,
  "message": "Nota de débito guardada satisfactoriamente.",
  "debit_note_number": "000021",
  "invoice_number_affected": "000313",
  "control_number": "00-00000127",
  "debit_note_pdf": "https://api.example.com/readonly/export_pdf/c41e7a2d-9f0b-4b5e-aa63-d1f0e2b7c9a4"
}
ClaveDescripción
successtrue si la nota se guardó.
messageMensaje de confirmación.
debit_note_numberNúmero de la nota de débito emitida.
invoice_number_affectedNúmero de la factura afectada.
control_numberNúmero de control asignado, con formato serie-########.
debit_note_pdfEnlace al PDF de la nota.
warning_control_numbersSolo aparece cuando al negocio le quedan pocos números de control.

Errores ​

Los errores devuelven "success": false con el código HTTP correspondiente (400 datos inválidos, 404 no encontrado, 409 conflicto, 500 error al guardar; ver Errores). Los errores de validación de productos, pagos, tasa y fecha se acumulan y se devuelven juntos en un solo message, separados por espacios.

HTTPMensaje (ejemplo)Causa
400El campo Número de Factura es obligatorio.Falta numeroFactura. Igual para El campo Número de Nota de Débito es obligatorio.
400El campo Número de Factura debe contener solo números enteros (sin decimales, espacios ni caracteres especiales). Valor recibido: F-313.Formato inválido. Hay mensaje equivalente para numeroNotaDebito.
400El campo Número de Nota de Débito no puede exceder los 19 caracteres. Longitud actual: 20.Número demasiado largo (equivalente para numeroFactura).
400El campo Descripción es obligatorio.Falta descripcion.
400El campo Descripción no puede exceder los 50 caracteres. Longitud actual: 58.descripcion demasiado larga.
400El campo productos_nuevos es obligatorio y no debe estar vacío.Falta productos_nuevos o está vacío.
400La cantidad de productos por nota de débito no puede ser mayor a 50Se superó el límite de productos por documento configurado en la plataforma (el número varía).
400Error: Productos duplicados en la nota de débito.Dos líneas con el mismo código y descripción.
400El campo Código del Producto en el producto 1 es obligatorio.Falta un campo del producto (mensajes análogos para Nombre, Descripción, Tipo de Impuesto, Cantidad Adquirida y Precio). El número de producto empieza en 1.
400El campo Código del Producto en el producto 1 no puede exceder los 13 caracteres.Código demasiado largo (también no puede contener espacios.).
400El campo Cantidad Adquirida en el producto 1 debe ser un número válido.Cantidad no numérica (por ejemplo, con coma decimal).
400El campo Precio del Producto en el producto 1 debe ser un número decimal válido con punto o coma (sin caracteres especiales ni negativos).Precio con más de 2 decimales, separador de miles o caracteres no válidos.
400La nota de débito N° 000021 no puede contener más de 5 métodos de pago.Más de 5 métodos de pago.
400El método de pago 'divisa' debe registrarse como el primer método de pago en la nota de débito N° 000021.divisa no es el primer método.
400El campo 'monto' debe tener hasta 9 dígitos enteros y exactamente 2 decimales (ejemplo: 120.343.231,99) en la nota de débito N° 000021.monto mal formado (ver Notas).
400El campo 'numero_de_referencia_de_operacion' debe contener exactamente 4 dígitos numéricos en la nota de débito N° 000021.Referencia inválida en transferencia o pago móvil.
400El banco 'Banco Inventado' no es válido. Bancos disponibles: ...Banco no reconocido.
400El campo 'telefono_pago_movil' debe tener exactamente 11 dígitos (ejemplo: 04141234567) en la nota de débito N° 000021.Teléfono de pago móvil inválido.
400El monto total registrado en los métodos de pago (100.00) es menor al total calculado de la nota de débito (116.00) en la nota de débito N° 000021. El total a pagar es 116.00. Si es a crédito o no cuenta con el pago aún, omita los métodos de pago.La suma de los pagos no cuadra con el total. Si la suma es mayor, el mensaje es ... no coincide con el total de la nota de débito N° ....
400El monto total calculado de la nota de débito (...) sobrepasa el límite máximo permitido de 9 dígitos enteros y 2 decimales (máximo 999.999.999,99) en la nota de débito N° 000021.Total demasiado alto.
400El campo Tasa de Cambio ('tasa_del_dia' o 'exchange_rate') es obligatorio en el JSON de la nota de débito N° 000021.Falta la tasa.
400La tasa de cambio ('tasa_del_dia') debe ser un número con hasta 6 enteros y hasta 8 decimales, separados por punto o coma (Ej: 342.8633) en la nota de débito N° 000021. Valor recibido: '36,5x'.Tasa con formato inválido.
400El campo Fecha de la Tasa de Cambio ('fecha_tasa') es obligatorio en el JSON de la nota de débito N° 000021.Falta la fecha de la tasa.
400El campo Fecha de la Tasa de Cambio ('fecha_tasa') debe tener un formato de fecha válido (DD-MM-YYYY) en la nota de débito N° 000021. Valor recibido: '21/10/2026'.Fecha con otro formato.
400No se permiten Notas de Débito para facturas a terceros.La factura afectada es una factura a terceros.
400No se pueden emitir notas de débito. Todos los items de esta factura ya han sido completamente acreditados por notas de crédito.La factura ya fue acreditada por completo.
400Tipo de contribuyente no establecido. Para continuar con la emisión de documentos fiscales, ...El negocio no tiene configurado su tipo de contribuyente.
401 / 400Ver ErroresToken ausente, mal formado, inválido o vencido.
409El número de nota de débito ya está en uso.Ya existe una nota de débito del negocio con ese número.
404El número de factura no existe.No hay una factura del negocio con ese número.
409No existe un número de control asociado al comercio.El negocio no tiene números de control.
409No hay números de control disponibles.No se encontró un número de control libre en el rango.
404RIF de comercio no existe.No se encontró el negocio del token.
400Tipo de tasa de impuesto no existe.tipoImpuesto no es una alícuota válida (al crear un producto nuevo).
500Error guardando la nota de débito, intente más tarde.Falló la transacción en la base de datos.
500Error general: ...Error interno inesperado.

Notas ​

  • Datos que se heredan. El cliente, la moneda y la serie se toman de la factura afectada. La tasa de cambio y su fecha se toman del cuerpo de la solicitud.
  • Cálculo. Base de cada línea = precioProducto × cantidadAdquirida; el IVA se calcula por alícuota. Si el codigoProducto ya existe en el negocio, la alícuota con la que se agrupa la línea es la del producto registrado; usa siempre el mismo tipoImpuesto con el que creaste el producto.
  • IGTF. Si hay un pago en divisa y el negocio está sujeto a IGTF (no es Contribuyente Ordinario), se suma un 3 % del monto en divisa al total de la nota.
  • Formato de monto. El ejemplo del mensaje de error (120.343.231,99) usa separadores de miles, pero según el código actual no se aceptan: envía "120343231.99" o "120343231,99". Envía siempre monto como texto, porque un número JSON como 116.5 pierde el segundo decimal y se rechaza.
  • Sin métodos de pago. Si no envías order_payment_methods, la nota se registra como pagada a crédito.
  • Una vez emitida una nota de débito sobre una factura, según el código actual ya no se puede emitir una nota de crédito total sobre esa factura.
  • Si la firma electrónica falla, la nota se guarda igualmente.

API de Facturación · CG Imprenta Digital