Comprobantes de Retención

Pruebas
Producción

Dominio: https://test-api-factura.edw-dev.com

Los comprobantes de retención son documentos electrónicos que certifican las retenciones de impuestos realizadas en la fuente al momento del pago de facturas, honorarios profesionales, servicios, o cualquier otro concepto sujeto a retención según la normativa tributaria ecuatoriana.

Información General

Código SRI: 07
Tipo de documento: Comprobante de Retención
Uso: Certificar retenciones de IR, IVA, ISD
Proveedor requerido: Sí (quien recibe la retención)
Documento de soporte: Requerido (factura, liquidación, etc.)
Emisión automática: Opcional

Endpoint

POST /api/v1/documents/create

Headers Requeridos

Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}

Parámetros Específicos

Parámetro	Tipo	Requerido	Descripción
`sri_code_document`	string	Sí	Debe ser `"07"` para comprobantes de retención
`send_to_emit`	boolean	No	Si se debe emitir automáticamente al SRI
`supplier`	object	Sí	Información del proveedor (quien recibe la retención)
`document`	object	Sí	Información del documento y soporte
`retentions`	array	Sí	Array de retenciones aplicadas
`aditional_fields`	array	No	Campos adicionales

Estructura del Documento (con soporte)

{
  "date": "2024-01-15",
  "establishment": "001",
  "point_of_emission": "001",
  "support_code_document": "01",
  "support_date": "2024-01-10",
  "support_document_number": "001-001-000000012",
  "payment_period": "01/2024"
}

Campos de Soporte Requeridos

Campo	Descripción	Ejemplo
`support_code_document`	Código del documento original	`"01"` (Factura)
`support_date`	Fecha del documento original	`"2024-01-10"`
`support_document_number`	Número del documento original	`"001-001-000000012"`
`payment_period`	Período fiscal del pago	`"01/2024"`

Estructura de Retenciones

{
  "retentions": [
    {
      "tax_code": "1",
      "retention_code": "303",
      "base_amount": 1000.00,
      "retention_percentage": 1.00,
      "retention_amount": 10.00
    }
  ]
}

Códigos de Retención Comunes

Retenciones de Impuesto a la Renta

Código	Descripción	Porcentaje
`303`	Honorarios profesionales	10%
`304`	Servicios predomina intelecto	8%
`307`	Servicios predomina mano obra	2%
`308`	Utilización o aprovechamiento imagen	10%
`309`	Servicios entre sociedades	25%
`310`	Arrendamiento inmuebles	8%
`312`	Suministros y materiales	1%
`319`	Otras retenciones aplicables 1%	1%
`320`	Otras retenciones aplicables 2%	2%

Retenciones de IVA

Código	Descripción	Porcentaje
`725`	Retención 30% IVA	30%
`727`	Retención 70% IVA	70%
`729`	Retención 100% IVA	100%

Ejemplos de Implementación

Comprobante de Retención Simple

Solicitud

{
  "sri_code_document": "07",
  "send_to_emit": true,
  "supplier": {
    "identification_number": "0987654321",
    "name": "María",
    "lastname": "González",
    "identification_type": "CEDULA",
    "email": "[email protected]",
    "address": "Quito, Ecuador"
  },
  "document": {
    "date": "2024-01-15",
    "establishment": "001",
    "point_of_emission": "001",
    "support_code_document": "01",
    "support_date": "2024-01-10",
    "support_document_number": "001-001-000000012",
    "payment_period": "01/2024"
  },
  "retentions": [
    {
      "tax_code": "1",
      "retention_code": "303",
      "base_amount": 500.00,
      "retention_percentage": 10.00,
      "retention_amount": 50.00
    }
  ]
}

Respuesta Exitosa (201)

