Skip to content

Nota de crédito ​

POST /api/Invoice/add_credit_note

Emite una nota de crédito total sobre una factura ya emitida por el negocio. La nota copia todos los productos, bases, impuestos y totales de la factura afectada, recibe un número de control y se firma electrónicamente. Devuelve el número de control asignado y el enlace al PDF.

Si solo quieres acreditar algunos productos o cantidades, usa Nota de crédito parcial.

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: "005172" y "5172" son facturas distintas). Solo dígitos (sin letras, guiones, espacios ni decimales), máximo 19 caracteres. Debe ser una factura del mismo negocio del token.
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í (ver regla)Motivo u observación de la nota, máximo 50 caracteres. Es obligatorio salvo cuando la factura afectada es una factura a terceros; en ese caso puede omitirse. También se acepta con el nombre description.
is_third_partyintegerNoEnvía 1 para marcar la nota como relativa a una factura a terceros. No hace falta enviarlo: el API detecta por sí mismo si la factura afectada es a terceros. También se acepta como is_third.

Ejemplo de solicitud ​

json
{
  "numeroFactura": "005172",
  "numeroNotaCredito": "000024",
  "descripcion": "Devolución total de la mercancía"
}

Respuesta exitosa ​

HTTP 200

json
{
  "success": true,
  "message": "Nota de crédito guardada satisfactoriamente.",
  "invoice_number_affected": "005172",
  "control_number": "00-00000125",
  "credit_note_pdf": "https://api.example.com/readonly/export_pdf/9b2c5e0f-4a7d-41c3-a8e6-1f2d7a90c4e1"
}
ClaveDescripción
successtrue si la nota se guardó.
messageMensaje de confirmación.
invoice_number_affectedNúmero de la factura afectada (el mismo numeroFactura enviado).
control_numberNúmero de control asignado a la nota, con formato serie-########.
credit_note_pdfEnlace al PDF de la nota de crédito.
warning_control_numbersSolo aparece cuando al negocio le quedan pocos números de control disponibles. Texto con usados, restantes y porcentajes.

La respuesta no repite el número de la nota de crédito: es el numeroNotaCredito que enviaste.

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). Cuando hay varios errores de validación de campos, se devuelven juntos en un solo message, separados por espacios.

HTTPMensaje (ejemplo)Causa
400El campo Número de Factura es obligatorio.Falta numeroFactura o está vacío.
400El campo Número de Factura debe contener solo números enteros (sin decimales, espacios ni caracteres especiales). Valor recibido: F-001.numeroFactura contiene algo distinto de dígitos.
400El campo Número de Factura no puede exceder los 19 caracteres. Longitud actual: 20.numeroFactura demasiado largo.
400El campo Número de Nota de Crédito es obligatorio.Falta numeroNotaCredito. Las mismas reglas de formato y longitud que numeroFactura aplican a este campo, con sus mensajes equivalentes.
400El campo Descripción no puede exceder los 50 caracteres. Longitud actual: 64.descripcion demasiado larga.
400El campo Descripción es obligatorio.Falta descripcion y la factura afectada no es a terceros.
400Tipo de contribuyente no establecido. Para continuar con la emisión de documentos fiscales, ...El negocio no tiene configurado su tipo de contribuyente. Hay que contactar a soporte.
401 / 400Ver ErroresToken ausente, mal formado, inválido o vencido.
409El número de nota de crédito ya está en uso.Ya existe una nota de crédito del negocio con ese numeroNotaCredito.
404El número de factura no existe.No hay una factura del negocio con ese numeroFactura.
409La factura indicada ya tiene una nota de crédito generada.La factura ya tiene una nota de crédito total (si tuvo parciales, el mensaje lo indica; ver Notas).
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 asociado al 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 ​

  • Una sola vez por factura. La nota se rechaza (409) si la factura ya tiene otra nota de crédito: si fue total, con La factura indicada ya tiene una nota de crédito generada.; si hubo notas parciales, con La factura indicada ya tiene notas de crédito parciales; para acreditar el resto use la nota de crédito parcial. Una nota de débito o una orden de entrega previas no impiden la nota de crédito total.
  • Montos. No se envían productos ni montos: la nota toma de la factura los productos, la tasa de cambio, la moneda, las bases y los impuestos por alícuota. Si la factura tuvo pagos en divisa, la nota registra también la base y el IGTF de esos pagos.
  • Facturas a terceros. Se permite la nota de crédito total sobre una factura a terceros (la nota de crédito parcial no lo permite). En ese caso descripcion es opcional.
  • Número de control. Se asigna automáticamente del rango del negocio; la nota queda emitida y firmada. Si la firma electrónica falla, la nota se guarda igualmente.
  • La fecha de la nota es la fecha del servidor en el momento de la solicitud.

API de Facturación · CG Imprenta Digital