<!-- source_url: https://docs.mynexusapi.com/v1/guias/emision-07 | last_updated: 2026-11-19 -->

# Comprobante de retención

Emite un comprobante de retención para acreditar al proveedor los impuestos de renta e IVA que le retuviste al pagarle.

Emites el comprobante de retención como agente de retención sobre la factura
que te entregó el proveedor, y con él el proveedor descuenta lo retenido de sus
propios impuestos.

Esta guía explica los conceptos de la retención, te da un ejemplo mínimo listo
para enviar y describe cada campo con las reglas que valida la API. Las
cabeceras y las reglas comunes a todos los tipos están en
[Comprobantes electrónicos](/v1/guias/emision).

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal. Los ejemplos usan `https://api-sandbox.mynexusapi.com` y los [datos de prueba](/v1/guias/datos-de-prueba).

Envías el comprobante de retención a
`POST /v1/contribuyentes/{identificacion}/retenciones`. El tipo de comprobante
lo fija la ruta, así que el cuerpo no lleva `infoTributaria.tipoDocumento`.

```
POST /v1/contribuyentes/{identificacion}/retenciones
Cabeceras: X-Api-Key, Idempotency-Key, Content-Type: application/json
```

Para revisar el cuerpo sin emitir, usa
`POST /v1/contribuyentes/{identificacion}/retenciones/validar`; aplica las mismas
reglas y su respuesta se describe en
[Validar sin emitir](/v1/guias/emision#validar-sin-emitir).

## Conceptos

Si nunca antes trabajaste con retenciones en Ecuador, lee esta sección primero.
Todos los términos están también en el [Glosario](/v1/guias/glosario).

- **Retención**: cuando un contribuyente designado como agente de retención
  paga una compra, no le entrega al proveedor el 100 %: se queda con un
  porcentaje del impuesto y lo paga al SRI en nombre del proveedor.
- **Retención de renta**: un porcentaje de la base sin IVA, por ejemplo el 10 %
  en honorarios profesionales. Se identifica con `codigo` `1`.
- **Retención de IVA**: un porcentaje del **valor del IVA** de la compra, por
  ejemplo el 100 % del IVA de los honorarios de una persona natural. Se
  identifica con `codigo` `2`.
- **Documento de sustento**: el comprobante del proveedor sobre el que retienes,
  normalmente su factura. Lo describes en `docsSustento` con su número, fecha,
  autorización, totales, impuestos y forma de pago.
- **Código de sustento** (`codSustento`): indica para qué usas la compra en tu
  contabilidad tributaria, por ejemplo `01`, crédito tributario de IVA.
- **Periodo fiscal**: el mes y el año en que declaras la retención, con el
  formato `MM/yyyy`.
- **Sujeto retenido**: el proveedor al que le retienes.

Ten en cuenta el plazo: la normativa del SRI exige emitir la retención dentro
de los 5 días siguientes a recibir el comprobante de venta del proveedor. Te
recomendamos controlarlo en tu sistema, porque la API no lo verifica.

## Cuándo lo emites

Emite un comprobante de retención en situaciones como estas:

- Pagas honorarios a un profesional independiente: retienes renta e IVA.
- Compras bienes o servicios a otra empresa y eres agente de retención.
- Registras en tu contabilidad una factura de proveedor sobre la que la ley te
  obliga a retener.

## Límites del comprobante de retención

La API aplica estos límites al comprobante de retención.

| Límite | Qué significa para ti |
|---|---|
| Un documento de sustento por retención | `docsSustento` lleva exactamente un elemento. Si retienes sobre varias facturas, emite una retención por factura. |
| Solo pago local | `pagoLocExt` debe ser `01`. Los pagos al exterior (`02`) se rechazan. |
| Sin dividendos ni reembolsos | `codSustento` `10` (dividendos) y `codDocSustento` `41` (reembolsos) se rechazan con un 422. |
| Sin banano | Los códigos de renta `338`, `340`, `341`, `342`, `342A` y `342B` se rechazan con un 422. |
| Impuestos retenidos | `retenciones[].codigo` admite `1` (renta), `2` (IVA) y `6` (ISD). |
| Campos que no existen | La API no procesa los datos de pago al exterior (`tipoRegi`, `paisEfecPago`, `aplicConvDobTrib`, `pagExtSujRetNorLeg`, `pagoRegFis`), de reembolso (`totalComprobantesReembolso`, `totalBaseImponibleReembolso`, `totalImpuestoReembolso`, `reembolsos`), de dividendos ni de banano (`retenciones[].dividendos`, `retenciones[].compraCajBanano`). Si los envías, la API los rechaza como campos desconocidos. |

## Antes de empezar

- [ ] Una API Key de pruebas en la variable de entorno `ECUAFACT_API_KEY`. Si todavía no tienes una, [crea tu sandbox](/v1/guias/sandbox).
- [ ] En el ambiente de pruebas puedes llamar desde cualquier IP. En producción, la IP desde la que llamas debe estar registrada para tu API Key, como se explica en [Autenticación](/v1/guias/autenticacion).
- [ ] El valor `identificacion` de tu contribuyente, que obtienes con [`GET /v1/contexto`](/v1/guias/consulta-contexto). En los ejemplos es `0123456789001`.
- [ ] El tipo `07` habilitado para ese contribuyente, es decir, que aparezca en `tiposComprobante` del contexto.
- [ ] Los datos de la factura del proveedor: número, fecha, totales, impuestos y, si es electrónica, su clave de acceso.
- [ ] Los códigos de retención y los porcentajes vigentes que aplican a la compra, que encuentras en [Catálogos: retenciones](/v1/guias/catalogos#retenciones-y-sustento).

## Ejemplo mínimo

Este ejemplo es la retención sobre una factura de honorarios profesionales de
una persona natural, por 100.00 más IVA 15 %, es decir, 115.00. Retienes el
10 % de renta y el 100 % del IVA. Guarda el JSON como `comprobante.json`, porque
lo usan los ejemplos de [Envío](#envio).

```json
{
  "origenReferencia": "MiERP",
  "referenciaExterna": "RET-2026-0001",
  "infoTributaria": {
    "ruc": "0123456789001",
    "estab": "001",
    "ptoEmi": "001",
    "secuencial": "000000000"
  },
  "info": {
    "fechaEmision": "05/10/2026",
    "tipoIdentificacionSujetoRetenido": "05",
    "identificacionSujetoRetenido": "0123456789",
    "razonSocialSujetoRetenido": "PROVEEDOR DE PRUEBAS",
    "periodoFiscal": "10/2026",
    "parteRel": "NO"
  },
  "docsSustento": [
    {
      "codSustento": "01",
      "codDocSustento": "01",
      "numDocSustento": "001001000000123",
      "fechaEmisionDocSustento": "01/10/2026",
      "fechaRegistroContable": "01/10/2026",
      "numAutDocSustento": "0110202601012345678900110010010000001231234567814",
      "pagoLocExt": "01",
      "totalSinImpuestos": 100.00,
      "importeTotal": 115.00,
      "impuestosDocSustento": [
        {
          "codImpuestoDocSustento": "2",
          "codigoPorcentaje": "4",
          "baseImponible": 100.00,
          "tarifa": 15,
          "valorImpuesto": 15.00
        }
      ],
      "retenciones": [
        {
          "codigo": "1",
          "codigoRetencion": "303",
          "baseImponible": 100.00,
          "porcentajeRetener": 10,
          "valorRetenido": 10.00
        },
        {
          "codigo": "2",
          "codigoRetencion": "3",
          "baseImponible": 15.00,
          "porcentajeRetener": 100,
          "valorRetenido": 15.00
        }
      ],
      "pagos": [
        {
          "formaPago": "20",
          "total": 115.00
        }
      ]
    }
  ],
  "infoAdicional": [
    {
      "nombre": "email",
      "valor": "proveedor@example.com"
    }
  ]
}
```

Con `"secuencial": "000000000"` te asignamos el siguiente número de la serie
001-001 de retenciones, y omitir el campo tiene el mismo efecto.

### Cómo se calcula

| Paso | Cálculo | Resultado | Campo |
|---|---|---|---|
| 1. Base de la factura del proveedor | | 100.00 | `totalSinImpuestos`, `impuestosDocSustento[0].baseImponible` |
| 2. IVA de la factura | 100.00 x 15 / 100 | 15.00 | `impuestosDocSustento[0].valorImpuesto` |
| 3. Total de la factura | 100.00 + 15.00 | 115.00 | `importeTotal` y suma de `pagos[].total` |
| 4. Retención de renta (código `303`, 10 %) sobre la base sin IVA | 100.00 x 10 / 100 | 10.00 | `retenciones[0].valorRetenido` |
| 5. Retención de IVA (código `3`, 100 %) sobre el **valor del IVA** | 15.00 x 100 / 100 | 15.00 | `retenciones[1].valorRetenido` |
| 6. Total retenido | 10.00 + 15.00 | 25.00 | No se envía; lo calculamos nosotros. |

Para el proveedor, el resultado es que de los 115.00 de su factura recibe 90.00
en efectivo o transferencia y 25.00 en el comprobante de retención, que tú pagas
al SRI.

> [!NOTE]
> Los porcentajes de este ejemplo son ilustrativos. Usa los códigos y porcentajes vigentes del SRI para tu caso. En la retención de IVA, la API comprueba que el código exista y que el porcentaje sea el de ese código; en la de renta, solo comprueba que `valorRetenido` sea `baseImponible` x `porcentajeRetener` / 100, y el SRI valida después que el porcentaje corresponda al código.

## Envío

Envía el `comprobante.json` del ejemplo mínimo con cualquiera de estos
ejemplos. Todos usan como `Idempotency-Key` la misma `referenciaExterna`,
RET-2026-0001.

```bash
curl -s -i -X POST \
  "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/retenciones" \
  -H "X-Api-Key: $ECUAFACT_API_KEY" \
  -H "Idempotency-Key: RET-2026-0001" \
  -H "Content-Type: application/json" \
  -d @comprobante.json
# 202 Accepted -> sigue con GET /v1/operaciones/{idOperacion}
```

```csharp
using System.Net.Http;
using System.Text;

string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!;
using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") };
http.DefaultRequestHeaders.Add("X-Api-Key", apiKey);

using var peticion = new HttpRequestMessage(HttpMethod.Post, "/v1/contribuyentes/0123456789001/retenciones");
peticion.Headers.Add("Idempotency-Key", "RET-2026-0001");
peticion.Content = new StringContent(
    await File.ReadAllTextAsync("comprobante.json"), Encoding.UTF8, "application/json");

using HttpResponseMessage respuesta = await http.SendAsync(peticion);
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
```

```python
import json
import os
import requests

with open("comprobante.json", encoding="utf-8") as archivo:
    cuerpo = json.load(archivo)

r = requests.post(
    "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/retenciones",
    headers={
        "X-Api-Key": os.environ["ECUAFACT_API_KEY"],
        "Idempotency-Key": "RET-2026-0001",
    },
    json=cuerpo,
    timeout=30,
)
print(r.status_code, r.text)
```

```javascript
// Node.js 18 o superior. Guarda como emitir.mjs y ejecuta: node emitir.mjs
import { readFile } from 'node:fs/promises';

const res = await fetch(
  'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/retenciones',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.ECUAFACT_API_KEY,
      'Idempotency-Key': 'RET-2026-0001',
      'Content-Type': 'application/json'
    },
    body: await readFile('comprobante.json', 'utf8')
  });
console.log(res.status, await res.text());
```

```php
<?php
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/retenciones');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'),
        'Idempotency-Key: RET-2026-0001',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => file_get_contents('comprobante.json'),
]);
$cuerpo = curl_exec($ch);
$estado = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $estado . ' ' . $cuerpo . PHP_EOL;
```

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;

// Dentro de: public static void main(String[] args) throws Exception
HttpClient cliente = HttpClient.newHttpClient();
HttpRequest peticion = HttpRequest.newBuilder()
    .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/retenciones"))
    .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
    .header("Idempotency-Key", "RET-2026-0001")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(Files.readString(Path.of("comprobante.json"))))
    .build();
HttpResponse<String> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString());
System.out.println(respuesta.statusCode() + " " + respuesta.body());
```

```csharp-sdk
using System.Text.Json;
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

var client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});

