Skip to content

Agregar factura ​

POST /api/Invoice/add_list_invoice

Emite una o varias facturas fiscales en una sola llamada. A cada factura se le asigna el siguiente número de control disponible del negocio, se registra el cliente y los productos que aún no existan, se guardan los pagos (o la factura queda a crédito si no se envían) y se devuelve el enlace al PDF de cada factura emitida.

Autenticación: Authorization: Bearer <token> (cómo obtenerlo) · Content-Type: application/json

Cuerpo de la solicitud ​

CampoTipoObligatorioDescripción y reglas
numeroSeriestringSíSerie de numeración del negocio (por ejemplo "A"). Debe corresponder a una serie configurada para su negocio.
cantidadFacturaintegerSíCantidad de facturas que trae el arreglo facturas. Debe ser un entero y coincidir exactamente con el número de elementos de facturas; si no coincide, no se emite ninguna.
facturasarraySíLista de facturas a emitir. No puede estar vacía. Ver facturas[].

facturas[] ​

Identificación de la factura

CampoTipoObligatorioDescripción y reglas
numeroFacturastringSíNúmero de la factura en su sistema. Solo dígitos (^[0-9]+$), sin decimales, espacios ni signos; máximo 19 caracteres. Se recomienda enviarlo como texto para conservar los ceros a la izquierda ("000123"). No puede repetirse ni dentro de la misma solicitud ni respecto a una factura ya emitida por su negocio (ver Duplicados).
descripcionFacturastringNoDescripción u observación general de la factura. Máximo 500 caracteres. No se admite si el negocio (o la propia factura) tiene un mensaje fijo activo (ver fixed_message).
fixed_messagestringNoMensaje fijo / coletilla que se imprime en la factura. Alias aceptado: mensajeFijo. Si el negocio ya tiene una coletilla configurada, se usa siempre la del negocio y este campo se ignora. Cuando hay mensaje fijo (del negocio o de la factura), descripcionFactura debe ir vacía o se rechaza la factura.

Cliente (receptor)

CampoTipoObligatorioDescripción y reglas
documentoIdentidadClientestringSí (salvo exportación)RIF o cédula del cliente: una letra V, E, P, J, G o C seguida de 8 a 10 dígitos, sin guiones ni espacios (ej. V12345678, J123456789). Si el cliente no existe en su negocio se crea automáticamente; si existe, se actualizan su nombre, correo, teléfono y dirección con los datos enviados.
nombreRazonSocialClientestringSíNombre o razón social del cliente.
correoClientestringSíCorreo del cliente. Se normaliza antes de validarlo: se pasa a minúsculas, se eliminan espacios y caracteres no permitidos; si el resultado no es un correo válido, se rechaza.
direccionClientestringSíDirección fiscal del cliente.
telefonoClientestringSíTeléfono del cliente. Solo se exige que no esté vacío.
is_client_exportintegerNo1 si el cliente es de exportación. Alias aceptado: es_cliente_export. En ese caso documentoIdentidadCliente no se valida (solo se toma su primera letra, por defecto V) y todos los productos deben llevar tipoImpuesto X.

Tasa de cambio y moneda

CampoTipoObligatorioDescripción y reglas
tasa_del_diastringSíTasa de cambio Bs/USD del día. Alias aceptados: exchange_rate, current_exchange_rate, tasa_de_cambio. Número positivo con hasta 6 enteros y hasta 8 decimales (ej. "342.8633", "36.5"); se acepta coma o punto como separador decimal. Debe ser mayor que cero.
fecha_tasastringSíFecha de la tasa de cambio. Alias aceptados: current_exchange, fecha_tasa_de_cambio, fecha_tasa_del_dia. Formatos aceptados: DD-MM-YYYY (ej. "09-10-2026") o YYYY-MM-DD.
product_currencyintegerNo1 para que la factura muestre, además de los montos en Bs, sus equivalentes en USD (cada monto en Bs dividido entre la tasa). Los precios se siguen enviando en Bs. Solo se admite si el negocio tiene activadas la dualidad de moneda y la moneda en productos.
dualidad_de_monedaintegerNo0 o 1. Con 0 se desactiva la dualidad de moneda solo para esta factura (se emite únicamente en Bs) aunque el negocio la tenga activa. No se puede enviar 1 si el negocio no tiene la dualidad activada, ni combinar 0 con product_currency: 1.

