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

# Contribuyentes por nombre

Busca contribuyentes en el catastro del SRI por apellidos y nombres, o por el inicio de su razón social, y devuelve sus identificaciones.

A veces solo conoces el nombre de un cliente o un proveedor y necesitas su
cédula o su RUC. Con este endpoint puedes buscar ese nombre en el catastro
público del [SRI](/v1/guias/glosario) y obtener las coincidencias, cada una
con su identificación, su clase y su estado.

Al terminar esta página sabrás cómo escribir la búsqueda para personas y para
sociedades, cómo leer las coincidencias y qué hacer cuando no hay resultados.

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal. Los ejemplos usan la URL de pruebas.
> La búsqueda lee el catastro público del SRI en ambos ambientes.

## Endpoint

```
GET /v1/consultas/contribuyentes?apellidos={apellidos}&nombres={nombres}&clase={clase}&max={max}
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 **arreglo** de coincidencias en el primer nivel del JSON.
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

- **Dar de alta a un cliente o proveedor del que solo tienes el nombre.** Busca
  por nombre, muestra las coincidencias a tu usuario y, cuando elija una, guarda
  su `identificacion`. Después completa la ficha con
  [Contribuyente por identificación](/v1/guias/consulta-contribuyente).
- **Corregir identificaciones mal registradas** en tu ERP, comparando el nombre
  con el catastro.

Te recomendamos no usar esta búsqueda para elegir automáticamente al comprador
de un comprobante, porque puede haber varias personas con el mismo nombre.
Deja que tu usuario confirme la coincidencia.

## 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).

## Parámetros

| Nombre | Dónde | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
| `apellidos` | consulta | string | Sí | Para personas naturales, sus apellidos, por ejemplo `PEREZ LOPEZ`. Para sociedades, el **inicio** de la razón social, por ejemplo `COMERCIAL DE`; un fragmento del medio o del final puede no encontrar coincidencias. Si falta o está vacío, la API responde 400 con el `codEstado` 3012 (`filtros_invalidos`). |
| `nombres` | consulta | string | No | Nombres de la persona natural, por ejemplo `JUAN`. Sirve para acotar la búsqueda. |
| `clase` | consulta | string | No | `PersonaNatural`, el valor por defecto, `Sociedad` o `SociedadPublica`. No distingue mayúsculas. Con otro valor la API responde 400 con el `codEstado` 3012 (`filtros_invalidos`). Para buscar una empresa privada, envía `Sociedad`. |
| `max` | consulta | integer | No | Número máximo de coincidencias, de 1 a 30. Por defecto es 10. Fuera de ese rango la API responde 400 con el `codEstado` 3012 (`filtros_invalidos`), y con un valor que no es entero responde 400 con el `codEstado` 3003 (`solicitud_invalida`). |

Codifica los valores para la URL; por ejemplo, el espacio se escribe `%20`,
como en `PEREZ%20LOPEZ`. Si usas nuestros SDK o las bibliotecas HTTP de los
ejemplos de Python, la codificación se hace por ti.

## Ejemplo

Los nombres del ejemplo son genéricos, así que la respuesta depende de lo que
haya en el catastro real.

```bash
curl -s "https://api-sandbox.mynexusapi.com/v1/consultas/contribuyentes?apellidos=PEREZ%20LOPEZ&nombres=JUAN&clase=PersonaNatural&max=10" \
  -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);

string ruta = "/v1/consultas/contribuyentes?apellidos=" + Uri.EscapeDataString("PEREZ LOPEZ")
    + "&nombres=" + Uri.EscapeDataString("JUAN") + "&clase=PersonaNatural&max=10";
using HttpResponseMessage respuesta = await http.GetAsync(ruta);
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",
    headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]},
    params={"apellidos": "PEREZ LOPEZ", "nombres": "JUAN", "clase": "PersonaNatural", "max": 10},
    timeout=30,
)
print(r.status_code, r.text)
```

```javascript
// Node.js 18 o superior. Guarda como ejemplo.mjs y ejecuta: node ejemplo.mjs
const consulta = new URLSearchParams({ apellidos: 'PEREZ LOPEZ', nombres: 'JUAN', clase: 'PersonaNatural', max: '10' });
const res = await fetch('https://api-sandbox.mynexusapi.com/v1/consultas/contribuyentes?' + consulta, {
  headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY }
});
console.log(res.status, await res.text());
```

```php
<?php
$url = 'https://api-sandbox.mynexusapi.com/v1/consultas/contribuyentes?'
    . http_build_query(['apellidos' => 'PEREZ LOPEZ', 'nombres' => 'JUAN', 'clase' => 'PersonaNatural', 'max' => 10], '', '&', PHP_QUERY_RFC3986);
$ch = curl_init($url);
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.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

