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
razonSocialCompradorconrazonSocial, o connombreCompletosi la razón social no viene. - Revisar a un proveedor antes de emitir una retención o una liquidación de
compra. Comprueba que
estadoseaACTIVOy leeagenteRetencion,contribuyenteEspecialyobligadoLlevarContabilidad, 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#
- Validar identificación: comprueba el dígito verificador antes de consultar o de emitir.
- Contribuyentes por nombre: encuentra la identificación cuando solo conoces el nombre.
- Factura: usa los datos consultados para llenar al comprador.
- Errores: catálogo completo de códigos y qué hacer ante cada uno.