Contenido y pago

CampoTipoObligatorioDescripción y reglas
productosarraySíRenglones de la factura. No puede estar vacío. Ver productos[].
order_payment_methodsarrayNoFormas de pago de la factura (máximo 5). Si se omite o se envía vacío, la factura queda registrada a crédito. Ver order_payment_methods[].
mostrar_formas_de_pagointegerNo0 (por defecto) o 1. Con 1 el PDF muestra el bloque "Formas de Pago" (también cuando la factura queda a crédito).

productos[] ​

CampoTipoObligatorioDescripción y reglas
codigoProductostringSíCódigo del producto en su catálogo. Máximo 13 caracteres y sin espacios. Si el código no existe en su negocio, el producto se registra automáticamente con el nombre, precio y alícuota enviados.
nombreProductostringSíNombre del producto. Máximo 400 caracteres.
descripcionProductostringSíDescripción que se imprime en el renglón. Admite saltos de línea. Ver el límite combinado con product_note.
product_notestringNoComentario adicional del renglón. La suma de descripcionProducto + product_note no puede pasar de 450 caracteres ni ocupar más de 9 líneas de 50 caracteres (cada salto de línea inicia una línea nueva).
tipoImpuestostringSíAlícuota de IVA: G (general, 16 %), R (reducida, 8 %), A (adicional / lujo, 31 %), E (exento), P (percibido, 0 %) o X (exportación, solo para clientes de exportación). Si el producto ya existe en su catálogo, debe enviarse con la misma alícuota con la que está registrado.
cantidadAdquiridastring | numberSíCantidad. Número mayor que cero; los decimales se separan con punto (ej. "2.5"). Sin signos ni separadores de miles.
precioProductostring | numberSíPrecio unitario en bolívares, sin IVA. Mayor que cero, máximo 9 enteros y 2 decimales; separador decimal punto o coma ("100.00" o "100,00"), sin separadores de miles.
discountnumber | stringNoDescuento del renglón en porcentaje: mayor o igual a 0 y menor que 100 (coma o punto). Por defecto 0.
rifTercerostringNoRIF del tercero por cuya cuenta se vende el producto (venta a terceros): letra V, E, P, J, G o C + 8 a 10 dígitos. Si se envía, nombreRifTercero es obligatorio.
nombreRifTercerostringNoRazón social del tercero. Máximo 70 caracteres. Si se envía, rifTercero es obligatorio.
lotestringNoLote del producto. Para negocios con plantilla farmacéutica se valida un máximo de 10 caracteres.
fechaVencimientostringNoFecha de vencimiento del lote, formato DD-MM-YYYY (ej. "08-08-2025"). Se valida en negocios con plantilla farmacéutica.

Productos de terceros

Si al menos un renglón trae rifTercero y nombreRifTercero, la factura se trata como factura con venta a terceros: admite como máximo 8 productos en total (propios + de terceros) y el enlace devuelto apunta al PDF de terceros. Para facturas exclusivamente de terceros también existe Factura a terceros.

order_payment_methods[] ​

Todos los montos se expresan en bolívares con exactamente 2 decimales, incluido el pago en divisa (su equivalente en Bs).

