Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
En esta página

Contribuyente por identificación GET

Consulta en el catastro del SRI los datos de un contribuyente a partir de su cédula, RUC o pasaporte.

Con este endpoint puedes buscar a un contribuyente en el catastro público del SRI por su cédula, RUC o pasaporte, y obtener su razón social, su estado, su régimen tributario, sus establecimientos y otros datos registrados.

Te sirve para llenar los datos de un comprador o un proveedor sin errores de tipeo, o para revisar su situación antes de emitirle un comprobante. Al terminar esta página sabrás qué datos devuelve la consulta y cómo tolerar los que vienen vacíos.

Importante

Ambiente de pruebas: sin validez fiscal. Los ejemplos usan la URL de pruebas. La consulta lee el catastro público del SRI en ambos ambientes, así que los datos que devuelve son los reales del catastro.

Endpoint#

GET /v1/consultas/contribuyentes/{identificacion}
X-Api-Key: <tu API Key>
Cabecera Obligatoria Descripción
X-Api-Key Sí Tu API Key.
X-Api-Version No Versión del contrato. Si la omites, se usa la vigente.

La respuesta es un objeto JSON con los campos en el primer nivel. Esta consulta no consume cupo de documentos, pero sí cuenta para el límite de solicitudes por minuto de tu API Key, que se explica en Límites.

Cuándo usarlo#

  • Autocompletar al comprador al facturar. Tu usuario escribe la cédula o el RUC del cliente y tu sistema llena razonSocialComprador con razonSocial, o con nombreCompleto si la razón social no viene.
  • Revisar a un proveedor antes de emitir una retención o una liquidación de compra. Comprueba que estado sea ACTIVO y lee agenteRetencion, contribuyenteEspecial y obligadoLlevarContabilidad, que tu área contable usa para decidir los porcentajes.
  • Mantener actualizada tu ficha de clientes y proveedores, con las direcciones de sus establecimientos, sus representantes legales y su fecha de cese.

Si solo necesitas saber si el número está bien escrito, es decir, si su dígito verificador es correcto, puedes usar Validar identificación. Esa consulta no depende del SRI y te responde más rápido.

Antes de empezar#

  • Una API Key de pruebas guardada en la variable de entorno ECUAFACT_API_KEY. Si todavía no tienes una, crea un sandbox; cómo viaja la API Key se explica en Autenticación.
  • Solo en producción, la IP pública de salida de tu servidor registrada para tu integración. El sandbox acepta cualquier IP. Si no sabes cómo hacerlo, sigue Registra tu IP.
  • Para ver datos reales, una cédula o un RUC que exista en el catastro del SRI, por ejemplo el RUC de tu empresa.

Parámetros#

Nombre Dónde Tipo Obligatorio Descripción
identificacion ruta string Sí Cédula de 10 dígitos, RUC de 13 dígitos o pasaporte. La API elimina los espacios al inicio y al final.
fusionar consulta boolean No Con true, el valor por defecto, combina los datos de todas las fuentes disponibles. Con false devuelve los datos de la primera fuente que responda, lo que es más rápido pero puede traer menos campos. Solo acepta true o false; con otro valor la API responde 400 con el codEstado 3003 (solicitud_invalida).
fuente consulta string No Todas, el valor por defecto, o SriCatastro para consultar solo el catastro del SRI. No distingue mayúsculas. Con otro valor la API responde 400 con el codEstado 3012 (filtros_invalidos).

Ejemplo#

El RUC 0123456789001 es el identificador de prueba de esta documentación y no existe en el catastro; para ver datos reales, reemplázalo por el RUC de tu propia empresa.

curl -s "https://api-sandbox.mynexusapi.com/v1/consultas/contribuyentes/0123456789001?fusionar=true" \
  -H "X-Api-Key: $ECUAFACT_API_KEY"
using System.Net.Http;

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 HttpResponseMessage respuesta = await http.GetAsync("/v1/consultas/contribuyentes/0123456789001?fusionar=true");
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
import os
import requests

r = requests.get(
    "https://api-sandbox.mynexusapi.com/v1/consultas/contribuyentes/0123456789001",
    headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]},
    params={"fusionar": "true"},
    timeout=30,
)
print(r.status_code, r.text)
// Node.js 18 o superior. Guarda como ejemplo.mjs y ejecuta: node ejemplo.mjs
const res = await fetch('https://api-sandbox.mynexusapi.com/v1/consultas/contribuyentes/0123456789001?fusionar=true', {
  headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY }
});
console.log(res.status, await res.text());
<?php
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/consultas/contribuyentes/0123456789001?fusionar=true');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')],
]);
$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;

// 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/consultas/contribuyentes/0123456789001?fusionar=true"))
    .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
    .GET()
    .build();
HttpResponse<String> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString());
System.out.println(respuesta.statusCode() + " " + respuesta.body());
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

using EcuafactClient client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});

