Apariencia
Retención de ISLR
POST /api/Invoice/add_retention_islr
Emite uno o varios comprobantes de retención de ISLR (impuesto sobre la renta). Cada elemento de data corresponde a un proveedor 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 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. (el texto menciona IVA aunque se trate de ISLR).
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]). |
retencionIslr | array de objetos | Sí | Líneas de retención. Máximo 3 por elemento de data. Respeta la r minúscula inicial. |
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. La letra V o E indica persona natural (afecta a sustraendo). |
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[].retencionIslr[]
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
numeroDocumento | string | Sí | Número de la factura o documento del proveedor. Máximo 20 caracteres. |
numeroControl | string | Sí | Número de control del documento del proveedor. Máximo 20 caracteres. |
fecha | string | Sí | Fecha del documento, formato AAAA-MM-DD. Debe ser una fecha válida. |
codigo | string | Sí | Código de referencia de la línea. Obligatorio; según el código actual su contenido no se valida contra ningún catálogo (en los ejemplos suele repetirse el código de concepto). |
conceptoPago | string | Sí | Descripción del concepto pagado. |
codigoRetencionIslr | string | Sí | Código de concepto de retención ISLR (p. ej. 004). Consulta la lista en Códigos de concepto ISLR. |
porcentaje | string | Sí | Porcentaje de retención con un único % al final (p. ej. 5%, 4.95%). Debe existir en el sistema y ser válido para el codigoRetencionIslr indicado (salvo para el código 001, ver Notas). |
montoDocumento | string | Sí | Monto del documento. Formato: coma decimal con exactamente 2 decimales, máximo 9 dígitos enteros, punto de miles opcional (10000,00 o 10.000,00). |
baseRetencion | string | Sí | Base de la retención. Mismo formato. No puede ser mayor que montoDocumento. |
montoRetenido | string | Sí | Monto retenido. Mismo formato. Debe ser mayor que 0. Lo calcula el integrador: el API no lo recalcula. |
sustraendo | string | Condicional | Mismo formato. Obligatorio y mayor que 0 si el proveedor es persona natural (V o E); para cualquier otro tipo de documento debe omitirse o ser 0,00. |
Ejemplo de solicitud
json
{
"data": [
{
"cliente": [
{
"documentoIdentidadCliente": "J123456789",
"nombreRazonSocialCliente": "Cliente Ejemplo C.A.",
"correoCliente": "proveedor@example.com",
"direccionCliente": "Av. Principal, Caracas",
"telefonoCliente": "04141234567"
}
],
"retencionIslr": [
{
"numeroDocumento": "000456",
"numeroControl": "00-0000456",
"fecha": "2026-07-10",
"codigo": "004",
"conceptoPago": "Honorarios profesionales",
"codigoRetencionIslr": "004",
"porcentaje": "5%",
"montoDocumento": "10.000,00",
"baseRetencion": "10.000,00",
"montoRetenido": "500,00"
}
]
}
]
}Para un proveedor persona natural (por ejemplo V12345678) agrega "sustraendo": "..." con un valor mayor que 0,00.
Respuesta exitosa
HTTP 200
json
{
"success": true,
"Mensaje": "Retenciones guardadas con éxito.",
"message": "Retenciones guardadas con éxito.",
"controles_usados": ["00-00000069"],
"comprobantes": ["20260700000005"],
"pdf": [
["https://<servidor>/readonly/exportPdf/NjR8OHw1fENMSUVOVEUgRUpFTVBMTy..."]
],
"alert": "La cantidad de número de control es baja: total usados: 69, total restantes: 31, Porcentaje usado: 69%, Porcentaje restante: 31%"
}| 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: período AAAAMM de asignación + correlativo de 8 dígitos. 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 emitir retenciones. |
| 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 'retencionIslr' es obligatorio y debe ser un arreglo en el registro #0. | Falta retencionIslr (o tiene otra capitalización). Igual para 'cliente'. |
| 400 | Máximo 3 retenciones por cliente. Usted envió 4 en el registro #0. | Más de 3 líneas en retencionIslr. |
| 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 Teléfono 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 montoDocumento 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 ausente o con formato inválido (igual para baseRetencion y montoRetenido). |
| 400 | El campo fecha es obligatorio y debe ser una fecha válida. FORMATO AAAA-MM-DD (registro #0) | También: El campo fecha debe tener el formato correcto: AAAA-MM-DD..., El campo fecha contiene una fecha inválida.... |
| 400 | El campo porcentaje debe contener solo un símbolo '%' y debe estar al final (registro #0). | porcentaje ausente o mal escrito. |
| 400 | El porcentaje 7% no existe en el sistema. (registro #0) | Porcentaje desconocido. |
| 400 | El código 999 no existe en el sistema. (registro #0) | codigoRetencionIslr desconocido o ausente. |
| 400 | El porcentaje 3% no es válido para el código 004. Por favor consulte documentación. (registro #0) | Combinación código/porcentaje no permitida. |
| 400 | El campo numeroDocumento no debe superar los 20 caracteres (registro #0) | Igual para numeroControl. |
| 400 | El campo conceptoPago es obligatorio. (registro #0) | Campo obligatorio vacío (el texto cambia según el campo). |
| 400 | El campo montoRetenido debe tener máximo 9 dígitos enteros y exactamente 2 decimales (ej: 1.234.567,89) (registro #0) | Monto sin 2 decimales exactos o demasiado grande (también para sustraendo). |
| 400 | El montoRetenido no debe estar dando menor ni igual a 0. valor actual 0.00 (registro #0) | Monto retenido en cero. |
| 400 | La baseRetencion no puede ser mayor al montoDocumento (registro #0) | Base mayor que el documento. |
| 400 | El campo sustraendo no puede ser 0 ni estar vacío para proveedores de tipo Persona Natural. (registro #0) | Proveedor V/E sin sustraendo. |
| 400 | El campo sustraendo no aplica (debe ser 0 o vacío) para proveedores que no sean Persona Natural. (registro #0) | Proveedor jurídico (u otro) con sustraendo. |
| 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 ISLR 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 un mismo proveedor comparten número de control y número de comprobante.
- Código
001(Sueldos y Salarios). Con este código no se valida la combinación código/porcentaje;porcentajeigual debe tener el formatoN%. - Montos. A diferencia de la retención de IVA, aquí los montos deben llevar exactamente 2 decimales (
500,00, no500ni500,5). - Fecha. A diferencia de IVA, el código actual no rechaza fechas futuras en
fecha. - No es idempotente. Reenviar la misma solicitud emite comprobantes nuevos y consume nuevos números de control.
- Claves desconocidas. Los campos que no figuran en las tablas se ignoran sin error.
- Para consultar lo emitido usa Consultar retenciones de ISLR; para anular, Anular retención.