CampoTipoObligatorioDescripción y reglas
order_payment_methodstringSíForma de pago. Valores reconocidos: divisa, efectivo, transferencia, pago movil (también se acepta pago móvil, con acento). Máximo 20 caracteres (si se excede, el documento se rechaza). 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.
montostringSíMonto pagado con esta forma de pago. Hasta 9 enteros y exactamente 2 decimales ("1160.00" o "1160,00"), mayor que cero. No use separadores de miles.
bancostringPara transferencia y pago movilNombre del banco tal como aparece en Bancos (no distingue mayúsculas). Si no se reconoce, el error lista los bancos disponibles.
numero_de_referencia_de_operacionstringPara transferencia y pago movilReferencia de la operación: exactamente 4 dígitos (normalmente los últimos 4 de la referencia bancaria).
telefono_pago_movilstringPara pago movilTeléfono desde el que se hizo el pago móvil. Debe contener 11 dígitos (ej. "04141234567"); se descartan los caracteres no numéricos.
notestringNoNota libre que se guarda con el pago.

Reglas del conjunto de pagos:

  • Máximo 5 formas de pago por factura.
  • divisa puede aparecer una sola vez y debe ser la primera del arreglo.
  • La suma de los monto debe cuadrar con el total de la factura (ver IGTF). Si la factura es a crédito o aún no tiene pago, omita order_payment_methods.
  • Cualquier otro campo (por ejemplo igtf) se ignora: el IGTF lo calcula el servidor.

Ejemplo de solicitud ​

json
{
  "numeroSerie": "A",
  "cantidadFactura": 1,
  "facturas": [
    {
      "numeroFactura": "000123",
      "descripcionFactura": "Servicio de mantenimiento mensual",
      "documentoIdentidadCliente": "J123456789",
      "nombreRazonSocialCliente": "Cliente Ejemplo C.A.",
      "correoCliente": "facturacion@example.com",
      "direccionCliente": "Av. Principal, Caracas",
      "telefonoCliente": "04141234567",
      "tasa_del_dia": "342.8633",
      "fecha_tasa": "09-10-2026",
      "mostrar_formas_de_pago": 1,
      "productos": [
        {
          "codigoProducto": "SERV-001",
          "nombreProducto": "Mantenimiento preventivo",
          "descripcionProducto": "Mantenimiento preventivo de equipos",
          "product_note": "Incluye visita técnica",
          "tipoImpuesto": "G",
          "cantidadAdquirida": "1",
          "precioProducto": "1000.00",
          "discount": 0
        }
      ],
      "order_payment_methods": [
        {
          "order_payment_method": "transferencia",
          "monto": "1160.00",
          "banco": "Banco de Venezuela",
          "numero_de_referencia_de_operacion": "1234"
        }
      ]
    }
  ]
}

Ejemplo con pago en divisa (negocio al que le aplica IGTF; total de la factura 1.160,00 Bs):

json
"order_payment_methods": [
  { "order_payment_method": "divisa", "monto": "1000.00" },
  { "order_payment_method": "pago movil", "monto": "160.00", "banco": "Banco de Venezuela",
    "telefono_pago_movil": "04141234567", "numero_de_referencia_de_operacion": "5678" }
]

Aquí los pagos suman 1.160,00 (el total sin IGTF) y el servidor añade el IGTF de 30,00 (3 % de 1.000,00) al pago en divisa; el total facturado queda en 1.190,00. También se acepta enviar los montos ya con el IGTF incluido (sumando 1.190,00).

Respuesta exitosa ​

HTTP 200

