Apariencia
Nota de crédito parcial
POST /api/Invoice/add_credit_note_with_products
Emite una nota de crédito por productos y cantidades concretas de una factura ya emitida. Puedes emitir varias notas parciales sobre la misma factura hasta acreditar todas sus cantidades. Devuelve el número de control, el PDF y el estado de lo acreditado y lo que queda disponible por producto.
Para acreditar la factura completa de una sola vez, usa Nota de crédito.
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. |
numeroNotaCredito | string | Sí | Número que tendrá la nota de crédito. Solo dígitos, máximo 19 caracteres. No puede estar ya usado por otra nota de crédito del negocio. |
descripcion | string | Sí | Motivo u observación de la nota, máximo 50 caracteres. |
productos | array | Sí | Productos de la factura a acreditar. Al menos uno. Ver productos[]. |
productos[]
Cada elemento identifica un producto que ya está en la factura original.
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
codigo | string | Sí | Código del producto tal como se envió en la factura (codigoProducto). |
descripcion | string | Sí | Descripción del producto tal como se envió en la factura (descripcionProducto). La combinación codigo + descripcion debe coincidir exactamente (incluidas mayúsculas, minúsculas y acentos) con una línea de la factura. |
cantidad | string o number | Sí | Cantidad a acreditar, mayor que 0. Solo dígitos con separador decimal . o , (por ejemplo "2", "1.50", "1,50"); sin signo negativo. No puede superar la cantidad aún disponible de ese producto (cantidad facturada menos lo acreditado en notas anteriores; se tolera una diferencia de 0,01). |
lote | string | Solo farmacias | Para negocios con plantilla de farmacia, el lote del producto; forma parte de la identificación de la línea junto con codigo y descripcion. En los demás negocios se ignora. |
Los productos de la factura que no incluyas no se acreditan en esta nota.
Ejemplo de solicitud
json
{
"numeroFactura": "000180",
"numeroNotaCredito": "000076",
"descripcion": "Devolución parcial de mercancía",
"productos": [
{
"codigo": "PT-0001",
"descripcion": "PAPEL TOILET",
"cantidad": "2.00"
},
{
"codigo": "CI-0001",
"descripcion": "CAFE INSTANTANEO",
"cantidad": "1"
}
]
}Respuesta exitosa
HTTP 200
json
{
"success": true,
"message": "Nota de crédito guardada satisfactoriamente.",
"note_credit_number": "000076",
"invoice_number_affected": "000180",
"control_number": "00-00000126",
"credit_note_pdf": "https://api.example.com/readonly/export_pdf/2f7d1c9a-0b4e-48a6-a3c5-5e1b9d0f7c22",
"productos_acreditados_esta_nc": [
{
"codigo": "PT-0001",
"descripcion": "PAPEL TOILET",
"cantidad_acreditada_esta_nc": 2,
"precio_unitario": "1.55"
},
{
"codigo": "CI-0001",
"descripcion": "CAFE INSTANTANEO",
"cantidad_acreditada_esta_nc": 1,
"precio_unitario": "4.20"
}
],
"productos_disponibles_factura_original": [
{
"codigo": "PT-0001",
"descripcion": "PAPEL TOILET",
"cantidad_original": 10,
"cantidad_acreditada_total": 2,
"cantidad_disponible": 8,
"precio_unitario": "1.55"
},
{
"codigo": "CI-0001",
"descripcion": "CAFE INSTANTANEO",
"cantidad_original": 3,
"cantidad_acreditada_total": 1,
"cantidad_disponible": 2,
"precio_unitario": "4.20"
}
]
}| Clave | Descripción |
|---|---|
success | true si la nota se guardó. |
message | Mensaje de confirmación. |
note_credit_number | Número de la nota de crédito emitida. |
invoice_number_affected | Número de la factura afectada. |
control_number | Número de control asignado, con formato serie-########. |
credit_note_pdf | Enlace al PDF de la nota. |
productos_acreditados_esta_nc | Productos acreditados en esta nota: codigo, descripcion, cantidad_acreditada_esta_nc y precio_unitario (texto con 2 decimales). En farmacias incluye lote. |
productos_disponibles_factura_original | Estado de todas las líneas de la factura después de esta nota: cantidad_original, cantidad_acreditada_total (sumando todas las notas), cantidad_disponible y precio_unitario. En farmacias incluye lote. |
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 formato de numeroFactura, numeroNotaCredito y descripcion se devuelven juntos en un solo message.
| HTTP | Mensaje (ejemplo) | Causa |
|---|---|---|
| 400 | El campo Productos es obligatorio y debe contener al menos un producto. | Falta productos, no es un arreglo o está vacío. |
| 400 | El campo Número de Factura es obligatorio. | Falta numeroFactura. Igual para El campo Número de Nota de Crédito es obligatorio. |
| 400 | El campo Número de Factura debe contener solo números enteros (sin decimales, espacios, letras ni caracteres especiales). Valor recibido: F-180. | Formato inválido. Hay mensaje equivalente para numeroNotaCredito. |
| 400 | El campo Número de Factura no puede exceder los 19 caracteres. Longitud actual: 20. | Demasiado largo. Equivalente para numeroNotaCredito. |
| 400 | El campo Descripción es obligatorio. | Falta descripcion o está vacía. |
| 400 | El campo Descripción no puede exceder los 50 caracteres. Longitud actual: 61. | descripcion demasiado larga. |
| 400 | Error en el producto índice 1: El campo cantidad debe ser mayor a 0. | Cantidad igual o menor que cero. El índice empieza en 0. |
| 400 | Error en el producto índice 1: El campo cantidad solo puede contener números y decimales (. o ,). No se permiten letras ni caracteres especiales. | Cantidad con caracteres no válidos. |
| 400 | Error en el producto índice 1: El campo cantidad no puede contener signo negativo (-) al inicio o al final. | Cantidad negativa. |
| 400 | No se permiten Notas de Crédito parciales para facturas a terceros. | La factura afectada es una factura a terceros. Usa la nota de crédito total. |
| 400 | El producto #0 con código 'PT-0001' y descripción 'PAPEL TOILET' no existe en la factura original. | La combinación codigo + descripcion (y lote en farmacias, con el texto (verifique el lote).) no coincide con ninguna línea de la factura. |
| 400 | El producto 'PT-0001' con descripción 'PAPEL TOILET' solo tiene 8 unidades disponibles (Original: 10, Ya acreditadas: 2). | La cantidad pedida supera lo disponible. |
| 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 | La factura no tiene items disponibles para acreditar. Todos los productos ya han sido completamente acreditados. | Todas las cantidades de la factura ya fueron acreditadas. |
| 409 | El número de nota de crédito ya está en uso. | Ya existe una nota de crédito 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 disponibles. |
| 404 | RIF de Comercio no existe. | No se encontró el negocio del token. |
| 500 | Error guardando la nota de crédito, intente más tarde. | Falló la transacción en la base de datos. |
| 500 | Error en la lógica del proceso: ... | Error interno inesperado. |
Notas
- Cálculo. El precio unitario y la alícuota de cada línea se toman de la factura original; tú solo indicas la cantidad. El IVA se calcula por alícuota sobre la base agrupada y se redondea a 2 decimales.
- IGTF. Si la factura original se pagó (total o parcialmente) en divisa y el negocio está sujeto a IGTF, la nota incluye la parte proporcional del IGTF en su total.
- Varias notas parciales. El API lleva el control de lo acreditado por línea. Usa
productos_disponibles_factura_originalde la respuesta para saber cuánto queda. - Relación con la nota de crédito total. Una vez emitida una nota parcial sobre una factura, según el código actual ya no se puede emitir una nota de crédito total sobre esa misma factura.
- Validación de cantidades. Envía cada
cantidadcomo texto con.o,decimal y mayor que cero. Según el código actual, las comprobaciones de formato decantidad(signo, caracteres, mayor que cero) solo se aplican al último producto del arreglo; en los demás, un valor no numérico o0hace que la línea se omita sin error. - Si la firma electrónica falla, la nota se guarda igualmente.