{
  "message": "Documento creado exitosamente",
  "status": "CREATED",
  "payload": {
    "id": 123456791,
    "environment": "PROD",
    "number": 1,
    "date": "2024-01-15",
    "total_retention": "50.00",
    "type": "retention",
    "supplier": {
      "id": 987654322,
      "full_name": "María González",
      "email": "[email protected]",
      "identification_type": "cedula",
      "identification_number": "0987654321"
    },
    "sri": {
      "access_key": "1501202407012345678900110010010000000011234567890",
      "status": "AUTORIZADO",
      "sequential_number": "000000001",
      "establishment": "001",
      "point_emission": "001",
      "document_number": "001-001-000000001",
      "type_document": "COMPROBANTE RETENCION",
      "code_document": "07"
    },
    "support": {
      "code_document": "01",
      "document_number": "001-001-000000012",
      "date": "2024-01-10",
      "payment_period": "01/2024"
    },
    "retentions": [
      {
        "tax_type": "RENTA",
        "tax_code": "1",
        "retention_code": "303",
        "retention_description": "Honorarios profesionales",
        "base_amount": "500.00",
        "retention_percentage": "10.00",
        "retention_amount": "50.00"
      }
    ]
  }
}

Comprobante con Múltiples Retenciones

Solicitud

{
  "sri_code_document": "07",
  "supplier": {
    "identification_number": "1234567890001",
    "name": "Empresa",
    "lastname": "Servicios S.A.",
    "identification_type": "RUC",
    "email": "[email protected]",
    "address": "Guayaquil, Ecuador"
  },
  "document": {
    "date": "2024-10-09",
    "sri_establishment": "001",
    "sri_point_emi": "004",
    "support_code_document": "01",
    "support_date": "2024-10-08",
    "support_document_number": "002-001-000000045",
    "payment_period": "10/2024"
  },
  "retentions": [
    {
      "tax_code": "1",
      "retention_code": "304",
      "base_amount": 1000.00,
      "retention_percentage": 8.00,
      "retention_amount": 80.00
    },
    {
      "tax_code": "2",
      "retention_code": "725",
      "base_amount": 120.00,
      "retention_percentage": 30.00,
      "retention_amount": 36.00
    }
  ],
  "aditional_fields": [
    {
      "key": "Telefono",
      "value": "042345678",
      "type": "sri"
    },
    {
      "key": "Email",
      "value": "[email protected]",
      "type": "sri"
    }
  ]
}

Respuesta con Múltiples Retenciones (201)

{
  "message": "Documento creado",
  "status": "CREATED",
  "payload": {
    "id": 1339329972,
    "environment": "TEST",
    "number": 3,
    "date": "2024-10-09",
    "total_retention": "116.00",
    "status": "draft",
    "type": "retention",
    "supplier": {
      "id": 61247346,
      "full_name": "Empresa Servicios S.A.",
      "email": "[email protected]",
      "identification_type": "ruc",
      "identification_number": "1234567890001"
    },
    "sri": {
      "establishment": "001",
      "point_emi": "004",
      "type_document": "COMPROBANTE RETENCION",
      "title_document": "Comprobante de retención",
      "code_document": "07"
    },
    "support": {
      "code_document": "01",
      "document_number": "002-001-000000045",
      "date": "2024-10-08",
      "payment_period": "10/2024"
    },
    "retentions": [
      {
        "tax_type": "RENTA",
        "tax_code": "1",
        "retention_code": "304",
        "retention_description": "Servicios predomina intelecto",
        "base_amount": "1000.00",
        "retention_percentage": "8.00",
        "retention_amount": "80.00"
      },
      {
        "tax_type": "IVA",
        "tax_code": "2",
        "retention_code": "725",
        "retention_description": "Retención 30% IVA",
        "base_amount": "120.00",
        "retention_percentage": "30.00",
        "retention_amount": "36.00"
      }
    ],
    "totals": {
      "total_renta_retention": "80.00",
      "total_iva_retention": "36.00",
      "total_retention": "116.00"
    }
  }
}

Ejemplos de Código