json
{
  "success": true,
  "message": "Facturas guardadas satisfactoriamente.",
  "invoice_errors": [],
  "invoice_list_success": [
    {
      "invoice_number": "000123",
      "control_number": "00-00000056",
      "invoice_pdf": "https://<su-dominio>/readonly/export_pdf/c68c9c82-58ea-4d85-a72d-d6fd0015f047"
    }
  ]
}
ClaveDescripción
successtrue si se emitió al menos una factura (aunque otras se hayan omitido por duplicadas). Si todas estaban registradas: false con HTTP 409.
messageFacturas guardadas satisfactoriamente. si se emitieron todas; Las facturas se guardaron correctamente, pero algunas estaban duplicadas y no pudieron guardarse. si se omitieron algunas; Error: facturas ya registradas. si todas estaban duplicadas (en este caso success sigue siendo true y no se emite nada).
invoice_errorsNúmeros de factura (numeroFactura) que no se emitieron por estar duplicados.
invoice_list_successUna entrada por factura emitida: invoice_number (su número), control_number (número de control asignado, formato SS-NNNNNNNN) e invoice_pdf (enlace público al PDF; para facturas con productos de terceros apunta a readonly/export_pdf_tercero/...).
warning_control_numbersSolo aparece cuando quedan pocos números de control disponibles. Texto con usados, restantes y porcentajes, por ejemplo: La cantidad de número de control es baja: Total usados: 950, Total restantes: 50, Porcentaje usado: 95%, Porcentaje restante: 5%.

Errores ​

Los mensajes de validación de las facturas se acumulan: si hay varios problemas, message los trae todos concatenados con un espacio.

