<!-- source_url: https://docs.mynexusapi.com/v1/guias/consulta-contribuyente | last_updated: 2026-11-18 -->

# Contribuyente por identificación

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](/v1/guias/glosario) en el
catastro público del [SRI](/v1/guias/glosario) 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.

> [!IMPORTANT]
> 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](/v1/guias/glosario). |
| `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](/v1/guias/limites).

## 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](/v1/guias/glosario), 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](/v1/guias/consulta-identificacion). 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](/v1/guias/sandbox);
  cómo viaja la API Key se explica en [Autenticación](/v1/guias/autenticacion).
- [ ] 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](/v1/guias/autenticacion#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.

```bash
curl -s "https://api-sandbox.mynexusapi.com/v1/consultas/contribuyentes/0123456789001?fusionar=true" \
  -H "X-Api-Key: $ECUAFACT_API_KEY"
```

```csharp
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()}");
```

```python
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)
```

```javascript
// 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
<?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;
```

```java
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());
```

```csharp-sdk
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);
```

```python-sdk
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)
```

```javascript-sdk
// 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-sdk
<?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;
```

```java-sdk
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());
```

```bash-cli
# 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.

```json
{
  "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](/v1/guias/consulta-establecimientos). |
| `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.

```json
{
  "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](/v1/guias/autenticacion). |
| 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](/v1/guias/errores#catalogo-de-codestado).

## Siguientes pasos

- [Validar identificación](/v1/guias/consulta-identificacion): comprueba el dígito verificador antes de consultar o de emitir.
- [Contribuyentes por nombre](/v1/guias/consulta-contribuyente-nombre): encuentra la identificación cuando solo conoces el nombre.
- [Factura](/v1/guias/emision-01): usa los datos consultados para llenar al comprador.
- [Errores](/v1/guias/errores): catálogo completo de códigos y qué hacer ante cada uno.