curl -X POST "https://dev-facturacion.e-dinky.test/api/v1/documents/create" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "sri_code_document": "07",
    "send_to_emit": true,
    "supplier": {
      "identification_number": "0987654321",
      "name": "María",
      "lastname": "González",
      "identification_type": "CEDULA",
      "email": "[email protected]",
      "address": "Quito, Ecuador"
    },
    "document": {
      "date": "2024-01-15",
      "establishment": "001",
      "point_of_emission": "001",
      "support_code_document": "01",
      "support_date": "2024-01-10",
      "support_document_number": "001-001-000000012",
      "payment_period": "01/2024"
    },
    "retentions": [
      {
        "tax_code": "1",
        "retention_code": "303",
        "base_amount": 500.00,
        "retention_percentage": 10.00,
        "retention_amount": 50.00
      }
    ]
  }'

<?php

use Illuminate\Support\Facades\Http;

$token = 'your-api-token';

$response = Http::withHeaders([
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer ' . $token,
])->post('https://dev-facturacion.e-dinky.test/api/v1/documents/create', [
    'sri_code_document' => '07',
    'send_to_emit' => true,
    'supplier' => [
        'identification_number' => '0987654321',
        'name' => 'María',
        'lastname' => 'González',
        'identification_type' => 'CEDULA',
        'email' => '[email protected]',
        'address' => 'Quito, Ecuador'
    ],
    'document' => [
        'date' => '2024-01-15',
        'establishment' => '001',
        'point_of_emission' => '001',
        'support_code_document' => '01',
        'support_date' => '2024-01-10',
        'support_document_number' => '001-001-000000012',
        'payment_period' => '01/2024'
    ],
    'retentions' => [
        [
            'tax_code' => '1',
            'retention_code' => '303',
            'base_amount' => 500.00,
            'retention_percentage' => 10.00,
            'retention_amount' => 50.00
        ]
    ]
]);

if ($response->successful()) {
    $document = $response->json();
    echo "Comprobante de retención creado: " . $document['payload']['id'];
    echo "Número de documento: " . $document['payload']['sri']['document_number'];
    echo "Documento de soporte: " . $document['payload']['support']['document_number'];
    echo "Total retenido: $" . $document['payload']['total_retention'];
} else {
    echo "Error: " . $response->body();
}

const axios = require('axios');

const createRetention = async () => {
    const token = 'your-api-token';

    const config = {
        method: 'post',
        url: 'https://dev-facturacion.e-dinky.test/api/v1/documents/create',
        headers: {
            'Content-Type': 'application/json',
            'Accept': 'application/json',
            'Authorization': `Bearer ${token}`
        },
        data: {
            sri_code_document: '07',
            send_to_emit: true,
            supplier: {
                identification_number: '0987654321',
                name: 'María',
                lastname: 'González',
                identification_type: 'CEDULA',
                email: '[email protected]',
                address: 'Quito, Ecuador'
            },
            document: {
                date: '2024-01-15',
                establishment: '001',
                point_of_emission: '001',
                support_code_document: '01',
                support_date: '2024-01-10',
                support_document_number: '001-001-000000012',
                payment_period: '01/2024'
            },
            retentions: [
                {
                    tax_code: '1',
                    retention_code: '303',
                    base_amount: 500.00,
                    retention_percentage: 10.00,
                    retention_amount: 50.00
                }
            ]
        }
    };

    try {
        const response = await axios(config);
        console.log('Comprobante de retención creado:', response.data.payload.id);
        console.log('Número de documento:', response.data.payload.sri.document_number);
        console.log('Documento de soporte:', response.data.payload.support.document_number);
        console.log('Total retenido: $', response.data.payload.total_retention);
        return response.data;
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
        throw error;
    }
};

// Uso
createRetention()
    .then(result => console.log('Éxito:', result))
    .catch(error => console.error('Error:', error));

Tipos de Retenciones

1. Retenciones de Impuesto a la Renta

Servicios Profesionales

Código 303: Honorarios profesionales (10%)
Código 304: Servicios predomina intelecto (8%)
Código 307: Servicios predomina mano obra (2%)

Arrendamientos

Código 310: Arrendamiento inmuebles (8%)
Código 311: Arrendamiento muebles (1%)

Otros Servicios

