Apariencia
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
| 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: "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. |
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í (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_party | integer | No | Enví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"
}| Clave | Descripción |
|---|---|
success | true si la nota se guardó. |
message | Mensaje de confirmación. |
invoice_number_affected | Número de la factura afectada (el mismo numeroFactura enviado). |
control_number | Número de control asignado a la nota, con formato serie-########. |
credit_note_pdf | Enlace al PDF de la nota de crédito. |
warning_control_numbers | Solo 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.
| HTTP | Mensaje (ejemplo) | Causa |
|---|---|---|
| 400 | El campo Número de Factura es obligatorio. | Falta numeroFactura o está vacío. |
| 400 | El 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. |
| 400 | El campo Número de Factura no puede exceder los 19 caracteres. Longitud actual: 20. | numeroFactura demasiado largo. |
| 400 | El 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. |
| 400 | El campo Descripción no puede exceder los 50 caracteres. Longitud actual: 64. | descripcion demasiado larga. |
| 400 | El campo Descripción es obligatorio. | Falta descripcion y la factura afectada no es a terceros. |
| 400 | Tipo 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 / 400 | Ver Errores | Token ausente, mal formado, inválido o vencido. |
| 409 | El número de nota de crédito ya está en uso. | Ya existe una nota de crédito del negocio con ese numeroNotaCredito. |
| 404 | El número de factura no existe. | No hay una factura del negocio con ese numeroFactura. |
| 409 | La 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). |
| 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 asociado al 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
- Una sola vez por factura. La nota se rechaza (
409) si la factura ya tiene otra nota de crédito: si fue total, conLa factura indicada ya tiene una nota de crédito generada.; si hubo notas parciales, conLa 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
descripciones 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.
