Skip to content

Factura a terceros ​

POST /api/Invoice/add_list_invoice_third_party

Emite facturas de venta por cuenta de terceros: cada factura debe tener al menos un producto vendido a cuenta de un tercero (identificado con rifTercero y nombreRifTercero) y puede combinarlo con productos propios. Devuelve el número de control asignado y el enlace al PDF de terceros de cada factura. El negocio debe tener activada la facturación a terceros.

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

Cuerpo de la solicitud ​

La estructura es la misma que la de Agregar factura; a continuación se detallan los campos y las diferencias respecto a ese endpoint.

CampoTipoObligatorioDescripción y reglas
numeroSeriestringSíSerie de numeración del negocio (por ejemplo "A").
cantidadFacturaintegerSíDebe coincidir exactamente con la cantidad de elementos de facturas.
facturasarraySíLista de facturas a terceros. No puede estar vacía.

facturas[] ​

CampoTipoObligatorioDescripción y reglas
numeroFacturastringSíSolo dígitos, máximo 19 caracteres. No puede estar repetido (ver Notas).
descripcionFacturastringNoMáximo 500 caracteres. No se admite si hay mensaje fijo activo.
fixed_messagestringNoMensaje fijo / coletilla (alias mensajeFijo). Si el negocio tiene uno configurado, prevalece el del negocio.
documentoIdentidadClientestringSí (salvo exportación)Letra V, E, P, J, G o C + 8 a 10 dígitos (ej. J123456789).
nombreRazonSocialClientestringSíNombre o razón social del cliente.
correoClientestringSíCorreo del cliente (se normaliza a minúsculas y se limpian caracteres no permitidos).
direccionClientestringSíDirección del cliente.
telefonoClientestringSíTeléfono del cliente.
is_client_exportintegerNo1 para cliente de exportación (alias es_cliente_export); todos los productos deben llevar alícuota X.
tasa_del_diastringNoTasa de cambio (alias exchange_rate). A diferencia de Agregar factura, aquí es opcional y no se valida su formato: si se omite se usa la tasa registrada en el negocio.
fecha_tasastringNoFecha de la tasa (alias current_exchange, fecha_tasa_de_cambio). Si se omite se usa la fecha del día. Envíela en formato YYYY-MM-DD: en este endpoint no se convierte el formato DD-MM-YYYY.
product_currencyintegerNo1 para mostrar equivalentes en USD (requiere dualidad de moneda y moneda en productos activas en el negocio).
dualidad_de_monedaintegerNo0 o 1; 0 desactiva la dualidad solo para esta factura.
mostrar_formas_de_pagointegerNo0 (por defecto) o 1 para mostrar el bloque "Formas de Pago" en el PDF.
productosarraySíVer productos[].
order_payment_methodsarrayNoVer order_payment_methods[]. Si se omite, la factura queda a crédito.

productos[] ​

CampoTipoObligatorioDescripción y reglas
codigoProductostringSíMáximo 13 caracteres, sin espacios. Si no existe se registra automáticamente (con los datos del tercero, si los trae).
nombreProductostringSíMáximo 70 caracteres (más estricto que en Agregar factura).
descripcionProductostringSíDescripción del renglón.
product_notestringNoComentario del renglón. Descripción + comentario: máximo 450 caracteres y 9 líneas de 50 caracteres.
tipoImpuestostringSíG (16 %), R (8 %), A (31 %), E (exento), P (percibido, 0 %) o X (solo exportación). Si el producto ya existe debe coincidir con su alícuota registrada.
cantidadAdquiridastring | numberSíMayor que cero; decimales con punto.
precioProductostring | numberSíPrecio unitario en Bs sin IVA; mayor que cero, máximo 9 enteros y 2 decimales (punto o coma).
discountnumber | stringNoDescuento en porcentaje, de 0 a menos de 100.
rifTercerostringCondicionalRIF del tercero: letra V, E, P, J, G o C + 8 a 10 dígitos. Si se envía, nombreRifTercero es obligatorio.
nombreRifTercerostringCondicionalRazón social del tercero, máximo 70 caracteres. Si se envía, rifTercero es obligatorio.

