Guía · Agentes de retención

Cómo consultar si un RUC es agente de retención

Publicado el

Antes de registrar un proveedor o preparar un proceso tributario puede ser necesario comprobar si un RUC consta como agente de retención.

Esta guía explica cómo hacer la verificación desde EcuadorAPI y cómo automatizar la misma consulta mediante un endpoint específico.

Qué significa ser agente de retención

Un agente de retención es un contribuyente que debe retener determinados impuestos en los casos establecidos por la normativa tributaria. Esta condición es distinta del tipo de contribuyente y de la calificación de contribuyente especial.

La calificación puede cambiar con el tiempo. Por eso conviene verificarla cuando vas a usarla en una decisión contable, tributaria o de facturación.

Cómo consultarlo desde la página

  • Abre la página para consultar agentes de retención.
  • Ingresa los 13 dígitos del RUC, sin espacios ni guiones.
  • Presiona Consultar y revisa si el resultado indica que consta como agente de retención.
  • Confirma también la razón social y el estado del contribuyente para evitar consultar el RUC equivocado.

Cómo consultarlo mediante la API

Envía una solicitud GET a /api/v1/rucs/{ruc}/agente-retencion y autentícala con tu API key en el encabezado Authorization.

La respuesta usa claves en inglés y valores legibles. is_withholding_agent es true cuando el RUC consta como agente de retención y false cuando no consta.

EndpointGET /api/v1/rucs/{ruc}/agente-retencion

El ejemplo usa un identificador ficticio. Reemplázalo por el dato que necesitas consultar.

Solicitud
curl --request GET "https://api.ecuadorapi.com/api/v1/rucs/1790012345001/agente-retencion" \
  --header "Authorization: Bearer $ECUADORAPI_KEY" \
  --header "Accept: application/json" \
  --fail-with-body \
  --max-time 60
const response = await fetch("https://api.ecuadorapi.com/api/v1/rucs/1790012345001/agente-retencion", {
  headers: {
    Authorization: "Bearer " + process.env.ECUADORAPI_KEY,
    Accept: "application/json",
  },
  signal: AbortSignal.timeout(60_000),
})
const contentType = response.headers.get("content-type") ?? ""
const body = contentType.includes("json")
  ? await response.json().catch(() => null)
  : null

if (!response.ok || body?.error) {
  throw new Error(body?.message ?? "Request failed: " + response.status)
}

if (!body || !("data" in body)) {
  throw new Error("API returned an invalid response")
}

const result = body.data
// Use result in your server-side flow. Avoid logging personal responses.
import os, requests

response = requests.get(
    "https://api.ecuadorapi.com/api/v1/rucs/1790012345001/agente-retencion",
    headers={
        "Authorization": f"Bearer {os.environ['ECUADORAPI_KEY']}",
        "Accept": "application/json",
    },
    timeout=60,
)
content_type = response.headers.get("content-type", "")

try:
    body = response.json() if "json" in content_type else None
except requests.exceptions.JSONDecodeError:
    body = None

if not response.ok or (isinstance(body, dict) and body.get("error")):
    message = body.get("message") if isinstance(body, dict) else None
    raise RuntimeError(message or f"Request failed: {response.status_code}")

if not isinstance(body, dict) or "data" not in body:
    raise RuntimeError("API returned an invalid response")

data = body["data"]
# Use data in your server-side flow. Avoid logging personal responses.
$ch = curl_init("https://api.ecuadorapi.com/api/v1/rucs/1790012345001/agente-retencion");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("ECUADORAPI_KEY"),
    "Accept: application/json",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 60);
$rawBody = curl_exec($ch);

if ($rawBody === false) {
    $transportError = curl_error($ch);
    curl_close($ch);
    throw new RuntimeException("Request transport failed: " . $transportError);
}

$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$body = json_decode($rawBody, true);

if (!is_array($body)) {
    throw new RuntimeException("API returned invalid JSON");
}

if ($statusCode >= 400 || ($body["error"] ?? false)) {
    throw new RuntimeException(
        ($body["message"] ?? null) ?: "Request failed: " . $statusCode
    );
}

if (!array_key_exists("data", $body)) {
    throw new RuntimeException("API returned an invalid response");
}

$data = $body["data"];
// Use $data in your server-side flow. Avoid logging personal responses.

Respuesta de ejemplo · 200 OK

JSON ficticio con la misma estructura que devuelve la API. Verlo o copiarlo no consume saldo.

{
  "data": {
    "id": "1790012345001",
    "business_name": "EJEMPLO COMERCIAL S.A.",
    "status": "ACTIVO",
    "is_withholding_agent": true,
    "fetched_at": "2026-09-14T16:00:00Z"
  },
  "error": null,
  "message": null
}
Ver campos, precio vigente y referencia del endpoint

Cómo interpretar la respuesta

  • id es el RUC que se verificó.
  • business_name permite confirmar la razón social consultada.
  • status muestra el estado tributario disponible del contribuyente.
  • is_withholding_agent contiene el resultado booleano de la verificación.
  • fetched_at indica cuándo se obtuvo la información.

Errores y buenas prácticas

  • Valida que el RUC tenga exactamente 13 dígitos antes de llamar al endpoint.
  • Maneja un 400 como formato inválido y un 404 como RUC sin información disponible.
  • Reintenta los errores temporales con espera progresiva, sin enviar ráfagas de solicitudes.
  • No guardes el resultado indefinidamente: vuelve a consultarlo cuando la vigencia sea importante.
Haz la consulta ahora
Ingresa un RUC y comprueba su condición de agente de retención.

Preguntas frecuentes

Respuestas rápidas sobre esta guía.

Más guías

Continúa explorando otros temas relacionados.

Ver todas las guías