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

Contribuyentes por nombre GET

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

Importante

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

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.
  • 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; 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.

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.

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"
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()}");
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)
// 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
$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;
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());
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);
}
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)
// 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
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;
}
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());
}
# 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.

[
  {
    "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.
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.

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.