Apariencia
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.
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
numeroSerie | string | Sí | Serie de numeración del negocio (por ejemplo "A"). |
cantidadFactura | integer | Sí | Debe coincidir exactamente con la cantidad de elementos de facturas. |
facturas | array | Sí | Lista de facturas a terceros. No puede estar vacía. |
facturas[]
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
numeroFactura | string | Sí | Solo dígitos, máximo 19 caracteres. No puede estar repetido (ver Notas). |
descripcionFactura | string | No | Máximo 500 caracteres. No se admite si hay mensaje fijo activo. |
fixed_message | string | No | Mensaje fijo / coletilla (alias mensajeFijo). Si el negocio tiene uno configurado, prevalece el del negocio. |
documentoIdentidadCliente | string | Sí (salvo exportación) | Letra V, E, P, J, G o C + 8 a 10 dígitos (ej. J123456789). |
nombreRazonSocialCliente | string | Sí | Nombre o razón social del cliente. |
correoCliente | string | Sí | Correo del cliente (se normaliza a minúsculas y se limpian caracteres no permitidos). |
direccionCliente | string | Sí | Dirección del cliente. |
telefonoCliente | string | Sí | Teléfono del cliente. |
is_client_export | integer | No | 1 para cliente de exportación (alias es_cliente_export); todos los productos deben llevar alícuota X. |
tasa_del_dia | string | No | Tasa 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_tasa | string | No | Fecha 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_currency | integer | No | 1 para mostrar equivalentes en USD (requiere dualidad de moneda y moneda en productos activas en el negocio). |
dualidad_de_moneda | integer | No | 0 o 1; 0 desactiva la dualidad solo para esta factura. |
mostrar_formas_de_pago | integer | No | 0 (por defecto) o 1 para mostrar el bloque "Formas de Pago" en el PDF. |
productos | array | Sí | Ver productos[]. |
order_payment_methods | array | No | Ver order_payment_methods[]. Si se omite, la factura queda a crédito. |
productos[]
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
codigoProducto | string | Sí | Máximo 13 caracteres, sin espacios. Si no existe se registra automáticamente (con los datos del tercero, si los trae). |
nombreProducto | string | Sí | Máximo 70 caracteres (más estricto que en Agregar factura). |
descripcionProducto | string | Sí | Descripción del renglón. |
product_note | string | No | Comentario del renglón. Descripción + comentario: máximo 450 caracteres y 9 líneas de 50 caracteres. |
tipoImpuesto | string | Sí | 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. |
cantidadAdquirida | string | number | Sí | Mayor que cero; decimales con punto. |
precioProducto | string | number | Sí | Precio unitario en Bs sin IVA; mayor que cero, máximo 9 enteros y 2 decimales (punto o coma). |
discount | number | string | No | Descuento en porcentaje, de 0 a menos de 100. |
rifTercero | string | Condicional | RIF del tercero: letra V, E, P, J, G o C + 8 a 10 dígitos. Si se envía, nombreRifTercero es obligatorio. |
nombreRifTercero | string | Condicional | Razó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
rifTerceroynombreRifTercero). Los productos sin esos campos se consideran propios. - Máximo 8 productos en total (propios + de terceros).
order_payment_methods[]
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
order_payment_method | string | Sí | 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. |
monto | string | Sí | Monto en Bs, hasta 9 enteros y exactamente 2 decimales ("17400.00"). |
banco | string | Para transferencia y pago movil | Nombre del banco según Bancos. |
numero_de_referencia_de_operacion | string | Para transferencia y pago movil | Exactamente 4 dígitos. |
telefono_pago_movil | string | Para pago movil | 11 dígitos (ej. "04141234567"). |
note | string | No | Nota libre del pago. |
igtf | — | No permitido | Enviar un igtf mayor que cero produce error: las facturas a terceros no llevan IGTF. |
- Máximo 5 formas de pago.
- La suma de los
montodebe 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"
}
]
}| Clave | Descripción |
|---|---|
success | true si se emitió al menos una factura. Si todas estaban registradas: false con HTTP 409. |
message | Facturas 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_errors | Números de factura omitidos por duplicados. |
invoice_list_success | Por cada factura emitida: invoice_number, control_number y invoice_pdf (siempre el PDF de terceros). |
warning_control_numbers | Solo 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:
| HTTP | Mensaje (ejemplo) | Causa |
|---|---|---|
| 400 / 401 | — | Token ausente, mal formado, inválido o expirado. Ver Errores. |
| 400 | El campo Número de Serie es obligatorio. | Falta numeroSerie (igual para Cantidad de Facturas). |
| 400 | La opción de facturación a terceros no está activada para este negocio. | El negocio no tiene habilitada la facturación a terceros. |
| 400 | El campo Facturas es obligatorio y no debe estar vacío. | Falta facturas. |
| 400 | El campo Productos en la factura a terceros 001083 es obligatorio y no debe estar vacío. | Falta productos. |
| 400 | El campo Nombre del Producto en el producto 1 de la factura 001083 no puede exceder los 70 caracteres. | Nombre de producto demasiado largo. |
| 400 | En 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. |
| 400 | En 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. |
| 400 | El 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). |
| 400 | La 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. |
| 400 | El método de pago divisa no está permitido para facturas a terceros, en la factura N° 001083. | Se envió un pago divisa. |
| 400 | No está permitido registrar el campo IGTF en facturas a terceros en la factura 001083. | Se envió igtf mayor que cero. |
| 400 | El 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. |
| 400 | El 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. |
| 400 | La cantidad de facturas no coincide con las enviadas en el payload. | cantidadFactura distinto del número de elementos de facturas. |
| 404 | El negocio no se encuentra registrado en el sistema. | El negocio del token no está registrado. |
| 409 | El comercio no Posee más números de control activos. | Números de control agotados. |
| 500 | Error 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;
nombreProductoadmite 70 caracteres (no 400); se exige al menos un producto de tercero; no se admitedivisani 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;loteyfechaVencimientono 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_methodsse 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
numeroFacturaya emitido por su negocio, o repetido dentro de la misma solicitud, se omite y aparece eninvoice_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
400conEl cuerpo de la solicitud está vacío o no es un JSON válido.
