En esta página
Comprobante de retención POST
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.
Importante
Ambiente de pruebas: sin validez fiscal. Los ejemplos usan https://api-sandbox.mynexusapi.com y los 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.
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.
- 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
codigo1. - 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
codigo2. - Documento de sustento: el comprobante del proveedor sobre el que retienes,
normalmente su factura. Lo describes en
docsSustentocon 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 ejemplo01, 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. - 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.
- El valor
identificacionde tu contribuyente, que obtienes conGET /v1/contexto. En los ejemplos es0123456789001. - El tipo
07habilitado para ese contribuyente, es decir, que aparezca entiposComprobantedel 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.
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.
{
"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.
Nota
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.
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}
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()}");
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)
// 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
$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;
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());
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}");
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}")
// 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
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;
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());
# 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, 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, 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. 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. 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, 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. |
codigoPorcentaje |
string | Sí | Código de la tarifa; "4" es IVA 15 %. Los valores están en 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. |
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. |
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, 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.
{
"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. 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, 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:
- Guarda
idOperacionjunto a la retención en tu sistema. - Consulta
GET /v1/operaciones/{idOperacion}, como se explica en Seguimiento de una operación, o espera el webhook. - Cuando su
estadoseaautorizado, la operación trae laclaveAccesoreal de 49 dígitos y puedes descargar el RIDE y el XML para entregarlos al proveedor. Si esrechazadoorechazo_configuracion, elcodEstadote dice la causa yerroresel detalle; corrígela y emite de nuevo con unaIdempotency-Keynueva y unareferenciaExternanueva. Si elcodEstadoes 3001 (rechazo_sri), usa además el secuencial automático, como se explica en 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 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.
Atención
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: consulta si el SRI autorizó la retención y obtiene su clave de acceso.
- Catálogos: códigos de retención, de sustento y tipos de documento de sustento.
- Webhooks: recibe el resultado sin consultar periódicamente.
- Liquidación de compra: documenta compras a proveedores que no emiten factura.