Skip to content

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 ​

CampoTipoObligatorioDescripción y reglas
dataarray de objetosSíLista de comprobantes a emitir. Debe ser un arreglo JSON con al menos un elemento.

data[] ​

CampoTipoObligatorioDescripción y reglas
clientearray de objetosSíDatos del proveedor al que se le retiene. Se usa solo el primer elemento (cliente[0]).
retencionIslrarray de objetosSíLíneas de retención. Máximo 3 por elemento de data. Respeta la r minúscula inicial.

data[].cliente[] ​

CampoTipoObligatorioDescripción y reglas
documentoIdentidadClientestringSí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).
nombreRazonSocialClientestringSíNombre o razón social.
correoClientestringSíCorreo electrónico válido.
telefonoClientestringSíDebe contener exactamente 11 dígitos (se ignoran los caracteres que no son dígitos). Ejemplo: 04141234567.
direccionClientestringSí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[] ​

CampoTipoObligatorioDescripción y reglas
numeroDocumentostringSíNúmero de la factura o documento del proveedor. Máximo 20 caracteres.
numeroControlstringSíNúmero de control del documento del proveedor. Máximo 20 caracteres.
fechastringSíFecha del documento, formato AAAA-MM-DD. Debe ser una fecha válida.
codigostringSí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).
conceptoPagostringSíDescripción del concepto pagado.
codigoRetencionIslrstringSíCódigo de concepto de retención ISLR (p. ej. 004). Consulta la lista en Códigos de concepto ISLR.
porcentajestringSí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).
montoDocumentostringSí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).
baseRetencionstringSíBase de la retención. Mismo formato. No puede ser mayor que montoDocumento.
montoRetenidostringSíMonto retenido. Mismo formato. Debe ser mayor que 0. Lo calcula el integrador: el API no lo recalcula.
sustraendostringCondicionalMismo 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%"
}
ClaveDescripción
MensajeTexto fijo de confirmación. La respuesta exitosa no incluye la clave success.
controles_usadosNúmeros de control asignados, uno por comprobante emitido.
comprobantesNúmeros de comprobante: período AAAAMM de asignación + correlativo de 8 dígitos. Guárdalo: lo necesitas para anular.
pdfUn arreglo por comprobante, cada uno con el enlace (o enlaces) al PDF.
alertSolo 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ó.

HTTPMensaje (ejemplo)Causa
401 / 400Ver ErroresToken ausente, mal formado, inválido o expirado.
400No puedes crear retenciones del impuesto valor agregado.El negocio no está habilitado para emitir retenciones.
400El cuerpo de la solicitud no es un JSON válido.Cuerpo mal formado.
400El campo "data" es obligatorio y debe ser un arreglo.Falta data o está vacío.
400El campo 'retencionIslr' es obligatorio y debe ser un arreglo en el registro #0.Falta retencionIslr (o tiene otra capitalización). Igual para 'cliente'.
400Máximo 3 retenciones por cliente. Usted envió 4 en el registro #0.Más de 3 líneas en retencionIslr.
400No se encontró el negocio asociado al usuario.El token no corresponde a un negocio.
400El cliente en el registro #0 es inválido o está incompleto.cliente[0] sin documentoIdentidadCliente.
400El campo Teléfono del Cliente es obligatorio.Falta un dato del cliente (el texto cambia según el campo).
400El formato del correo electrónico no es válido.Correo inválido.
400El número de teléfono debe tener exactamente 11 dígitos.Teléfono con otra cantidad de dígitos.
400El 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: V12345678RIF/cédula mal formado.
400El 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).
400El 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....
400El campo porcentaje debe contener solo un símbolo '%' y debe estar al final (registro #0).porcentaje ausente o mal escrito.
400El porcentaje 7% no existe en el sistema. (registro #0)Porcentaje desconocido.
400El código 999 no existe en el sistema. (registro #0)codigoRetencionIslr desconocido o ausente.
400El 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.
400El campo numeroDocumento no debe superar los 20 caracteres (registro #0)Igual para numeroControl.
400El campo conceptoPago es obligatorio. (registro #0)Campo obligatorio vacío (el texto cambia según el campo).
400El 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).
400El montoRetenido no debe estar dando menor ni igual a 0. valor actual 0.00 (registro #0)Monto retenido en cero.
400La baseRetencion no puede ser mayor al montoDocumento (registro #0)Base mayor que el documento.
400El campo sustraendo no puede ser 0 ni estar vacío para proveedores de tipo Persona Natural. (registro #0)Proveedor V/E sin sustraendo.
400El 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.
400No hay número de control disponible.El negocio agotó sus números de control.
409El 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.
500Hubo 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; porcentaje igual debe tener el formato N%.
  • Montos. A diferencia de la retención de IVA, aquí los montos deben llevar exactamente 2 decimales (500,00, no 500 ni 500,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.

API de Facturación · CG Imprenta Digital