Retention (Comprobante de Retención) Examples - Type `07`

This document provides comprehensive examples of withholding tax certificates for different scenarios.

Retention Types
Example 1: Retención de IVA
Example 2: Retención de Impuesto a la Renta
Example 3: Retención Mixta (IVA + IR)
Example 4: Retención por Servicios Profesionales
Example 5: Retención Múltiple en un Período
Tipos de Documentos Soportados
Tax Códigos Reference
Common Errors and Solutions

Retention Types

Tax Retention Códigos (`codigo`)

Retention Percentage Códigos (`codigoRetencion`)

For Impuesto a la Renta (codigo: 1):

For IVA (codigo: 2):

Código	Descripción	Common Percentage
------	-------------	-------------------
`1`	Impuesto a la Renta (IR)	1%, 2%, 8%, 10%, 25%
`2`	IVA	30%, 70%, 100%
Código	Descripción	Percentage
------	-------------	-------------
`1`	1%	1.0%
`2`	2%	2.0%
`331`	8%	8.0%
`332`	10%	10.0%
`333`	25%	25.0%
Código	Descripción	Percentage
------	-------------	-------------
`1`	30%	30.0%
`2`	70%	70.0%
`3`	100%	100.0%

Fiscal Period (`periodoFiscal`)

Format: MM/YYYY (e.g., 12/2025)

Example 1: Retención de IVA

Scenario: Company with 30% IVA retention for supplier services

{
  "ruc": "0707012605001",
  "tipo": "07",
  "id_externo": "RET-2025-001",
  "retencion": {
    "fecha": "07/12/2025",
    "establecimiento": "001",
    "puntoEmision": "001",
    "secuencial": "000000123",
    "periodoFiscal": "12/2025",
    "sujetoRetenido": {
      "tipoIdentificacion": "04",
      "documento": "1791234567001",
      "nombre": "PROVEEDOR DE SERVICIOS S.A.",
      "direccion": "Av. Industrial #789"
    },
    "total": 30.00
  },
  "detalles": [
    {
      "codigo": "2",
      "codigoRetencion": "1",
      "baseImponible": 100.00,
      "porcentajeRetener": 30.0,
      "valorRetenido": 30.00,
      "codDocSustento": "01",
      "numDocSustento": "001-001-000001234",
      "fechaEmisionSustento": "01/12/2025"
    }
  ],
  "notificaciones": {
    "email": "[email protected]",
    "webhook_url": "https://proveedor.com/webhooks/retentions"
  }
}

Expected Response

{
  "status": "ok",
  "code": 200,
  "message": "Register the document successfully",
  "data": {
    "id": 1,
    "company_id": 1,
    "external_id": "RET-2025-001",
    "document_type": "07",
    "access_key": "0712202507070701260050010010000001231234567890",
    "series": "001001",
    "sequential": "000000123",
    "status": "GENERATED",
    "issue_date": "2025-12-07",
    "document_status": "PENDIENTE",
    "notification_email": "[email protected]",
    "webhook_url": "https://proveedor.com/webhooks/retentions",
    "created_at": "2025-12-07T12:00:00.000000Z"
  }
}

Example 2: Retención de Impuesto a la Renta

Scenario: Professional services with 10% IR retention

{
  "ruc": "0707012605001",
  "tipo": "07",
  "id_externo": "RET-2025-002",
  "retencion": {
    "fecha": "07/12/2025",
    "establecimiento": "001",
    "puntoEmision": "002",
    "secuencial": "000000124",
    "periodoFiscal": "12/2025",
    "sujetoRetenido": {
      "tipoIdentificacion": "05",
      "documento": "0987654321",
      "nombre": "ING. JUAN PEREZ",
      "direccion": "Calle Los Artesanos #456",
      "telefono": "0998765432",
      "correo": "[email protected]"
    },
    "total": 100.00
  },
  "detalles": [
    {
      "codigo": "1",
      "codigoRetencion": "332",
      "baseImponible": 1000.00,
      "porcentajeRetener": 10.0,
      "valorRetenido": 100.00,
      "codDocSustento": "01",
      "numDocSustento": "001-002-000001235",
      "fechaEmisionSustento": "05/12/2025"
    }
  ],
  "notificaciones": {
    "email": "[email protected]",
    "webhook_url": "https://profesional.com/webhooks/retentions"
  }
}