// Dentro de: public static void main(String[] args) throws Exception
String apellidos = URLEncoder.encode("PEREZ LOPEZ", StandardCharsets.UTF_8).replace("+", "%20");
HttpClient cliente = HttpClient.newHttpClient();
HttpRequest peticion = HttpRequest.newBuilder()
    .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/consultas/contribuyentes?apellidos=" + apellidos
        + "&nombres=JUAN&clase=PersonaNatural&max=10"))
    .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")!
});

IReadOnlyList<BusquedaContribuyente> encontrados =
    await client.BuscarContribuyentesAsync("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10);
foreach (BusquedaContribuyente c in encontrados)
{
    Console.WriteLine(c.Identificacion + " " + c.NombreCompleto);
}
```

```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"],
))

encontrados = client.buscar_contribuyentes("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10)
for contribuyente in encontrados:
    print(contribuyente.identificacion, contribuyente.nombre_completo)
```

```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 encontrados = await client.buscarContribuyentes("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10);
for (const contribuyente of encontrados) {
  console.log(contribuyente.identificacion, contribuyente.nombreCompleto);
}
```

```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'),
));

$encontrados = $client->buscarContribuyentes('PEREZ LOPEZ', 'JUAN', 'PersonaNatural', 10);
foreach ($encontrados as $contribuyente) {
    echo $contribuyente->identificacion . ' ' . $contribuyente->nombreCompleto . PHP_EOL;
}
```

```java-sdk
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.contracts.BusquedaContribuyente;
import java.util.List;

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

List<BusquedaContribuyente> encontrados = client.buscarContribuyentes("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10);
for (BusquedaContribuyente contribuyente : encontrados) {
    System.out.println(contribuyente.identificacion() + " " + contribuyente.nombreCompleto());
}
```

```bash-cli
# Resultado esperado: hasta 10 coincidencias con su identificación y nombre, en tabla.
ecuafact ruc buscar --apellidos "PEREZ LOPEZ" --nombres JUAN --clase PersonaNatural --max 10 --entorno sandbox
```

El resultado esperado es un 200 con un arreglo de hasta `max` coincidencias.

## Respuesta

La API responde `200 OK`. Los valores de este ejemplo son ilustrativos.

```json
[
  {
    "identificacion": "0123456789",
    "tipoIdentificacion": "Cedula",
    "nombreCompleto": "PEREZ LOPEZ JUAN CARLOS",
    "clase": "PersonaNatural",
    "estado": "ACTIVO",
    "fuenteOrigen": "SriCatastro"
  }
]
```

Cada elemento del arreglo trae estos campos, y cualquiera puede venir `null` si
la fuente no tiene el dato.

| Campo | Tipo | Descripción |
|---|---|---|
| `identificacion` | string | Cédula, RUC o pasaporte del contribuyente encontrado. Guárdala para consultas posteriores. |
| `tipoIdentificacion` | string | `Cedula`, `RucPersonaNatural`, `RucSociedadPrivada`, `RucSociedadPublica`, `Pasaporte` o `Desconocido`. |
| `nombreCompleto` | string | Nombre de la persona natural o razón social. |
| `clase` | string | `PersonaNatural`, `Sociedad` o `SociedadPublica`. |
| `estado` | string | Estado en el catastro, tal como lo publica el SRI, por ejemplo `ACTIVO`. |
| `fuenteOrigen` | string | Fuente que aportó el dato, por ejemplo `SriCatastro`. |

Cuando no hay coincidencias, la respuesta puede ser un 200 con un arreglo
vacío (`[]`) o un 404 con el `codEstado` 3013 (`no_encontrado`), según lo que informe la fuente. Trata
ambos casos como "sin resultados".

## Estados de este endpoint

| `codEstado` | HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| - | 200 | La búsqueda se realizó, con o sin coincidencias. | Lee el arreglo; un `[]` significa que no hubo resultados. |
| 3012 (`filtros_invalidos`) | 400 | Falta `apellidos`, `clase` no es un valor permitido o `max` está fuera de 1 a 30. El detalle llega en `errores`, por ejemplo `["max debe estar entre 1 y 30."]`. | Corrige los parámetros. |
| 3003 (`solicitud_invalida`) | 400 | `max` no es un número entero, o la fuente rechazó el formato de la búsqueda. | Corrige los parámetros. |
| 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 fuente no encontró coincidencias. | Prueba con menos palabras en `apellidos` o sin `nombres`. |
| 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. Si buscas mientras el usuario escribe, espera a que termine, por ejemplo 400 ms sin teclear, antes de llamar. |
| 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. |

El catálogo completo de `codEstado` está en [Errores](/v1/guias/errores#catalogo-de-codestado).

## Siguientes pasos

- [Contribuyente por identificación](/v1/guias/consulta-contribuyente): obtiene la ficha completa de la coincidencia que elegiste.
- [Validar identificación](/v1/guias/consulta-identificacion): comprueba el formato de una cédula o RUC sin consultar al SRI.
- [Errores](/v1/guias/errores): catálogo completo de códigos y qué hacer ante cada uno.