json
{
  "success": false,
  "message": "El campo Correo del Cliente en la factura 000123 es obligatorio. El campo Precio del Producto en el producto 1 de la factura 000123 es obligatorio."
}
HTTPMensaje (ejemplo)Causa
400 / 401—Token ausente, mal formado, inválido o expirado. Ver Errores.
400Json de facturas no enviado.Cuerpo vacío o que no es JSON.
400El campo Número de Serie es obligatorio.Falta numeroSerie.
400El campo Cantidad de Facturas es obligatorio.Falta cantidadFactura (si no es entero, el mensaje llega en inglés: The Cantidad de Facturas field must contain an integer.).
400Tipo de contribuyente no establecido. Para continuar con la emisión de documentos fiscales, es necesario establecer el tipo de contribuyente de su negocio. ...El negocio no tiene configurado su tipo de contribuyente. Contacte a soporte.
400No se encontró información del negocio asociado al usuario.El token no corresponde a un negocio.
400El campo Facturas es obligatorio y no debe estar vacío.Falta facturas o está vacío.
400El campo Número de Factura en la factura 1 debe contener solo números enteros (sin decimales, espacios ni caracteres especiales). Valor recibido: A-123.numeroFactura con caracteres no numéricos (también: obligatorio, máximo 19 caracteres).
400No se puede procesar la factura N° 000123 con Descripción de Factura, ya que la empresa tiene una Coletilla / Mensaje Fijo activo.Se envió descripcionFactura y hay mensaje fijo activo.
400El campo Descripción de Factura en la factura 1 debe tener máximo 500 caracteres. Actualmente tiene 520 caracteres (excede por 20 caracteres).Descripción demasiado larga.
400El campo Documento de Identidad del Cliente en la factura 000123 debe comenzar con V, E, P, J, G o C seguido de al menos 5 dígitos. / El campo Documento de Identidad del Cliente debe ser una letra válida seguida de máximo 10 números.Documento del cliente con formato inválido (debe ser letra + 8 a 10 dígitos).
400El campo Nombre o Razón Social del Cliente en la factura 000123 es obligatorio.Falta un dato del cliente (igual para Correo, Dirección y Teléfono).
400El campo Correo del Cliente en la factura 000123 contiene caracteres inválidos y no pudo ser procesado.El correo no se pudo normalizar (o ... es inválido incluso después de limpieza. Valor recibido: ...).
400El campo Tasa de Cambio ('tasa_del_dia' o 'exchange_rate') es obligatorio en el JSON de la factura 000123.Falta la tasa.
400La 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 factura 000123. Valor recibido: '36,5x'.Tasa con formato inválido.
400El campo Fecha de la Tasa de Cambio ('fecha_tasa') es obligatorio en el JSON de la factura 000123.Falta la fecha de la tasa (o ... debe tener un formato de fecha válido (DD-MM-YYYY) ...).
400El campo product_currency no puede ser 1 en la factura 000123 si el negocio no tiene activada la dualidad de moneda en su configuración.product_currency/dualidad_de_moneda no permitidos por la configuración del negocio, o valores distintos de 0/1.
400El campo Productos en la factura 000123 es obligatorio y no debe estar vacío.Falta productos.
400El campo Código del Producto en el producto 1 de la factura 000123 no puede exceder los 13 caracteres.Código demasiado largo (también: obligatorio, no puede contener espacios).
400El campo Nombre del Producto en el producto 1 de la factura 000123 no puede exceder los 400 caracteres.Nombre demasiado largo (o falta).
400La descripción y el comentario del producto 1 de la factura 000123 exceden el límite de 450 caracteres equivalentes (máximo 9 líneas). Caracteres equivalentes calculados: 500.Descripción + comentario ocupan más de 9 líneas (o ... no puede exceder los 450 caracteres reales ...).
400El campo Cantidad Adquirida en el producto 1 de la factura 000123 debe ser mayor que cero. Valor recibido: 0.Cantidad inválida (también: obligatoria, debe ser un número válido).
400El campo Precio del Producto en el producto 1 de la factura 000123 debe ser un número decimal válido con punto o coma (sin caracteres especiales ni negativos).Precio con formato inválido (también: obligatorio, mayor que cero, debe contener solo 9 (nueve) enteros y 2 (dos) decimales).
400El campo Discount en el producto 1 de la factura 000123 debe ser mayor o igual a 0 y menor a 100.Descuento fuera de rango o no numérico.
400En la factura 000123, si se usa Facturación a Terceros en el producto 1 debes enviar ambos campos: rifTercero y nombreRifTercero.Datos de tercero incompletos o inválidos.
400La factura 000123 excede el límite de 8 productos en total. Cantidad recibida: 9 (7 propios + 2 terceros).Factura con productos de terceros y más de 8 renglones.
400La factura N° 000123 no puede contener más de 5 métodos de pago.Más de 5 formas de pago.
400El método de pago 'divisa' debe registrarse como el primer método de pago en la factura N° 000123.divisa no es la primera (o No se permite registrar el método de pago 'divisa' más de una vez ...).
400El campo 'monto' debe tener hasta 9 dígitos enteros y exactamente 2 decimales en la factura 000123.monto mal formado (también: obligatorio, mayor que cero).
400El campo 'numero_de_referencia_de_operacion' debe contener exactamente 4 dígitos numéricos en la factura 000123.Referencia faltante o inválida en transferencia/pago móvil.
400El campo 'telefono_pago_movil' debe tener exactamente 11 dígitos (ejemplo: 04141234567) en la factura 000123.Teléfono de pago móvil inválido.
400El banco 'Banco Inexistente' no es válido. Bancos disponibles: ...Banco no reconocido (en pago móvil: ... no es válido para pago móvil. ...).
400El monto total registrado en los métodos de pago (1000.00) es menor al total calculado de la factura (1160.00) en la factura N° 000123. El total a pagar es 1160.00. Si la factura es a crédito o no cuenta con el pago aún, omita los métodos de pago.Los pagos no cubren el total (o ... no coincide con el total de la factura ... si lo exceden). Ver IGTF.
400El monto total calculado de la factura (1000000000.00) sobrepasa el límite máximo permitido de 9 dígitos enteros y 2 decimales (máximo 999.999.999,99) en la factura N° 000123.Total de la factura demasiado alto.
400Cantidad de Facturas Incorrecta.cantidadFactura no coincide con el número de elementos de facturas.
404El comercio indicado aún no está registrado.El negocio del token no está registrado.
409El comercio no Posee más números de control activos.El negocio agotó sus números de control (variante: El Comercio no Posee más números de Control Activos.).
400La cantidad de líneas por factura no puede ser mayor a NSe superó el límite de líneas por factura (ver Notas). Incluye facturas_error con numeroFactura, cantidadProductos y cantidadLineas de cada factura afectada.
400Error: Productos duplicados en la factura 000123: Código: SERV-001 - Mantenimiento preventivo.Dos renglones con el mismo codigoProducto + descripcionProducto (en negocios con plantilla farmacéutica se distinguen además por lote y se permiten). Llega dentro de un arreglo errors (cada elemento con success, message y numeroFactura).
400La alícuota X (exportación) del producto con código SERV-001 solo puede ser utilizada para clientes de exportación.Alícuota X con cliente nacional (o Para clientes de exportación, la alícuota del producto con código ... debe ser X.).
400El producto con código SERV-001 ya está registrado en el sistema con la alícuota G, pero en la petición se envió con la alícuota E.La alícuota enviada no coincide con la del producto existente.
400Tipo de tasa de impuesto no existe en la base de datos.tipoImpuesto no reconocido al crear un producto nuevo.
400Tipo de Documento de identidad Invalido.La letra del documento del cliente no está registrada.
500Error Guardando las Facturas, Intente Mas Tarde.Falló el guardado; no se emitió ninguna factura del lote. Incluye invoice_errors.

