Apariencia
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
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
numeroFactura | string | Sí | 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. |
numeroNotaDebito | string | Sí | 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. |
descripcion | string | Sí | Motivo u observación de la nota, máximo 50 caracteres. |
tasa_del_dia | string | Sí | 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_tasa | string | Sí | 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_nuevos | array | Sí | Productos o conceptos que se cargan en la nota. Al menos uno. Ver productos_nuevos[]. |
order_payment_methods | array | No | Mé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[]
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
codigoProducto | string | Sí | 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. |
nombreProducto | string | Sí | Nombre del producto, máximo 400 caracteres. Se usa al crear el producto. |
descripcionProducto | string | Sí | Descripción que se imprime en la línea de la nota, máximo 400 caracteres. |
tipoImpuesto | string | Sí | Alícuota de IVA: E (exento, 0 %), R (reducida, 8 %), G (general, 16 %), A (adicional, 31 %), P (percibido, 0 %). |
cantidadAdquirida | number o string | Sí | Cantidad, mayor que 0, con punto decimal (por ejemplo 15.63 o "2"). Sin signo ni separadores de miles. |
precioProducto | string o number | Sí | 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[]
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
order_payment_method | string | Sí | 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. |
monto | string | Sí | 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. |
banco | string | Para transferencia y pago movil | Nombre del banco, tal como aparece en Bancos. |
numero_de_referencia_de_operacion | string | Para transferencia y pago movil | Exactamente 4 dígitos (los últimos de la referencia). |
telefono_pago_movil | string | Para pago movil | Teléfono con exactamente 11 dígitos, por ejemplo "04141234567". |
note | string | No | Nota 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"
}| Clave | Descripción |
|---|---|
success | true si la nota se guardó. |
message | Mensaje de confirmación. |
debit_note_number | Número de la nota de débito emitida. |
invoice_number_affected | Número de la factura afectada. |
control_number | Número de control asignado, con formato serie-########. |
debit_note_pdf | Enlace al PDF de la nota. |
warning_control_numbers | Solo 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.
| HTTP | Mensaje (ejemplo) | Causa |
|---|---|---|
| 400 | El campo Número de Factura es obligatorio. | Falta numeroFactura. Igual para El campo Número de Nota de Débito es obligatorio. |
| 400 | El 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. |
| 400 | El campo Número de Nota de Débito no puede exceder los 19 caracteres. Longitud actual: 20. | Número demasiado largo (equivalente para numeroFactura). |
| 400 | El campo Descripción es obligatorio. | Falta descripcion. |
| 400 | El campo Descripción no puede exceder los 50 caracteres. Longitud actual: 58. | descripcion demasiado larga. |
| 400 | El campo productos_nuevos es obligatorio y no debe estar vacío. | Falta productos_nuevos o está vacío. |
| 400 | La cantidad de productos por nota de débito no puede ser mayor a 50 | Se superó el límite de productos por documento configurado en la plataforma (el número varía). |
| 400 | Error: Productos duplicados en la nota de débito. | Dos líneas con el mismo código y descripción. |
| 400 | El 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. |
| 400 | El 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.). |
| 400 | El campo Cantidad Adquirida en el producto 1 debe ser un número válido. | Cantidad no numérica (por ejemplo, con coma decimal). |
| 400 | El 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. |
| 400 | La 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. |
| 400 | El 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. |
| 400 | El 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). |
| 400 | El 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. |
| 400 | El banco 'Banco Inventado' no es válido. Bancos disponibles: ... | Banco no reconocido. |
| 400 | El 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. |
| 400 | El 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° .... |
| 400 | El 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. |
| 400 | El 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. |
| 400 | La 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. |
| 400 | El 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. |
| 400 | El 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. |
| 400 | No se permiten Notas de Débito para facturas a terceros. | La factura afectada es una factura a terceros. |
| 400 | No 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. |
| 400 | Tipo de contribuyente no establecido. Para continuar con la emisión de documentos fiscales, ... | El negocio no tiene configurado su tipo de contribuyente. |
| 401 / 400 | Ver Errores | Token ausente, mal formado, inválido o vencido. |
| 409 | El número de nota de débito ya está en uso. | Ya existe una nota de débito del negocio con ese número. |
| 404 | El número de factura no existe. | No hay una factura del negocio con ese número. |
| 409 | No existe un número de control asociado al comercio. | El negocio no tiene números de control. |
| 409 | No hay números de control disponibles. | No se encontró un número de control libre en el rango. |
| 404 | RIF de comercio no existe. | No se encontró el negocio del token. |
| 400 | Tipo de tasa de impuesto no existe. | tipoImpuesto no es una alícuota válida (al crear un producto nuevo). |
| 500 | Error guardando la nota de débito, intente más tarde. | Falló la transacción en la base de datos. |
| 500 | Error 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 elcodigoProductoya existe en el negocio, la alícuota con la que se agrupa la línea es la del producto registrado; usa siempre el mismotipoImpuestocon el que creaste el producto. - IGTF. Si hay un pago en
divisay 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 siempremontocomo texto, porque un número JSON como116.5pierde 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.