Reglas de la factura:

  • Al menos 1 producto debe ser de un tercero (con rifTercero y nombreRifTercero). Los productos sin esos campos se consideran propios.
  • Máximo 8 productos en total (propios + de terceros).

order_payment_methods[] ​

CampoTipoObligatorioDescripción y reglas
order_payment_methodstringSíefectivo, transferencia o pago movil. Máximo 20 caracteres (si se excede, el documento se rechaza). divisa no está permitido en facturas a terceros. 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 en Bs, hasta 9 enteros y exactamente 2 decimales ("17400.00").
bancostringPara transferencia y pago movilNombre del banco según Bancos.
numero_de_referencia_de_operacionstringPara transferencia y pago movilExactamente 4 dígitos.
telefono_pago_movilstringPara pago movil11 dígitos (ej. "04141234567").
notestringNoNota libre del pago.
igtf—No permitidoEnviar un igtf mayor que cero produce error: las facturas a terceros no llevan IGTF.
  • Máximo 5 formas de pago.
  • La suma de los monto debe ser exactamente igual al total de la factura (ni menor ni mayor).

Ejemplo de solicitud ​

json
{
  "numeroSerie": "A",
  "cantidadFactura": 1,
  "facturas": [
    {
      "numeroFactura": "001083",
      "descripcionFactura": "Factura mixta (cuenta propia y cuenta de terceros)",
      "tasa_del_dia": "342.8633",
      "fecha_tasa": "2026-10-09",
      "documentoIdentidadCliente": "J123456789",
      "nombreRazonSocialCliente": "Cliente Ejemplo C.A.",
      "correoCliente": "cliente@example.com",
      "direccionCliente": "Av. Principal, Caracas",
      "telefonoCliente": "04141234567",
      "productos": [
        {
          "codigoProducto": "PROD-002",
          "nombreProducto": "Mercancía de tercero",
          "descripcionProducto": "Venta a cuenta de tercero",
          "tipoImpuesto": "G",
          "cantidadAdquirida": "100",
          "precioProducto": "150.00",
          "rifTercero": "J987654321",
          "nombreRifTercero": "Tercero Ejemplo C.A."
        },
        {
          "codigoProducto": "FEE-001",
          "nombreProducto": "Comisión de servicio",
          "descripcionProducto": "Comisión por intermediación",
          "tipoImpuesto": "G",
          "cantidadAdquirida": "1",
          "precioProducto": "500.00"
        }
      ],
      "order_payment_methods": [
        {
          "order_payment_method": "transferencia",
          "monto": "17980.00",
          "banco": "Banco de Venezuela",
          "numero_de_referencia_de_operacion": "1234"
        }
      ]
    }
  ]
}

Respuesta exitosa ​

HTTP 200

json
{
  "success": true,
  "message": "Facturas guardadas satisfactoriamente.",
  "invoice_errors": [],
  "invoice_list_success": [
    {
      "invoice_number": "001083",
      "control_number": "00-00000057",
      "invoice_pdf": "https://<su-dominio>/readonly/export_pdf_tercero/3c59dc04-8e88-4024-abe8-079a5c74d079"
    }
  ]
}
ClaveDescripción
successtrue si se emitió al menos una factura. Si todas estaban registradas: false con HTTP 409.
messageFacturas guardadas satisfactoriamente., Las facturas se guardaron correctamente, pero algunas estaban duplicadas y no pudieron guardarse. o Error: facturas ya registradas. (todas duplicadas; success sigue en true).
invoice_errorsNúmeros de factura omitidos por duplicados.
invoice_list_successPor cada factura emitida: invoice_number, control_number y invoice_pdf (siempre el PDF de terceros).
warning_control_numbersSolo si quedan pocos números de control disponibles.

Errores ​