ContribuyenteConsulta contribuyente = await client.ConsultarContribuyenteAsync("0123456789001", fusionar: true);
Console.WriteLine(contribuyente.RazonSocial + " " + contribuyente.Estado);
import os
from ecuafact import EcuafactClient, EcuafactClientOptions

client = EcuafactClient(EcuafactClientOptions(
    base_address="https://api-sandbox.mynexusapi.com/",
    api_key=os.environ["ECUAFACT_API_KEY"],
))

contribuyente = client.consultar_contribuyente("0123456789001", fusionar=True)
print(contribuyente.razon_social, contribuyente.estado)
// Node.js 18 o superior. Guarda como ejemplo.mjs y ejecuta: node ejemplo.mjs
import { EcuafactClient } from "@ecuafact/sdk";

const client = new EcuafactClient({
  baseAddress: "https://api-sandbox.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY
});

const contribuyente = await client.consultarContribuyente("0123456789001", true);
console.log(contribuyente.razonSocial, contribuyente.estado);
<?php
require 'vendor/autoload.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'),
));

$contribuyente = $client->consultarContribuyente('0123456789001', true);
echo $contribuyente->razonSocial . ' ' . $contribuyente->estado . PHP_EOL;
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.contracts.ContribuyenteConsulta;

// 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")));

ContribuyenteConsulta contribuyente = client.consultarContribuyente("0123456789001", true, null);
System.out.println(contribuyente.razonSocial() + " " + contribuyente.estado());
# Resultado esperado: con un RUC que existe en el catastro, sus datos en tabla.
# Con el RUC de prueba 0123456789001, un error 404 con el `codEstado` 3013 (`no_encontrado`).
ecuafact ruc consultar 0123456789001 --entorno sandbox

Con un RUC que existe en el catastro, el resultado esperado es un 200 con el objeto que se describe en la sección siguiente. Con 0123456789001 recibes un 404 con el codEstado 3013 (no_encontrado) y el mensaje "Recurso no encontrado.".

Respuesta#

La API responde 200 OK. Los valores de este ejemplo son ilustrativos, porque los reales dependen de lo que devuelva el catastro del SRI en el momento de la consulta.

{
  "identificacion": "0123456789001",
  "tipoIdentificacion": "RucPersonaNatural",
  "nombreCompleto": "CONTRIBUYENTE DE PRUEBA",
  "razonSocial": "CONTRIBUYENTE DE PRUEBA",
  "nombreComercial": "COMERCIAL DE PRUEBA",
  "clase": "PersonaNatural",
  "estado": "ACTIVO",
  "regimen": "GENERAL",
  "actividadEconomicaPrincipal": "VENTA AL POR MENOR DE ARTICULOS DE OFICINA",
  "obligadoLlevarContabilidad": false,
  "agenteRetencion": false,
  "contribuyenteEspecial": false,
  "fechaInicioActividades": "2015-03-02T00:00:00",
  "fechaCese": null,
  "fechaReinicioActividades": null,
  "fechaActualizacion": "2026-01-15T00:00:00",
  "representantesLegales": [],
  "establecimientos": [
    {
      "numero": "001",
      "nombreComercial": "COMERCIAL DE PRUEBA",
      "tipo": "MATRIZ",
      "direccionCompleta": "AV. DE PRUEBA 123 Y CALLE FICTICIA",
      "estado": "ABIERTO",
      "esMatriz": true
    }
  ],
  "estadoTributario": {
    "tieneDeuda": false,
    "tieneImpugnacion": false,
    "tieneRemision": false,
    "resumenDeuda": null,
    "resumenImpugnacion": null,
    "resumenRemision": null,
    "consultadoEn": "2026-10-07T08:00:00"
  },
  "fuenteOrigen": "SriCatastro",
  "consultadoEn": "2026-10-07T08:00:00"
}

Cualquier campo puede venir null cuando la fuente no tiene el dato, así que programa tu integración para tolerarlo. Por ejemplo, nombreComercial es null en muchas personas naturales.

