Skip to content

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 ​

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]).
RetencionIvaarray de objetosSíLíneas de retención (facturas o notas del proveedor). Máximo 3 por elemento de data. Respeta la R mayúscula.

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.
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[].RetencionIva[] ​

CampoTipoObligatorioDescripción y reglas
fechaDeFacturastringSíFecha del documento retenido, formato AAAA-MM-DD. Debe ser una fecha válida y no futura (hora de Caracas).
numeroFacturastringSíNúmero de la factura del proveedor. Máximo 20 caracteres.
numeroControlstringSíNúmero de control de la factura del proveedor. Máximo 20 caracteres.
numeroNotaDeDebitostringSíNúmero de la nota de débito, o N/A si no aplica. Si tiene valor, solo letras y números.
numeroNotaDeCreditostringSíNúmero de la nota de crédito, o N/A si no aplica. Si tiene valor, solo letras y números.
numeroFacturaAfectadastringSí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.
totalDeCompraIncluyendoIvastringSíMonto total de la compra con IVA. Formato numérico venezolano (ver más abajo). Debe ser mayor que baseImponible.
compraSinDerechoACreditoFiscalstringSíMonto de compras exentas o sin derecho a crédito fiscal (puede ser 0,00). Formato numérico venezolano.
baseImponiblestringSíBase imponible sobre la que se calcula el IVA. Formato numérico venezolano.
porcentaje_ivastringSíAlícuota de IVA: 16.00%, 8.00% o 31.00%. También se acepta la clave porcentajeIva.
porcentajestringSí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, numeroNotaDeCredito y numeroFacturaAfectada en N/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 en numeroFacturaAfectada.
  • Si numeroFacturaAfectada tiene un valor distinto de N/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%"
}
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, uno por comprobante: período AAAAMM de asignación + correlativo de 8 dígitos (ej. 20260700000012). 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 retenciones de IVA.
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 'cliente' es obligatorio y debe ser un arreglo en el registro #0.Falta cliente.
400El campo 'RetencionIva' es obligatorio y debe ser un arreglo en el registro #0.Falta RetencionIva (o se escribió con otra capitalización).
400Máximo 3 retenciones por cliente. Usted envió 4 en el registro #0.Más de 3 líneas en RetencionIva.
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 Correo 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 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.
400El 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.
400El campo porcentaje es obligatorio y debe ser uno de los valores permitidos (75%, 100%) (registro #0).porcentaje ausente o no permitido.
400El 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....
400El campo numeroFactura es obligatorio y no debe superar los 20 caracteres (registro #0)Igual para numeroFacturaAfectada.
400El campo numeroControl no debe superar los 20 caracteres (registro #0)Número de control demasiado largo.
400El campo numeroControl es obligatorio. (registro #0)Campo obligatorio vacío (el texto cambia según el campo).
400Si numeroFacturaAfectada tiene valor, debes indicar número en numeroNotaDeCredito o numeroNotaDeDebito (solo uno). (registro #0)Factura afectada sin nota.
400Si numeroFacturaAfectada tiene valor, no puedes tener valores en numeroNotaDeCredito y numeroNotaDeDebito al mismo tiempo. (registro #0)Ambas notas con valor.
400El campo numeroNotaDeCredito solo debe contener letras o números, sin caracteres especiales. (registro #0)Igual para numeroNotaDeDebito.
400El campo totalDeCompraIncluyendoIva, compraSinDerechoACreditoFiscal y baseImponible tienen como límite de 15 enteros y 2 décimales. (registro #0)Monto demasiado grande.
400El 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....
400El totalDeCompraIncluyendoIva no puede ser menor ni igual a la baseImponible. (registro #0)El total no supera la base.
400El 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).
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 IVA 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 RetencionIva de un mismo proveedor comparten número de control y número de comprobante. Si envías dos elementos de data con 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 AAAAMM es el de la fecha de asignación, no el de fechaDeFactura.
  • No es idempotente. Reenviar la misma solicitud emite comprobantes nuevos y consume nuevos números de control.
  • Campos de nota. Envía siempre numeroNotaDeDebito y numeroNotaDeCredito (con N/A si 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.

API de Facturación · CG Imprenta Digital