Código 308: Utilización imagen (10%)
Código 309: Servicios entre sociedades (25%)
Código 312: Suministros y materiales (1%)

2. Retenciones de IVA

Por Tipo de Contribuyente

Código 725: Retención 30% IVA
Código 727: Retención 70% IVA
Código 729: Retención 100% IVA

Casos Especiales

Código 731: Retención IVA presuntivo
Código 732: Retención IVA servicios profesionales

3. Retenciones de ISD

Impuesto Salida Divisas

Código 4580: ISD 5%
Código 4581: ISD tarjetas crédito

Validaciones Específicas

Documento de Soporte

Código: Debe corresponder a un tipo válido
Fecha: No puede ser posterior al comprobante
Número: Debe existir y estar autorizado
Período: Debe corresponder al período fiscal

Proveedor (Supplier)

Identificación: Debe ser válida según tipo
Tipo: CEDULA, RUC, PASAPORTE
Email: Requerido para notificaciones
Datos: Completos y actualizados

Retenciones

Códigos: Deben existir en catálogo SRI
Porcentajes: Deben coincidir con código
Base: Debe ser coherente con documento
Cálculo: Validación matemática exacta

Totales

Suma: Total debe ser suma de retenciones
Límites: No exceder base imponible
Coherencia: Con documento de soporte

Códigos de Respuesta

Código	Descripción	Acción
`201`	Comprobante creado exitosamente	Continuar con el flujo
`400`	Datos inválidos	Revisar formato de datos
`401`	Token inválido	Renovar autenticación
`404`	Documento de soporte no encontrado	Verificar número de factura
`422`	Error de validación	Corregir datos según errores
`500`	Error del servidor	Reintentar más tarde

Errores Comunes

Error de Validación (422)

{
  "message": "Error de validación",
  "status": "UNPROCESSABLE_ENTITY",
  "errors": {
    "document.support_document_number": [
      "El documento de soporte no existe"
    ],
    "retentions.0.retention_code": [
      "El código de retención no es válido"
    ],
    "retentions.0.retention_amount": [
      "El cálculo de retención es incorrecto"
    ]
  }
}

Soluciones

Documento de soporte no existe
- Verificar número de factura
- Confirmar que esté autorizada
- Revisar establecimiento y punto de emisión
Código de retención inválido
- Consultar catálogo actualizado del SRI
- Verificar vigencia del código
- Confirmar aplicabilidad al caso
Cálculo incorrecto
- Verificar fórmula: base × porcentaje
- Confirmar porcentaje según código
- Validar redondeo a 2 decimales

Mejores Prácticas

1. Validación de Códigos

// Validar códigos de retención antes de crear
$validRetentionCodes = [
    '1' => ['303', '304', '307', '308', '309', '310', '312', '319', '320'],
    '2' => ['725', '727', '729', '731', '732']
];

foreach ($retentions as $retention) {
    if (!in_array($retention['retention_code'], $validRetentionCodes[$retention['tax_code']])) {
        throw new InvalidRetentionCodeException($retention['retention_code']);
    }
}

2. Cálculo Automático

// Calcular automáticamente el monto de retención
const calculateRetention = (baseAmount, retentionCode) => {
    const retentionRates = {
        '303': 10.00,  // Honorarios profesionales
        '304': 8.00,   // Servicios predomina intelecto
        '307': 2.00,   // Servicios predomina mano obra
        '725': 30.00,  // Retención 30% IVA
        '727': 70.00,  // Retención 70% IVA
        '729': 100.00  // Retención 100% IVA
    };

    const rate = retentionRates[retentionCode];
    return Math.round((baseAmount * rate / 100) * 100) / 100;
};

3. Validación de Período

// Validar período fiscal
$validatePaymentPeriod = function($supportDate, $retentionDate, $paymentPeriod) {
    $supportMonth = date('m/Y', strtotime($supportDate));
    $retentionMonth = date('m/Y', strtotime($retentionDate));

    if ($paymentPeriod !== $retentionMonth) {
        throw new InvalidPaymentPeriodException();
    }
};