Los errores de validación se acumulan en un único message, separados por un espacio. Además de los errores de validación de campos descritos en Agregar factura (número de factura, cliente, productos, descuento, pagos, bancos, alícuotas), este endpoint tiene los siguientes:

HTTPMensaje (ejemplo)Causa
400 / 401—Token ausente, mal formado, inválido o expirado. Ver Errores.
400El campo Número de Serie es obligatorio.Falta numeroSerie (igual para Cantidad de Facturas).
400La opción de facturación a terceros no está activada para este negocio.El negocio no tiene habilitada la facturación a terceros.
400El campo Facturas es obligatorio y no debe estar vacío.Falta facturas.
400El campo Productos en la factura a terceros 001083 es obligatorio y no debe estar vacío.Falta productos.
400El campo Nombre del Producto en el producto 1 de la factura 001083 no puede exceder los 70 caracteres.Nombre de producto demasiado largo.
400En la factura a terceros 001083 debe haber al menos 1 producto a cuenta de un tercero (con rifTercero y nombreRifTercero). Cantidad actual de productos a terceros: 0.Ningún producto trae datos de tercero.
400En la factura 001083, si se asigna Facturación a Terceros en el producto 1 debes enviar ambos campos: rifTercero y nombreRifTercero.Datos de tercero incompletos.
400El campo rifTercero del producto 1 en la factura 001083 debe comenzar con V, E, P, J, G o C seguido de 5 a 10 dígitos.RIF del tercero inválido (en la práctica se exigen 8 a 10 dígitos).
400La factura a terceros 001083 excede el límite de 8 productos en total. Cantidad recibida: 9 (5 propios + 4 terceros).Más de 8 productos.
400El método de pago divisa no está permitido para facturas a terceros, en la factura N° 001083.Se envió un pago divisa.
400No está permitido registrar el campo IGTF en facturas a terceros en la factura 001083.Se envió igtf mayor que cero.
400El monto total registrado en los métodos de pago (17000.00) es menor al total calculado de la factura (17980.00) en la factura N° 001083. Si registra métodos de pago, el monto debe cubrir el total de la factura. 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.
400El monto total registrado en los métodos de pago (18000.00) no puede sobrepasar el total calculado de la factura (17980.00) en la factura N° 001083.Los pagos superan el total.
400La cantidad de facturas no coincide con las enviadas en el payload.cantidadFactura distinto del número de elementos de facturas.
404El negocio no se encuentra registrado en el sistema.El negocio del token no está registrado.
409El comercio no Posee más números de control activos.Números de control agotados.
500Error Guardando las Facturas, Intente Mas Tarde.Falló el guardado; no se emitió ninguna factura del lote.

Notas ​

  • Diferencias con Agregar factura: la tasa y su fecha son opcionales; nombreProducto admite 70 caracteres (no 400); se exige al menos un producto de tercero; no se admite divisa ni IGTF; los pagos deben sumar exactamente el total; no se aplican la verificación de productos repetidos ni el límite global de líneas por factura; lote y fechaVencimiento no se usan.
  • Totales: base = precio × cantidad − descuento (%); IVA por alícuota sobre la suma de bases (G 16 %, R 8 %, A 31 %), redondeado a 2 decimales.
  • Pagos: solo el primer elemento de order_payment_methods se valida en detalle (banco, referencia, teléfono); los demás solo cuentan para el cuadre del total. Envíe todos los datos completos en cada forma de pago.
  • Duplicados: un numeroFactura ya emitido por su negocio, o repetido dentro de la misma solicitud, se omite y aparece en invoice_errors.
  • Crédito: sin formas de pago, la factura queda registrada a crédito por el total.
  • Altas automáticas: clientes y productos inexistentes se registran durante el proceso (después de validar las alícuotas de todo el lote: si alguna falla no se crea nada); los clientes existentes se actualizan con los datos enviados.
  • Cuerpo vacío: si el cuerpo llega vacío o no es JSON válido, responde 400 con El cuerpo de la solicitud está vacío o no es un JSON válido.

API de Facturación · CG Imprenta Digital