Contribuyentes por nombre GET

Busca contribuyentes por apellidos y nombres (o razon social) y devuelve identificaciones con sus nombres. La respuesta es un arreglo.

GET /v1/consultas/contribuyentes?apellidos=...&nombres=...&clase=...&max=...

Parametros#

Parametro	Regla
`apellidos`	Obligatorio. En sociedades, el inicio de la razon social: un fragmento interno o final puede no encontrar coincidencias
`nombres`	Opcional
`clase`	`PersonaNatural` (por defecto), `Sociedad` o `SociedadPublica`
`max`	Por defecto 10; tope 30

Codificar los espacios como %20.

curl -s "https://staging-api.mynexusapi.com/v1/consultas/contribuyentes?apellidos=PEREZ%20LOPEZ&nombres=JUAN&clase=PersonaNatural&max=10" \
  -H "X-Api-Key: $ECUAFACT_API_KEY"

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-Api-Key", apiKey);

string url = "https://staging-api.mynexusapi.com/v1/consultas/contribuyentes"
    + "?apellidos=PEREZ%20LOPEZ&nombres=JUAN&clase=PersonaNatural&max=10";
string json = await http.GetStringAsync(url);
Console.WriteLine(json);

import os, requests
r = requests.get(
    "https://staging-api.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)

const url = new URL('https://staging-api.mynexusapi.com/v1/consultas/contribuyentes');
url.search = new URLSearchParams({ apellidos: 'PEREZ LOPEZ', nombres: 'JUAN', clase: 'PersonaNatural', max: '10' });
const res = await fetch(url, { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } });
console.log(res.status, await res.text());

<?php
$url = 'https://staging-api.mynexusapi.com/v1/consultas/contribuyentes'
     . '?apellidos=' . rawurlencode('PEREZ LOPEZ') . '&nombres=JUAN&clase=PersonaNatural&max=10';
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')],
]);
$respuesta = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE) . ' ' . $respuesta;
curl_close($ch);

HttpClient cliente = HttpClient.newHttpClient();
HttpRequest peticion = HttpRequest.newBuilder()
    .uri(URI.create("https://staging-api.mynexusapi.com/v1/consultas/contribuyentes"
        + "?apellidos=PEREZ%20LOPEZ&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;

// client: cliente EcuafactClient - ver SDK .NET
IReadOnlyList<BusquedaContribuyente> encontrados =
    await client.BuscarContribuyentesAsync("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10);
foreach (BusquedaContribuyente c in encontrados)
{
    Console.WriteLine(c.Identificacion + " " + c.NombreCompleto);
}

from ecuafact import EcuafactClient

# client: cliente EcuafactClient - ver SDK Python
encontrados = client.buscar_contribuyentes("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10)
for contribuyente in encontrados:
    print(contribuyente.identificacion, contribuyente.nombre_completo)

import { EcuafactClient } from "@ecuafact/sdk";

// client: cliente EcuafactClient - ver SDK Node.js
const encontrados = await client.buscarContribuyentes("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10);
for (const contribuyente of encontrados) {
  console.log(contribuyente.identificacion, contribuyente.nombreCompleto);
}

<?php
use Ecuafact\Sdk\EcuafactClient;

// $client: cliente EcuafactClient - ver SDK PHP
$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 java.util.List;

// client: cliente EcuafactClient - ver SDK Java
List<BusquedaContribuyente> encontrados = client.buscarContribuyentes("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10);
for (BusquedaContribuyente contribuyente : encontrados) {
    System.out.println(contribuyente.identificacion() + " " + contribuyente.nombreCompleto());
}

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

Respuesta#

La respuesta es un arreglo de coincidencias; cada elemento trae:

Campo	Significado
`identificacion`	Identificacion del contribuyente
`tipoIdentificacion`	Tipo (`Cedula`, `RucSociedadPrivada`, etc.)
`nombreCompleto`	Nombre o razon social
`clase`	Persona natural, sociedad o sociedad publica
`estado`	Estado del contribuyente
`fuenteOrigen`	Fuente que respondio

Estados de este endpoint#

Codigo	HTTP	Cuando ocurre	Que hacer
`200`	200	Busqueda exitosa	Lee las coincidencias
`303`	400	`apellidos` ausente, o `clase`/`max` fuera de rango	Ajusta los parametros
`104`	429	Limite de solicitudes	Espera y reintenta
`003` / `004`	502 / 504	Fuente caida o sin respuesta	Reintenta

Esta consulta no consume cupo de documentos. El catalogo completo esta en Errores.

Siguientes pasos#

Errores