Notas ​

Cálculo de totales ​

  • Base de cada renglón = precioProducto × cantidadAdquirida, menos el discount (%) del renglón.
  • El IVA se calcula una sola vez por alícuota sobre la suma de las bases (no renglón por renglón) y se redondea a 2 decimales: G 16 %, R 8 %, A 31 %; E, P y X no generan IVA.
  • Total de la factura = suma de bases (con descuento) + IVA + IGTF (si aplica).

IGTF y cuadre de pagos ​

  • El IGTF (3 %) solo se aplica cuando hay un pago divisa y el negocio no es Contribuyente Ordinario. Se calcula como el 3 % del monto del pago en divisa, redondeado a 2 decimales.
  • Si aplica IGTF, se aceptan dos formas de cuadrar: que los pagos sumen el total sin IGTF (el servidor suma el IGTF automáticamente a la fila de divisa) o que sumen el total más el IGTF.
  • Si el negocio es Contribuyente Ordinario, los pagos deben sumar exactamente el total; si se incluyó el 3 %, el error lo indica: Este negocio es Contribuyente Ordinario: no aplica IGTF. ....
  • La comparación se hace al céntimo.

Duplicados ​

  • Si un numeroFactura ya fue emitido por su negocio, esa factura se omite y su número aparece en invoice_errors; las demás se emiten con normalidad.
  • Si el mismo numeroFactura aparece más de una vez en la solicitud, se omiten todas sus apariciones.
  • Reenviar exactamente la misma solicitud no duplica facturas: la segunda vez la respuesta es HTTP 409 con success: false y Error: facturas ya registradas.

Límite de líneas por factura ​

  • Además de los límites de cada renglón, puede existir un límite global de líneas por factura configurado por la plataforma. Cada renglón cuenta como el número de líneas de su descripción (mínimo 1) más las de su product_note, a razón de 50 caracteres por línea y una línea por cada salto de línea.

Otros comportamientos ​

  • Validación previa: todas las facturas se validan antes de emitir; si alguna tiene un error de validación, no se emite ninguna. La emisión del lote se hace en una única transacción.
  • Altas automáticas: los productos cuyo codigoProducto no existe y los clientes nuevos se registran en su catálogo durante el proceso. Las alícuotas de todo el lote se validan antes: si alguna falla, se responde 400 sin crear clientes ni productos. Para clientes existentes se actualizan nombre, correo, teléfono y dirección. Puede registrar productos y clientes por adelantado con Registrar productos y Registrar clientes.
  • Precio usado: la factura usa siempre el precioProducto enviado, no el precio guardado en el catálogo.
  • Factura a crédito: sin order_payment_methods, la factura se registra con forma de pago "Crédito" por el total.
  • Fecha de emisión: es la fecha del servidor en el momento de la llamada; no se puede enviar.
  • Número de control: se asigna automáticamente, de forma consecutiva, a cada factura emitida.

API de Facturación · CG Imprenta Digital