Example 3: Retención Mixta (IVA + IR)

Scenario: Supplier with both IVA and IR retention

{
  "ruc": "0707012605001",
  "tipo": "07",
  "id_externo": "RET-2025-003",
  "retencion": {
    "fecha": "07/12/2025",
    "establecimiento": "002",
    "puntoEmision": "001",
    "secuencial": "000000125",
    "periodoFiscal": "12/2025",
    "sujetoRetenido": {
      "tipoIdentificacion": "04",
      "documento": "1765432109001",
      "nombre": "CONSTRUCTORA DEL ECUADOR S.A.",
      "direccion": "Av. De la Construcción #123"
    },
    "total": 136.00
  },
  "detalles": [
    {
      "codigo": "1",
      "codigoRetencion": "1",
      "baseImponible": 1000.00,
      "porcentajeRetener": 1.0,
      "valorRetenido": 10.00,
      "codDocSustento": "01",
      "numDocSustento": "002-001-000001236",
      "fechaEmisionSustento": "03/12/2025"
    },
    {
      "codigo": "2",
      "codigoRetencion": "1",
      "baseImponible": 420.00,
      "porcentajeRetener": 30.0,
      "valorRetenido": 126.00,
      "codDocSustento": "01",
      "numDocSustento": "002-001-000001236",
      "fechaEmisionSustento": "03/12/2025"
    }
  ],
  "notificaciones": {
    "email": "[email protected]",
    "webhook_url": "https://constructora.com/webhooks/retentions"
  }
}

Example 4: Retención por Servicios Profesionales

Scenario: Professional services with 8% IR retention

{
  "ruc": "0707012605001",
  "tipo": "07",
  "id_externo": "RET-2025-004",
  "retencion": {
    "fecha": "07/12/2025",
    "establecimiento": "001",
    "puntoEmision": "003",
    "secuencial": "000000126",
    "periodoFiscal": "12/2025",
    "sujetoRetenido": {
      "tipoIdentificacion": "06",
      "documento": "PP987654321",
      "nombre": "MARIA GONZALEZ",
      "direccion": "Oficina Central, Piso 5",
      "correo": "[email protected]"
    },
    "total": 80.00
  },
  "detalles": [
    {
      "codigo": "1",
      "codigoRetencion": "331",
      "baseImponible": 1000.00,
      "porcentajeRetener": 8.0,
      "valorRetenido": 80.00,
      "codDocSustento": "01",
      "numDocSustento": "001-003-000001237",
      "fechaEmisionSustento": "04/12/2025"
    }
  ],
  "notificaciones": {
    "email": "[email protected]",
    "webhook_url": "https://consultora.com/webhooks/retentions"
  }
}

Example 5: Retención Múltiple en un Período

Scenario: Multiple invoices from same supplier in same fiscal period

