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

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.

curl "https://api.ecuadorapi.com/api/v1/rucs/1790012345001/agente-retencion" \
  -H "Authorization: Bearer $ECUADORAPI_KEY"

const response = await fetch("https://api.ecuadorapi.com/api/v1/rucs/1790012345001/agente-retencion", {
  headers: {
    Authorization: "Bearer " + process.env.ECUADORAPI_KEY,
  },
})
const { data } = await response.json()

import os
import requests

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

$ch = curl_init("https://api.ecuadorapi.com/api/v1/rucs/1790012345001/agente-retencion");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("ECUADORAPI_KEY")],
    CURLOPT_RETURNTRANSFER => true,
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
$data = $body["data"];

{
  "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
}

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.