RetencionRequest comprobante = JsonSerializer.Deserialize<RetencionRequest>(
    await File.ReadAllTextAsync("comprobante.json"))!;

EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "RET-2026-0001");
Console.WriteLine($"Operacion {resultado.Admission.IdOperacion} / estado: {resultado.Admission.Estado}");
```

```python-sdk
import json
import os

from ecuafact import RetencionRequest, EcuafactClient, EcuafactClientOptions

client = EcuafactClient(EcuafactClientOptions(
    base_address="https://api-sandbox.mynexusapi.com/",
    api_key=os.environ["ECUAFACT_API_KEY"],
))

with open("comprobante.json", encoding="utf-8") as archivo:
    comprobante = RetencionRequest.model_validate(json.load(archivo))

resultado = client.emitir_en("0123456789001", comprobante, "RET-2026-0001")
print(f"Operacion {resultado.admission.id_operacion} / estado: {resultado.admission.estado}")
```

```javascript-sdk
// Node.js 18 o superior. Guarda como emitir-sdk.mjs y ejecuta: node emitir-sdk.mjs
import { readFile } from 'node:fs/promises';
import { EcuafactClient } from '@ecuafact/sdk';

const client = new EcuafactClient({
  baseAddress: 'https://api-sandbox.mynexusapi.com/',
  apiKey: process.env.ECUAFACT_API_KEY
});

