Apariencia
Retención de IVA
POST /api/Invoice/add_retention_iva
Emite uno o varios comprobantes de retención de IVA. Cada elemento de data corresponde a un proveedor (el "cliente" del comprobante) con hasta 3 líneas de retención. Por cada proveedor se asigna un número de control y un número de comprobante, y se devuelve el enlace al PDF.
Autenticación: Authorization: Bearer <token> (cómo obtenerlo) · Content-Type: application/json
Requisitos del negocio
El negocio del token debe estar habilitado para emitir retenciones de IVA según su configuración de contribuyente y de firma. Si no lo está, el API responde 400 con No puedes crear retenciones del impuesto valor agregado. antes de leer el cuerpo.
Cuerpo de la solicitud
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
data | array de objetos | Sí | Lista de comprobantes a emitir. Debe ser un arreglo JSON con al menos un elemento. |
data[]
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
cliente | array de objetos | Sí | Datos del proveedor al que se le retiene. Se usa solo el primer elemento (cliente[0]). |
RetencionIva | array de objetos | Sí | Líneas de retención (facturas o notas del proveedor). Máximo 3 por elemento de data. Respeta la R mayúscula. |
data[].cliente[]
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
documentoIdentidadCliente | string | Sí | RIF o cédula sin guiones: una letra (V, E, P, J, G o C) seguida de 8 a 10 dígitos. Ejemplo: J123456789. |
nombreRazonSocialCliente | string | Sí | Nombre o razón social. |
correoCliente | string | Sí | Correo electrónico válido. |
telefonoCliente | string | Sí | Debe contener exactamente 11 dígitos (se ignoran los caracteres que no son dígitos). Ejemplo: 04141234567. |
direccionCliente | string | Sí | Dirección fiscal. |
Si no existe un cliente con ese número de documento en el negocio, se crea automáticamente con estos datos. Si ya existe, se reutiliza tal cual (sus datos no se actualizan).
data[].RetencionIva[]
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
fechaDeFactura | string | Sí | Fecha del documento retenido, formato AAAA-MM-DD. Debe ser una fecha válida y no futura (hora de Caracas). |
numeroFactura | string | Sí | Número de la factura del proveedor. Máximo 20 caracteres. |
numeroControl | string | Sí | Número de control de la factura del proveedor. Máximo 20 caracteres. |
numeroNotaDeDebito | string | Sí | Número de la nota de débito, o N/A si no aplica. Si tiene valor, solo letras y números. |
numeroNotaDeCredito | string | Sí | Número de la nota de crédito, o N/A si no aplica. Si tiene valor, solo letras y números. |
numeroFacturaAfectada | string | Sí | Factura afectada por la nota, o N/A si la línea es una factura. Máximo 20 caracteres. Ver reglas de notas más abajo. |
totalDeCompraIncluyendoIva | string | Sí | Monto total de la compra con IVA. Formato numérico venezolano (ver más abajo). Debe ser mayor que baseImponible. |
compraSinDerechoACreditoFiscal | string | Sí | Monto de compras exentas o sin derecho a crédito fiscal (puede ser 0,00). Formato numérico venezolano. |
baseImponible | string | Sí | Base imponible sobre la que se calcula el IVA. Formato numérico venezolano. |
porcentaje_iva | string | Sí | Alícuota de IVA: 16.00%, 8.00% o 31.00%. También se acepta la clave porcentajeIva. |
porcentaje | string | Sí | Porcentaje de retención. Valores permitidos: 75% o 100%. |
Formato de los montos. Se envían como texto con coma decimal y, opcionalmente, punto como separador de miles, con hasta 2 decimales: 0,00, 150,5, 1.234,56, 1234,56, 1000. Límite: 15 dígitos enteros y 2 decimales. Ver Convenciones.
Reglas de notas de débito y crédito.
- Para una factura normal:
numeroNotaDeDebito,numeroNotaDeCreditoynumeroFacturaAfectadaenN/A. - Para una nota de débito o de crédito: indica el número en uno solo de los dos campos de nota (el otro en
N/A) y el número de la factura afectada ennumeroFacturaAfectada. - Si
numeroFacturaAfectadatiene un valor distinto deN/A, es obligatorio indicar exactamente una de las dos notas.
Cálculo que hace el API. IVA = baseImponible x alícuota (porcentaje_iva); IVA retenido = IVA x porcentaje. Ambos deben resultar mayores que 0. Estos valores no se envían: los calcula el API.
Ejemplo de solicitud
json
{
"data": [
{
"cliente": [
{
"documentoIdentidadCliente": "J123456789",
"nombreRazonSocialCliente": "Cliente Ejemplo C.A.",
"correoCliente": "proveedor@example.com",
"direccionCliente": "Av. Principal, Caracas",
"telefonoCliente": "04141234567"
}
],
"RetencionIva": [
{
"fechaDeFactura": "2026-07-10",
"numeroFactura": "000123",
"numeroControl": "00-0000123",
"numeroNotaDeDebito": "N/A",
"numeroNotaDeCredito": "N/A",
"numeroFacturaAfectada": "N/A",
"totalDeCompraIncluyendoIva": "1.160,00",
"compraSinDerechoACreditoFiscal": "0,00",
"baseImponible": "1.000,00",
"porcentaje_iva": "16.00%",
"porcentaje": "75%"
}
]
}
]
}Respuesta exitosa
HTTP 200
json
{
"success": true,
"Mensaje": "Retenciones guardadas con éxito.",
"message": "Retenciones guardadas con éxito.",
"controles_usados": ["00-00000070"],
"comprobantes": ["20260700000012"],
"pdf": [
["https://<servidor>/readonly/exportPdf/MTIzfDl8NXxDTElFTlRFIEVKRU1QTE8..."]
],
"alert": "La cantidad de número de control es baja: total usados: 70, total restantes: 30, Porcentaje usado: 70%, Porcentaje restante: 30%"
}| Clave | Descripción |
|---|---|
Mensaje | Texto fijo de confirmación. La respuesta exitosa no incluye la clave success. |
controles_usados | Números de control asignados, uno por comprobante emitido. |
comprobantes | Números de comprobante, uno por comprobante: período AAAAMM de asignación + correlativo de 8 dígitos (ej. 20260700000012). Guárdalo: lo necesitas para anular. |
pdf | Un arreglo por comprobante, cada uno con el enlace (o enlaces) al PDF. |
alert | Solo aparece cuando quedan pocos números de control disponibles. |
Errores
Todos los errores tienen la forma { "success": false, "message": "..." }. #N es la posición (empezando en 0) del elemento de data que falló.
| HTTP | Mensaje (ejemplo) | Causa |
|---|---|---|
| 401 / 400 | Ver Errores | Token ausente, mal formado, inválido o expirado. |
| 400 | No puedes crear retenciones del impuesto valor agregado. | El negocio no está habilitado para retenciones de IVA. |
| 400 | El cuerpo de la solicitud no es un JSON válido. | Cuerpo mal formado. |
| 400 | El campo "data" es obligatorio y debe ser un arreglo. | Falta data o está vacío. |
| 400 | El campo 'cliente' es obligatorio y debe ser un arreglo en el registro #0. | Falta cliente. |
| 400 | El campo 'RetencionIva' es obligatorio y debe ser un arreglo en el registro #0. | Falta RetencionIva (o se escribió con otra capitalización). |
| 400 | Máximo 3 retenciones por cliente. Usted envió 4 en el registro #0. | Más de 3 líneas en RetencionIva. |
| 400 | No se encontró el negocio asociado al usuario. | El token no corresponde a un negocio. |
| 400 | El cliente en el registro #0 es inválido o está incompleto. | cliente[0] sin documentoIdentidadCliente. |
| 400 | El campo Correo del Cliente es obligatorio. | Falta un dato del cliente (el texto cambia según el campo). |
| 400 | El formato del correo electrónico no es válido. | Correo inválido. |
| 400 | El número de teléfono debe tener exactamente 11 dígitos. | Teléfono con otra cantidad de dígitos. |
| 400 | El campo Documento de Identidad del Cliente debe tener el formato correcto (letra V, E, P, J, G o C seguida de 8 o 9 dígitos). Ejemplo: V12345678 | RIF/cédula mal formado. |
| 400 | El campo baseImponible debe venir en formato numérico válido: 0,00 - 00,00 - 000,00 - 0.000,00 - 000.000,00 - 000.000.000,00 (registro #0) | Monto con formato inválido. |
| 400 | El campo numeroFacturaAfectada es obligatorio cuando se especifica numeroNotaDeDebito (registro #0) | Nota de débito (o crédito) sin factura afectada. También ocurre si se omite el campo de nota en lugar de enviar N/A. |
| 400 | El campo porcentaje es obligatorio y debe ser uno de los valores permitidos (75%, 100%) (registro #0). | porcentaje ausente o no permitido. |
| 400 | El campo fechaDeFactura debe tener el formato correcto: AAAA-MM-DD (registro #0) | Fecha con otro formato. También: ...es obligatorio..., ...contiene una fecha inválida..., ...no puede ser una fecha futura.... |
| 400 | El campo numeroFactura es obligatorio y no debe superar los 20 caracteres (registro #0) | Igual para numeroFacturaAfectada. |
| 400 | El campo numeroControl no debe superar los 20 caracteres (registro #0) | Número de control demasiado largo. |
| 400 | El campo numeroControl es obligatorio. (registro #0) | Campo obligatorio vacío (el texto cambia según el campo). |
| 400 | Si numeroFacturaAfectada tiene valor, debes indicar número en numeroNotaDeCredito o numeroNotaDeDebito (solo uno). (registro #0) | Factura afectada sin nota. |
| 400 | Si numeroFacturaAfectada tiene valor, no puedes tener valores en numeroNotaDeCredito y numeroNotaDeDebito al mismo tiempo. (registro #0) | Ambas notas con valor. |
| 400 | El campo numeroNotaDeCredito solo debe contener letras o números, sin caracteres especiales. (registro #0) | Igual para numeroNotaDeDebito. |
| 400 | El campo totalDeCompraIncluyendoIva, compraSinDerechoACreditoFiscal y baseImponible tienen como límite de 15 enteros y 2 décimales. (registro #0) | Monto demasiado grande. |
| 400 | El impuesto de iva no debe estar dando menor ni igual a 0. valor actual 0.00 (registro #0) | La base imponible da un IVA de 0. Igual para El iva retenido no debe.... |
| 400 | El totalDeCompraIncluyendoIva no puede ser menor ni igual a la baseImponible. (registro #0) | El total no supera la base. |
| 400 | El campo porcentaje_iva es obligatorio y debe ser una alícuota válida (16.00%, 8.00% o 31.00%) (registro #0). | Falta la alícuota. Si viene con otro valor: El campo porcentaje_iva debe ser una alícuota válida (16.00%, 8.00% o 31.00%) (registro #0). |
| 400 | No hay número de control disponible. | El negocio agotó sus números de control. |
| 409 | El sistema está procesando otra retención de este negocio, intente nuevamente. | Hay otra emisión de retención de IVA del mismo negocio en curso. Reintenta. |
| 500 | Hubo un problema la intentar guardar las retenciones. | Error al guardar (también: No se pudo asignar el número de comprobante, intente nuevamente.). |
Notas
- Todo o nada. Las validaciones se hacen sobre todo el lote antes de guardar; si un registro falla, no se emite ningún comprobante. El guardado es transaccional.
- Un comprobante por proveedor. Las líneas de
RetencionIvade un mismo proveedor comparten número de control y número de comprobante. Si envías dos elementos dedatacon el mismo proveedor, quedan en un único comprobante. - Numeración. El correlativo del comprobante es propio del negocio y se asigna en el momento de la emisión; el período
AAAAMMes el de la fecha de asignación, no el defechaDeFactura. - No es idempotente. Reenviar la misma solicitud emite comprobantes nuevos y consume nuevos números de control.
- Campos de nota. Envía siempre
numeroNotaDeDebitoynumeroNotaDeCredito(conN/Asi no aplican); omitirlos produce un error de validación. - Claves desconocidas. Los campos que no figuran en las tablas se ignoran sin error.
- Para consultar lo emitido usa Consultar retenciones de IVA; para anular, Anular retención.
