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#
- Contribuyente por identificación: obtiene la ficha completa de la coincidencia que elegiste.
- Validar identificación: comprueba el formato de una cédula o RUC sin consultar al SRI.
- Errores: catálogo completo de códigos y qué hacer ante cada uno.