const comprobante = JSON.parse(await readFile('comprobante.json', 'utf8'));
const resultado = await client.emitirRetencionEn('0123456789001', comprobante, 'RET-2026-0001');
console.log(`Operacion ${resultado.admission.idOperacion} / estado: ${resultado.admission.estado}`);
```

```php-sdk
<?php
use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

// $comprobante: RetencionRequest con la estructura de esta pagina (como armarlo: SDK PHP).
$resultado = $client->emitirEn('0123456789001', $comprobante, 'RET-2026-0001');
echo 'Operacion ' . $resultado->admission->idOperacion . ' / estado: ' . $resultado->admission->estado . PHP_EOL;
```

```java-sdk
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.EmisionResultado;
import com.ecuafact.sdk.contracts.RetencionRequest;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.file.Files;
import java.nio.file.Path;

// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));

RetencionRequest comprobante = new ObjectMapper()
    .readValue(Files.readString(Path.of("comprobante.json")), RetencionRequest.class);

EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "RET-2026-0001");
System.out.println("Operacion " + resultado.admission().idOperacion() + " / estado: " + resultado.admission().estado());
```

```bash-cli
# Resultado esperado: una fila con el estado recibido y el idOperacion de la retención.
ecuafact emitir comprobante.json --entorno sandbox
```

Si repites exactamente la misma solicitud, con la misma `Idempotency-Key` y el
mismo cuerpo, por ejemplo tras un timeout, la API no crea otra retención. Responde
202 con el mismo `idOperacion` y el estado actual de la operación.

## Estructura del comprobante

El cuerpo del comprobante de retención se organiza en bloques, y cada tabla
describe uno.

### Raíz

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `origenReferencia` | string | Sí | Nombre de tu sistema de origen, de hasta 64 caracteres entre letras y dígitos ASCII y `- _ . : /`. |
| `referenciaExterna` | string | Sí | Identificador estable del documento en tu sistema, de hasta 128 caracteres con el mismo alfabeto. Repítelo igual en cada reintento. |
| `infoTributaria` | object | Sí | Identidad del comprobante, descrita en la tabla `infoTributaria`. |
| `info` | object | Sí | Datos del sujeto retenido y del periodo. Su detalle está en la tabla `info`. |
| `docsSustento` | array | Sí | Exactamente un documento de sustento. Su detalle está en la tabla `docsSustento`. |
| `infoAdicional` | array | No | Hasta 15 objetos `{nombre, valor}`. Su detalle está en la tabla `infoAdicional`. |

No envíes `detalles`, `motivos` ni `destinatarios`, porque la API responde 422 con
`Campo no soportado en este contrato.` Tampoco envíes `claveAcceso`, `ambiente`, `tipoEmision`, `version` ni `formato`,
porque la API no los admite.

### `infoTributaria`

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `ruc` | string | Sí | RUC del emisor, que es el agente de retención, de 5 a 13 dígitos. Debe ser igual a la `identificacion` de la ruta; por ejemplo, `0123456789001`. |
| `estab` | string | Sí | Código del [establecimiento](/v1/guias/glosario), de hasta 3 dígitos. Se completa con ceros, así que `"1"` se toma como `"001"`. |
| `ptoEmi` | string | Sí | Código del [punto de emisión](/v1/guias/glosario), de hasta 3 dígitos. |
| `secuencial` | string | No | Si lo omites o envías `"000000000"`, te asignamos el siguiente número de la serie, que forman `estab`, `ptoEmi`, el tipo del comprobante y el ambiente. Si envías un número de hasta 9 dígitos, entre 1 y 999999999, usamos ese número. |

### `info`

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `fechaEmision` | string | Sí | Fecha de la retención, `dd/MM/yyyy`. |
| `tipoIdentificacionSujetoRetenido` | string | Sí | `04` RUC, `05` cédula, `06` pasaporte o `08` identificación del exterior. Los valores están en [Catálogos](/v1/guias/catalogos#tipos-de-identificacion). `07`, consumidor final, no se admite. |
| `identificacionSujetoRetenido` | string | Sí | Con `04`, 13 dígitos. Con `05`, 10 dígitos. Con otros tipos, hasta 20 caracteres. |
| `razonSocialSujetoRetenido` | string | Sí | Nombre o razón social del proveedor, hasta 300 caracteres. |
| `periodoFiscal` | string | Sí | Mes y año de la declaración, `MM/yyyy`, por ejemplo `10/2026`. |
| `parteRel` | string | Sí | `SI` si tú y el proveedor son partes relacionadas; si no, `NO`. |
| `tipoSujetoRetenido` | string | No | Clasificación del sujeto retenido, cuando el SRI la exige para una identificación del exterior. |
| `dirEstablecimiento` | string | No | Dirección del establecimiento emisor, hasta 300 caracteres. |
| `telefono` | string | No | Teléfono del proveedor, hasta 40 caracteres. |
| `correo` | string | No | Correo del proveedor al que enviamos el comprobante, hasta 500 caracteres. Si lo omites, se usa el `infoAdicional` llamado `email` o `correo`. |

La retención no usa `moneda`, `pagos` ni totales en `info`, y si los envías, la
API responde 422 con `Campo no soportado en este contrato.`

### `docsSustento`

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `codSustento` | string | Sí | Código de sustento, de 2 dígitos, que encuentras en [Códigos de sustento](/v1/guias/catalogos#codigos-de-sustento). El `10` se rechaza. |
| `codDocSustento` | string | Sí | Tipo del documento de sustento, de 2 dígitos, como `01` para una factura. Los valores están en [Tipos de documento de sustento](/v1/guias/catalogos#tipos-de-documento-de-sustento), y el `41` se rechaza. |
| `numDocSustento` | string | Sí | Número de la factura del proveedor, de 15 dígitos sin guiones, como `001001000000123`. También se acepta `ddd-ddd-ddddddddd`. |
| `fechaEmisionDocSustento` | string | Sí | Fecha de la factura del proveedor, `dd/MM/yyyy`. |
| `fechaRegistroContable` | string | Sí | Fecha en que registraste la factura en tu contabilidad, `dd/MM/yyyy`. |
| `numAutDocSustento` | string | No | Número de autorización de la factura del proveedor, de 10 a 49 dígitos; si es electrónica, su clave de acceso de 49 dígitos. |
| `pagoLocExt` | string | Sí | `01`, pago local, que es el único valor admitido. |
| `totalSinImpuestos` | number | Sí | Base de la factura del proveedor sin impuestos, con 2 decimales. |
| `importeTotal` | number | Sí | Total de la factura del proveedor, igual a `totalSinImpuestos` más la suma de `impuestosDocSustento[].valorImpuesto`. |
| `impuestosDocSustento` | array | Sí | 1 o 2 impuestos de la factura. Su detalle está en la tabla `docsSustento[].impuestosDocSustento`. |
| `retenciones` | array | Sí | De 1 a 1000 retenciones. Su detalle está en la tabla `docsSustento[].retenciones`. |
| `pagos` | array | Sí | De 1 a 20 formas de pago de la factura del proveedor. Su detalle está en la tabla `docsSustento[].pagos`. |

### `docsSustento[].impuestosDocSustento`

Los impuestos que trae la factura del proveedor, tal como aparecen en ella.

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `codImpuestoDocSustento` | string | Sí | Impuesto de la factura, `2` para IVA o `3` para ICE. Los valores están en [Impuestos](/v1/guias/catalogos#impuestos). |
| `codigoPorcentaje` | string | Sí | Código de la tarifa; `"4"` es IVA 15 %. Los valores están en [Tarifas de IVA](/v1/guias/catalogos#tarifas-de-iva). |
| `baseImponible` | number | Sí | Base del impuesto en la factura, con 2 decimales. |
| `tarifa` | number | Sí | Porcentaje de la tarifa, por ejemplo `15`. |
| `valorImpuesto` | number | Sí | Valor del impuesto en la factura, con 2 decimales. |

### `docsSustento[].retenciones`

Una fila por cada retención que practicas.

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `codigo` | string | Sí | Impuesto retenido, `1` para renta, `2` para IVA o `6` para ISD. |
| `codigoRetencion` | string | Sí | Código de la retención dentro de ese impuesto, por ejemplo `303` en renta o `3` en IVA, de hasta 5 caracteres. Los valores están en [Catálogos](/v1/guias/catalogos#retenciones-y-sustento). |
| `baseImponible` | number | Sí | Base de la retención. En renta, la base sin IVA; en IVA, el valor del IVA. Lleva 2 decimales. |
| `porcentajeRetener` | number | Sí | Porcentaje de retención, de 0 a 100, con 2 decimales como máximo y 3 dígitos en total (`100`, `70`, `10.5` y `2.75` son válidos; `12.75` no). En IVA debe corresponder al `codigoRetencion`. |
| `valorRetenido` | number | Sí | `baseImponible` x `porcentajeRetener` / 100, redondeado a 2 decimales. |

### `docsSustento[].pagos`

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `formaPago` | string | Sí | Código de 2 dígitos. Los valores están en [Formas de pago](/v1/guias/catalogos#formas-de-pago). |
| `total` | number | Sí | Importe pagado con esa forma. La suma de todos los `total` es igual a `importeTotal`. |
| `plazo` | number | No | Número entero mayor o igual a 0. |
| `unidadTiempo` | string | Condicional | Obligatoria si `plazo` es mayor que 0, por ejemplo `dias`, con hasta 20 caracteres. |

### `infoAdicional`

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `nombre` | string | Sí | Nombre del dato, hasta 300 caracteres. |
| `valor` | string | Sí | Valor del dato, hasta 300 caracteres. |

Estos datos aparecen en el [RIDE](/v1/guias/glosario), el PDF del comprobante.

## Reglas de cálculo y validaciones

Si alguna regla falla, la API responde 422 con el `codEstado` 3002 (`comprobante_invalido`), y `errores`
describe la regla y, cuando aplica, el campo, como en
`$.docsSustento[0]: Los totales y pagos del sustento no coinciden.` Un 422 consume 1 documento como intento, pero no usa un número de la serie, así que corrige el dato y reenvía.

| Regla | Ejemplo de incumplimiento |
|---|---|
| `importeTotal` = `totalSinImpuestos` + suma de `impuestosDocSustento[].valorImpuesto`. | `importeTotal` 115.00 con IVA 12.00 y base 100.00. |
| Suma de `pagos[].total` = `importeTotal`. | Pagos por 100.00 con `importeTotal` 115.00. |
| `valorRetenido` = `redondear(baseImponible x porcentajeRetener / 100, 2)`. | Base 15.00 al 30 % con `valorRetenido` 4.00 (debe ser 4.50). |
| `porcentajeRetener` está entre 0 y 100. | `porcentajeRetener: 110`. |
| `retenciones[].codigo` es `1`, `2` o `6`. | `codigo: "3"`. |
| `docsSustento` tiene exactamente un elemento. | Dos facturas en la misma retención. |
| `pagoLocExt` es `01` y `parteRel` es `SI` o `NO`. | `pagoLocExt: "02"`. |
| `codSustento` no es `10`, `codDocSustento` no es `41` y no hay códigos de banano. | `codDocSustento: "41"`. |
| `periodoFiscal` va en `MM/yyyy` y las fechas en `dd/MM/yyyy`. | `periodoFiscal: "2026-10"`. |
| `numAutDocSustento`, si lo envías, tiene de 10 a 49 dígitos. | Autorización de 5 dígitos. |
| El sujeto retenido está identificado; no se admite `07`. | Retención a consumidor final. |
| Los importes llevan como máximo 2 decimales y la API no los redondea por ti. | `valorRetenido: 10.005`. |

## Respuesta

Si la solicitud es válida, la API responde 202 Accepted. La retención quedó
**recibida**, pero todavía no tiene el resultado del SRI.

```json
{
  "estado": "recibido",
  "codEstado": 1001,
  "errores": [],
  "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
  "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
  "ambiente": 1,
  "tipoDocumento": "07",
  "numeroDocumento": "001-001-000000001",
  "referenciaExterna": "RET-2026-0001",
  "claveAcceso": null,
  "fhRecibido": "2026-11-16T10:15:00-05:00",
  "fhAutorizacion": null
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `estado` | string | `recibido`: el comprobante pasó nuestras validaciones y lo aceptamos. No es una autorización. Un reintento con la misma `Idempotency-Key` y el mismo cuerpo responde con el mismo `idOperacion` y el estado actual de la operación. Normalmente el 202 trae `recibido`, pero si el resultado ya se conoce al responder, trae directamente el estado final (`autorizado` con 2001, `rechazado` con 3xxx o `rechazo_configuracion` con 4xxx), con su `msgError` y su detalle en `errores`. Decide siempre por `estado` y `codEstado`. |
| `codEstado` | number | 1001 si el comprobante todavía no tiene clave de acceso, o 1002 si ya la tiene. Acepta los dos valores. |
| `errores` | array de string | Viene siempre; en una emisión recibida es una lista vacía, y con un resultado final trae su detalle. |
| `idOperacion` | string (UUID) | Identificador de la [operación](/v1/guias/glosario). Guárdalo, porque lo necesitas para el seguimiento. |
| `urlEstado` | string | URL completa del seguimiento, igual a la cabecera `Location`. Puedes llamarla tal como viene. |
| `numeroDocumento` | string o `null` | Número del comprobante con la forma `estab-ptoEmi-secuencial`, incluido el secuencial que te asignamos si no lo enviaste. |
| `claveAcceso` | string o `null` | Clave de acceso de 49 dígitos. Es `null` con el `codEstado` 1001; en ese caso la obtienes en el seguimiento o en el webhook. Con 1002 o con un resultado final ya viene en la respuesta. |
| `fhRecibido` | string | Fecha y hora en que recibimos la emisión, en ISO 8601 con zona horaria. |

Los demás campos, `ambiente`, `tipoDocumento`, `referenciaExterna` y `fhAutorizacion`, tienen la misma forma del [seguimiento de una operación](/v1/guias/consulta-operacion#respuesta), y el campo `msgError` solo aparece cuando el 202 ya trae un resultado final con error.

La respuesta trae además estas cabeceras:

| Cabecera | Descripción |
|---|---|
| `Location` | La misma URL completa que `urlEstado`. |
| `X-Correlation-Id` | Identificador de correlación de la solicitud. Cítalo al pedir soporte. |

Después de recibirla, sigue estos pasos:

1. Guarda `idOperacion` junto a la retención en tu sistema.
2. Consulta `GET /v1/operaciones/{idOperacion}`, como se explica en [Seguimiento de una operación](/v1/guias/consulta-operacion), o espera el [webhook](/v1/guias/webhooks).
3. Cuando su `estado` sea `autorizado`, la operación trae la `claveAcceso` real de 49 dígitos y puedes descargar el RIDE y el XML para entregarlos al proveedor. Si es `rechazado` o `rechazo_configuracion`, el `codEstado` te dice la causa y `errores` el detalle; corrígela y emite de nuevo con una `Idempotency-Key` nueva y una `referenciaExterna` nueva. Si el `codEstado` es 3001 (`rechazo_sri`), usa además el secuencial automático, como se explica en [Reintentos y duplicados](/v1/guias/emision#reintentos-y-duplicados).

## Estados de este endpoint

Esta tabla reúne las respuestas que puedes recibir al emitir un comprobante de
retención.

| `codEstado` | HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| 1001 o 1002 | 202 | La retención quedó recibida, o reintentaste con la misma `Idempotency-Key` y el mismo cuerpo. | Guarda `idOperacion` y sigue la operación; un reintento trae el estado actual. No reenvíes con otros datos. |
| 3003 (`solicitud_invalida`) | 400 | Falta `Idempotency-Key` o no es ASCII de hasta 128 caracteres, o el JSON o el XML está mal formado. | Corrige la solicitud según `errores` y reenvía. |
| 3002 (`comprobante_invalido`) | 422 | Falta un campo obligatorio, un campo tiene formato inválido o no se cumple una regla de la retención (totales del sustento, cálculo de la retención, límites del comprobante de retención, campo desconocido, `ruc` que no corresponde a la ruta). | Corrige el campo indicado en `errores`. Consume 1 documento como intento. |
| 3006 (`cuerpo_excedido`) | 413 | El cuerpo supera 2 MiB. | Reduce el número de retenciones o de `infoAdicional`. |
| 3009 (`credenciales_invalidas`) | 401 | La API Key falta o no es válida. | Revisa `X-Api-Key`. |
| 3010 (`ip_no_autorizada`) | 403 | En producción, la IP no está registrada para tu API Key o no se pudo identificar. El ambiente de pruebas acepta cualquier IP. | Registra tu IP en **Cuenta > IP permitidas** o revisa proxies entre tu sistema y la API. |
| 3011 (`acceso_denegado`) | 403 | El contribuyente de la ruta o el tipo `07` no están habilitados. | Verifica `GET /v1/contexto`; si falta el tipo, solicita habilitarlo. |
| 3004 (`comprobante_duplicado`) | 409 | Ya existe una retención con ese número (`estab`-`ptoEmi`-`secuencial`) autorizada, pendiente o rechazada por el SRI. | Consulta la existente. Si la anterior no se emitió (`document.failed`), puedes reenviar el mismo número con nueva `Idempotency-Key` y `referenciaExterna`; si la rechazó el SRI, emite con un secuencial nuevo. |
| 3005 (`conflicto_idempotencia`) | 409 | Usaste la misma `Idempotency-Key` con otro cuerpo, o una `referenciaExterna` que ya usó otro comprobante. | No cambies el cuerpo de un reintento. Para un comprobante nuevo, incluida la corrección de un rechazo, usa otra `Idempotency-Key` y otra `referenciaExterna`. |
| 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes por minuto. | Espera lo que indique `Retry-After` y reintenta con la misma `Idempotency-Key`. |
| 4004 (`cupo_agotado`) | 429 | Se agotó el cupo de documentos. | Revisa [`GET /v1/consumo`](/v1/guias/consumo) y compra un paquete. |
| 5002 (`servicio_no_disponible`) | 503 | El servicio no está disponible temporalmente. | Reintenta con la misma `Idempotency-Key` y el mismo cuerpo. |

Todos los errores traen la misma forma de la respuesta 202, con `msgError`, el detalle en `errores` y `idOperacion`, `urlEstado`, `numeroDocumento`, `claveAcceso` y las fechas en `null`. El catálogo completo está en [Errores](/v1/guias/errores#catalogo-de-codestado).

> [!WARNING]
> Ante un timeout, reintenta con la **misma** `Idempotency-Key` y el mismo cuerpo. Cambiar la clave o la `referenciaExterna` puede emitir dos retenciones sobre la misma factura.

## Siguientes pasos

- [Seguimiento de una operación](/v1/guias/consulta-operacion): consulta si el SRI autorizó la retención y obtiene su clave de acceso.
- [Catálogos](/v1/guias/catalogos#retenciones-y-sustento): códigos de retención, de sustento y tipos de documento de sustento.
- [Webhooks](/v1/guias/webhooks): recibe el resultado sin consultar periódicamente.
- [Liquidación de compra](/v1/guias/emision-03): documenta compras a proveedores que no emiten factura.