{
  "ruc": "0707012605001",
  "tipo": "07",
  "id_externo": "RET-2025-005",
  "retencion": {
    "fecha": "07/12/2025",
    "establecimiento": "001",
    "puntoEmision": "001",
    "secuencial": "000000127",
    "periodoFiscal": "12/2025",
    "sujetoRetenido": {
      "tipoIdentificacion": "04",
      "documento": "1789012345001",
      "nombre": "DISTRIBUIDORA NACIONAL S.A.",
      "direccion": "Av. Comercial #789, Guayaquil",
      "telefono": "0422334455"
    },
    "total": 320.00
  },
  "detalles": [
    {
      "codigo": "1",
      "codigoRetencion": "2",
      "baseImponible": 2000.00,
      "porcentajeRetener": 2.0,
      "valorRetenido": 40.00,
      "codDocSustento": "01",
      "numDocSustento": "001-001-000001238",
      "fechaEmisionSustento": "15/11/2025"
    },
    {
      "codigo": "2",
      "codigoRetencion": "2",
      "baseImponible": 400.00,
      "porcentajeRetener": 30.0,
      "valorRetenido": 120.00,
      "codDocSustento": "01",
      "numDocSustento": "001-001-000001238",
      "fechaEmisionSustento": "15/11/2025"
    },
    {
      "codigo": "1",
      "codigoRetencion": "1",
      "baseImponible": 1500.00,
      "porcentajeRetener": 1.0,
      "valorRetenido": 15.00,
      "codDocSustento": "01",
      "numDocSustento": "001-001-000001239",
      "fechaEmisionSustento": "20/11/2025"
    },
    {
      "codigo": "2",
      "codigoRetencion": "1",
      "baseImponible": 600.00,
      "porcentajeRetener": 30.0,
      "valorRetenido": 180.00,
      "codDocSustento": "01",
      "numDocSustento": "001-001-000001239",
      "fechaEmisionSustento": "20/11/2025"
    },
    {
      "codigo": "1",
      "codigoRetencion": "1",
      "baseImponible": 650.00,
      "porcentajeRetener": 1.0,
      "valorRetenido": 6.50,
      "codDocSustento": "01",
      "numDocSustento": "001-001-000001240",
      "fechaEmisionSustento": "25/11/2025"
    }
  ],
  "notificaciones": {
    "email": "[email protected]",
    "webhook_url": "https://distribuidora.com/webhooks/retentions"
  }
}

Tipos de Documentos Soportados

Sustento Tipo de Documentos (`codDocSustento`)

Código	Descripción	Common Use
------	-------------	------------
`01`	Factura	Most common case
`03`	Liquidación de compra	Purchases
`05`	Nota de débito	Adjustments
`18`	Orden de compra	Government entities

Formato de Número de Documento

{establecimiento}-{puntoEmision}-{secuencial}

Example: 001-001-000001234

Tax Códigos Reference

Impuesto a la Renta (IR)

IVA Retention

Activity	Retention Código	Percentage
----------	----------------	------------
Professional services	331	8%
Professional services (high income)	332	10%
Supply of goods	1	1%
Supply of services	2	2%
Other	333	25%
Supplier Type	Retention Código	Percentage
---------------	----------------	------------
Regular	1	30%
Regular (special)	2	70%
Government/Non-profit	3	100%

Common Errors and Solutions

Error 1: Porcentaje y Valor Inconsistentes

Error Message:

Descuadre en detalle: base(100.00) * porcentaje(10%) = 10.00, pero valorRetenido = 12.00

Solution:

Ensure valorRetenido = baseImponible * porcentajeRetener / 100
Check rounding to 2 decimal places
Example: 100.00 * 10.0 / 100 = 10.00

Error 2: Total Incorrecto

Error Message:

Descuadre total: suma retenciones(115.00) != retencion.total(110.00)

Solution:

Sum all valorRetenido must equal retencion.total
Check each calculation individually
Verify decimal rounding

Error 3: Fecha Futura

Error Message:

Fecha de emisión de documento sustento (08/12/2025) no puede ser futura

Solution:

Document sustento dates must be <= retention date
Use current or past dates for sustento documents
Retention date can be current or future

Error 4: Secuencial Duplicado

Error Message:

The retencion.secuencial has already been taken.

Solution:

Use unique sequential numbers per establishment and emission point
Retention numbers are independent from invoice/credit note numbers

Pruebas with cURL

Test Retention

