Skip to content

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 ​

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.
numeroNotaCreditostringSí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.
descripcionstringSíMotivo u observación de la nota, máximo 50 caracteres.
productosarraySíProductos de la factura a acreditar. Al menos uno. Ver productos[].

productos[] ​

Cada elemento identifica un producto que ya está en la factura original.

CampoTipoObligatorioDescripción y reglas
codigostringSíCódigo del producto tal como se envió en la factura (codigoProducto).
descripcionstringSí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.
cantidadstring o numberSí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).
lotestringSolo farmaciasPara 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"
    }
  ]
}
ClaveDescripción
successtrue si la nota se guardó.
messageMensaje de confirmación.
note_credit_numberNúmero de la nota de crédito emitida.
invoice_number_affectedNúmero de la factura afectada.
control_numberNúmero de control asignado, con formato serie-########.
credit_note_pdfEnlace al PDF de la nota.
productos_acreditados_esta_ncProductos acreditados en esta nota: codigo, descripcion, cantidad_acreditada_esta_nc y precio_unitario (texto con 2 decimales). En farmacias incluye lote.
productos_disponibles_factura_originalEstado 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_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 formato de numeroFactura, numeroNotaCredito y descripcion se devuelven juntos en un solo message.

HTTPMensaje (ejemplo)Causa
400El campo Productos es obligatorio y debe contener al menos un producto.Falta productos, no es un arreglo o está vacío.
400El campo Número de Factura es obligatorio.Falta numeroFactura. Igual para El campo Número de Nota de Crédito es obligatorio.
400El 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.
400El campo Número de Factura no puede exceder los 19 caracteres. Longitud actual: 20.Demasiado largo. Equivalente para numeroNotaCredito.
400El campo Descripción es obligatorio.Falta descripcion o está vacía.
400El campo Descripción no puede exceder los 50 caracteres. Longitud actual: 61.descripcion demasiado larga.
400Error en el producto índice 1: El campo cantidad debe ser mayor a 0.Cantidad igual o menor que cero. El índice empieza en 0.
400Error 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.
400Error en el producto índice 1: El campo cantidad no puede contener signo negativo (-) al inicio o al final.Cantidad negativa.
400No 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.
400El 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.
400El producto 'PT-0001' con descripción 'PAPEL TOILET' solo tiene 8 unidades disponibles (Original: 10, Ya acreditadas: 2).La cantidad pedida supera lo disponible.
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.
409La factura no tiene items disponibles para acreditar. Todos los productos ya han sido completamente acreditados.Todas las cantidades de la factura ya fueron acreditadas.
409El número de nota de crédito ya está en uso.Ya existe una nota de crédito 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 disponibles.
404RIF de Comercio no existe.No se encontró el negocio del token.
500Error guardando la nota de crédito, intente más tarde.Falló la transacción en la base de datos.
500Error 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_original de 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 cantidad como texto con . o , decimal y mayor que cero. Según el código actual, las comprobaciones de formato de cantidad (signo, caracteres, mayor que cero) solo se aplican al último producto del arreglo; en los demás, un valor no numérico o 0 hace que la línea se omita sin error.
  • Si la firma electrónica falla, la nota se guarda igualmente.

API de Facturación · CG Imprenta Digital