4. Trazabilidad Completa

// Mantener referencia completa al documento original
const createRetention = (data) => {
    return {
        ...data,
        support: {
            document_id: originalInvoice.id,
            access_key: originalInvoice.access_key,
            total_amount: originalInvoice.total,
            tax_amount: originalInvoice.tax_amount,
            ...data.support
        }
    };
};

Flujo Recomendado

Verificar documento de soporte
- Confirmar que existe y está autorizado
- Validar datos del proveedor
- Revisar montos y bases imponibles
Determinar retenciones aplicables
- Identificar tipo de servicio/bien
- Consultar tabla de retenciones vigente
- Verificar exenciones o casos especiales
Calcular retenciones
- Aplicar porcentajes correctos
- Validar bases imponibles
- Verificar cálculos matemáticos
Crear comprobante
- Enviar solicitud POST
- Verificar respuesta
- Manejar errores específicos
Procesar resultado
- Actualizar cuentas por pagar
- Notificar al proveedor
- Registrar en contabilidad
- Preparar declaraciones

Consideraciones Fiscales

Obligaciones del Agente de Retención

Registro: Mantener registro detallado
Entrega: Entregar comprobante al retenido
Declaración: Incluir en declaraciones mensuales
Pago: Pagar retenciones al SRI

Plazos y Términos

Emisión: Máximo 5 días después del pago
Entrega: Inmediata al retenido
Declaración: Hasta el día 28 del mes siguiente
Pago: Junto con la declaración

Sanciones por Incumplimiento

No emisión: Multa del 5% del monto retenido
Emisión tardía: Multa del 1% por cada mes
Datos incorrectos: Multa según gravedad
No entrega: Multa adicional

Impacto Contable

En el Agente de Retención (Emisor)

Cuentas por pagar: Reducción por retención
Retenciones por pagar: Pasivo con el SRI
Gastos: Registro del gasto total
Crédito tributario: Si aplica

En el Retenido (Proveedor)

Cuentas por cobrar: Reducción por retención
Retenciones a favor: Activo con el SRI
Ingresos: Registro del ingreso total
Crédito tributario: Para declaraciones

Casos de Uso Específicos

1. Honorarios Profesionales

{
  "retentions": [
    {
      "tax_code": "1",
      "retention_code": "303",
      "base_amount": 1000.00,
      "retention_percentage": 10.00,
      "retention_amount": 100.00
    }
  ]
}

2. Servicios con IVA

{
  "retentions": [
    {
      "tax_code": "1",
      "retention_code": "304",
      "base_amount": 1000.00,
      "retention_percentage": 8.00,
      "retention_amount": 80.00
    },
    {
      "tax_code": "2",
      "retention_code": "725",
      "base_amount": 120.00,
      "retention_percentage": 30.00,
      "retention_amount": 36.00
    }
  ]
}

3. Arrendamiento

{
  "retentions": [
    {
      "tax_code": "1",
      "retention_code": "310",
      "base_amount": 800.00,
      "retention_percentage": 8.00,
      "retention_amount": 64.00
    }
  ]
}

Notas Importantes

📋 Documento de soporte obligatorio: Todo comprobante debe referenciar un documento válido
⚖️ Cumplimiento fiscal: Obligatorio para agentes de retención
🔗 Trazabilidad completa: Se mantiene la relación con el documento original
⏰ Plazos estrictos: Emisión máximo 5 días después del pago
📧 Notificaciones automáticas: El proveedor recibe notificación del comprobante
💾 Impacto en declaraciones: Afecta automáticamente las declaraciones del SRI
🔄 Estados sincronizados: El estado se actualiza automáticamente
📊 Contabilización automática: Se registra automáticamente en la contabilidad
🚫 No modificable: Una vez autorizado, no se puede modificar
💰 Validación de cálculos: Los montos se validan automáticamente
📅 Período fiscal: Debe corresponder al mes de pago
🏛️ Obligación legal: Incumplimiento genera sanciones del SRI