curl -X POST http://localhost:8000/api/document \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "ruc": "0707012605001",
    "tipo": "07",
    "id_externo": "TEST-RET-001",
    "retencion": {
      "fecha": "07/12/2025",
      "establecimiento": "001",
      "puntoEmision": "001",
      "secuencial": "999999999",
      "periodoFiscal": "12/2025",
      "sujetoRetenido": {
        "tipoIdentificacion": "05",
        "documento": "0999999999",
        "nombre": "TEST PROVIDER",
        "direccion": "Test Address"
      },
      "total": 10.00
    },
    "detalles": [
      {
        "codigo": "1",
        "codigoRetencion": "1",
        "baseImponible": 1000.00,
        "porcentajeRetener": 1.0,
        "valorRetenido": 10.00,
        "codDocSustento": "01",
        "numDocSustento": "001-001-999999999",
        "fechaEmisionSustento": "01/12/2025"
      }
    ],
    "notificaciones": {
      "email": "[email protected]",
      "webhook_url": "https://test.com/webhook"
    }
  }'

Field Reference

Retention Fields

Retained Subject Fields

Detail Fields

Field	Required	Max Length	Descripción
-------	----------	------------	-------------
`fecha`	Yes	-	Issue date (dd/mm/YYYY)
`establecimiento`	Yes	3	Establishment code
`puntoEmision`	Yes	3	Emission point code
`secuencial`	Yes	9	Secuencial number (unique per establishment)
`periodoFiscal`	Yes	-	Fiscal period (MM/YYYY)
`total`	Yes	-	Sum of all retention amounts
Field	Required	Max Length	Descripción
-------	----------	------------	-------------
`tipoIdentificacion`	Yes	-	ID type (04,05,06,07,08)
`documento`	Yes	20	ID number
`nombre`	Yes	150	Subject name
`direccion`	No	300	Subject address
`telefono`	No	15	Subject phone
`correo`	No	-	Email for notifications
Field	Required	Type	Descripción
-------	----------	------	-------------
`codigo`	Yes	String	Tax code (1=IR, 2=IVA)
`codigoRetencion`	Yes	String	Retention percentage code
`baseImponible`	Yes	Decimal	Base amount for calculation
`porcentajeRetener`	Yes	Decimal	Percentage to retain
`valorRetenido`	Yes	Decimal	Calculated retention amount
`codDocSustento`	Yes	String	Soporteing document type
`numDocSustento`	Yes	String	Soporteing document number
`fechaEmisionSustento`	Yes	String	Soporteing document date

Business Rules

Fiscal Period

All retentions for a supplier should be grouped by fiscal period
Fiscal period format: MM/YYYY
Cannot have multiple retentions for same invoice in same period

Calculation Rules

IR: valorRetenido = baseImponible * porcentajeRetener / 100
IVA: valorRetenido = baseImponible * porcentajeRetener / 100
Total: retencion.total = sum(detalles.valorRetenido)

Timing Rules

Retention date can be current or future
Sustento document dates must be <= retention date
Fiscal period should match sustento document dates

Best Practices

Group by fiscal period for efficiency
Validate calculations before submission
Maintain unique sequentials per establishment
Use appropriate retention codes based on supplier type
Keep supporting document information accurate
Test with small amounts before large retentions
Document retention reasons for audit purposes
Monitor retention totals to avoid duplicate retentions

Retention (Comprobante de Retención) Examples - Type `07`

Table of Contents

Retention Types

Tax Retention Códigos (`codigo`)

Retention Percentage Códigos (`codigoRetencion`)

Fiscal Period (`periodoFiscal`)

Example 1: Retención de IVA

Expected Response

Example 2: Retención de Impuesto a la Renta

Example 3: Retención Mixta (IVA + IR)

Example 4: Retención por Servicios Profesionales

Example 5: Retención Múltiple en un Período

Tipos de Documentos Soportados

Sustento Tipo de Documentos (`codDocSustento`)

Formato de Número de Documento

Tax Códigos Reference

Impuesto a la Renta (IR)

IVA Retention

Common Errors and Solutions

Error 1: Porcentaje y Valor Inconsistentes

Error 2: Total Incorrecto

Error 3: Fecha Futura

Error 4: Secuencial Duplicado

Pruebas with cURL

Test Retention

Field Reference

Retention Fields

Retained Subject Fields

Detail Fields

Business Rules

Fiscal Period

Calculation Rules

Timing Rules

Best Practices