Campo Tipo Descripción
identificacion string Identificación consultada.
tipoIdentificacion string Tipo detectado: Cedula, RucPersonaNatural, RucSociedadPrivada, RucSociedadPublica, Pasaporte o Desconocido.
nombreCompleto string Nombre de la persona natural o razón social de la sociedad. Úsalo cuando razonSocial venga null.
razonSocial string Razón social registrada. Es el valor recomendado para razonSocialComprador o razonSocialProveedor.
nombreComercial string Nombre comercial, si existe.
clase string PersonaNatural, Sociedad o SociedadPublica.
estado string Estado en el catastro, tal como lo publica el SRI, por ejemplo ACTIVO. Compara contra ACTIVO y trata cualquier otro texto como "no activo".
regimen string Régimen tributario, tal como lo publica el SRI.
actividadEconomicaPrincipal string Descripción de la actividad económica principal.
obligadoLlevarContabilidad boolean true si está obligado a llevar contabilidad.
agenteRetencion boolean true si es agente de retención.
contribuyenteEspecial boolean true si es contribuyente especial.
fechaInicioActividades string Fecha y hora de inicio de actividades, en formato yyyy-MM-ddTHH:mm:ss y sin zona horaria.
fechaCese string Fecha de cese de actividades. Vale null si sigue activo.
fechaReinicioActividades string Fecha de reinicio de actividades. Vale null si no aplica.
fechaActualizacion string Última actualización de los datos en el catastro.
representantesLegales array Representantes legales, que suelen venir en las sociedades. Puede ser [] o null.
representantesLegales[].identificacion string Identificación del representante.
representantesLegales[].nombre string Nombre del representante.
establecimientos array Establecimientos del contribuyente, con el mismo formato que en Establecimientos de un RUC.
establecimientos[].numero string Código del establecimiento, de 3 dígitos, por ejemplo 001. Es el valor que usas en infoTributaria.estab.
establecimientos[].nombreComercial string Nombre comercial del establecimiento.
establecimientos[].tipo string Tipo, tal como lo publica el SRI, por ejemplo MATRIZ. Para decidir si es la matriz, usa esMatriz.
establecimientos[].direccionCompleta string Dirección registrada.
establecimientos[].estado string ABIERTO o CERRADO.
establecimientos[].esMatriz boolean true si es la matriz.
estadoTributario object Situación de deudas, impugnaciones y remisiones. Puede venir null.
estadoTributario.tieneDeuda boolean true si registra deudas.
estadoTributario.tieneImpugnacion boolean true si registra impugnaciones.
estadoTributario.tieneRemision boolean true si registra remisiones.
estadoTributario.resumenDeuda string Resumen de la deuda, si existe.
estadoTributario.resumenImpugnacion string Resumen de la impugnación, si existe.
estadoTributario.resumenRemision string Resumen de la remisión, si existe.
estadoTributario.consultadoEn string Momento en que se obtuvo el estado tributario.
fuenteOrigen string Fuente que aportó los datos, por ejemplo SriCatastro.
consultadoEn string Momento de la consulta.

Estados de este endpoint#

Los errores tienen el formato de cualquier error de la API, con los campos estado, codEstado, msgError y errores. En los errores de validación, errores trae el detalle de cada problema, como en este ejemplo; en los demás viene como una lista vacía.

{
  "estado": "rechazado",
  "codEstado": 3012,
  "msgError": "Filtros inválidos.",
  "errores": [
    "fuente debe ser Todas o SriCatastro."
  ]
}
codEstado HTTP Cuándo ocurre Qué hacer
- 200 La consulta encontró al contribuyente. Lee los datos.
3003 (solicitud_invalida) 400 La identificación tiene un formato que la fuente no acepta, o fusionar no es true ni false. Corrige la identificación o el parámetro.
3012 (filtros_invalidos) 400 fuente no es Todas ni SriCatastro. Corrige fuente u omítelo.
3007 (version_no_soportada) 400 Enviaste X-Api-Version con una versión no admitida. Quita la cabecera o envía la versión vigente.
3009 (credenciales_invalidas) 401 Falta la API Key o es inválida. Revisa X-Api-Key, como se explica en Autenticación.
3010 (ip_no_autorizada) 403 En producción, la IP de la que sale la llamada no está registrada o no se pudo identificar. El sandbox no lo devuelve. Registra tu IP en Cuenta > IP permitidas o revisa los proxies o balanceadores entre tu servidor y la API.
3011 (acceso_denegado) 403 Tu API Key está limitada y no incluye el scope sri:consultar. Crea una API Key con ese scope en Cuenta > API Keys.
3013 (no_encontrado) 404 La identificación no existe en el catastro o ninguna fuente tuvo resultado. Verifica el número y, si el usuario lo escribió, pídele que lo confirme.
5005 (limite_solicitudes) 429 Superaste el límite de solicitudes de tu API Key o la fuente limitó las consultas. Espera los segundos que indica Retry-After y reintenta.
5001 (error_interno) 500 Ocurrió un error interno. Reintenta con una espera y, si persiste, reporta el valor de X-Correlation-Id.
5003 (error_dependencia) 502 La fuente de datos reportó un error o no está disponible. Reintenta con una espera creciente, por ejemplo de 5, 15 y 60 segundos.
5002 (servicio_no_disponible) 503 El servicio de consultas no está disponible temporalmente. Espera los segundos que indica Retry-After y reintenta.
5004 (tiempo_agotado) 504 La fuente no respondió a tiempo. Reintenta con una espera. Si necesitas una respuesta más rápida, prueba con fusionar=false.

El catálogo completo de codEstado está en Errores.

Siguientes pasos#

No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

No se pudo conectar. Revisa tu conexión y vuelve a intentarlo.

La sesión ya no está disponible. Recarga la página para continuar.

La sesión está en pausa. Puedes reanudarla para continuar.

No se pudo reanudar la sesión. Vuelve a intentarlo o recarga la página.

Al recargar se perderán los cambios que no hayas guardado.