Guía · Contribuyentes especiales

Cómo consultar si un RUC es contribuyente especial

Publicado el

La calificación de contribuyente especial puede influir en procesos contables, tributarios y de facturación. Por eso conviene comprobarla antes de registrar o actualizar un cliente o proveedor.

Esta guía explica cómo verificarla gratis desde EcuadorAPI y cómo automatizar la consulta mediante un endpoint específico.

Qué significa ser contribuyente especial

Un contribuyente especial es una persona o entidad calificada como tal por la administración tributaria. Esta condición es distinta del tipo de contribuyente y de la designación de agente de retención.

Un mismo RUC puede tener ambas calificaciones, solo una o ninguna. Consulta cada dato por separado y vuelve a verificarlo cuando su vigencia sea importante.

Cómo consultarlo gratis desde la página

  • Abre la página para consultar contribuyentes especiales.
  • Ingresa los 13 dígitos del RUC, sin espacios ni guiones.
  • Presiona Consultar y revisa si el resultado indica que consta como contribuyente especial.
  • Confirma la razón social y el estado para asegurarte de que verificaste el RUC correcto.

Cómo consultarlo mediante la API

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

La respuesta usa claves en inglés. is_special_taxpayer es true cuando el RUC consta como contribuyente especial y false cuando no consta.

EndpointGET /api/v1/rucs/{ruc}/contribuyente-especial

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/contribuyente-especial" \
  --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/contribuyente-especial", {
  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/contribuyente-especial",
    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/contribuyente-especial");
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_special_taxpayer": 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_special_taxpayer 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: la calificación tributaria puede actualizarse.
Haz la consulta gratis
Ingresa un RUC y comprueba su calificación de contribuyente especial.

Preguntas frecuentes

Respuestas rápidas sobre esta guía.

Más guías

Continúa explorando otros temas relacionados.

Ver todas las guías