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.
GET /api/v1/rucs/{ruc}/agente-retencionEl ejemplo usa un identificador ficticio. Reemplázalo por el dato que necesitas consultar.
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 60const 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
}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.
Preguntas frecuentes
Respuestas rápidas sobre esta guía.