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

Establecimientos de un RUC GET

Lista los establecimientos que un RUC tiene registrados en el SRI, con su dirección y si están abiertos o cerrados.

Un establecimiento es un local que el contribuyente tiene registrado en el SRI, sea la matriz o una sucursal. Su código de 3 dígitos es el estab con el que numeras tus comprobantes. Con este endpoint puedes consultar los establecimientos de un RUC, con su código, su nombre comercial, su dirección y su estado.

Te sirve para comprobar que un establecimiento existe antes de emitir con él o para llenar direcciones sin escribirlas a mano. Al terminar esta página sabrás cómo filtrar el listado y cómo leer cada establecimiento.

Importante

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.

Endpoint#

GET /v1/consultas/establecimientos/{ruc}?filtro={filtro}
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 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.

Cuándo usarlo#

  • Elegir el establecimiento con el que emites. Antes de emitir con el estab 002, comprueba que ese establecimiento existe y está ABIERTO en el RUC emisor.
  • Llenar direcciones. Usa direccionCompleta como dirección del establecimiento emisor o, en una guía de remisión, como dirPartida o dirDestinatario cuando el destino es una sucursal de tu cliente.
  • Mostrar las sucursales de un cliente o proveedor en tu ERP.

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.
  • Para ver datos reales, 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
ruc ruta string Sí RUC de 13 dígitos del contribuyente. La API elimina los espacios al inicio y al final.
filtro consulta string No Qué establecimientos devolver, según la tabla siguiente. No distingue mayúsculas. Con otro valor, la API responde 400 con el codEstado 3012 (filtros_invalidos).
filtro Devuelve
Todos (por defecto) Todos los establecimientos, abiertos y cerrados.
SoloActivos Solo los establecimientos con estado ABIERTO.
SoloCerrados Solo los establecimientos con estado CERRADO.
SoloMatriz Solo la matriz, es decir, el establecimiento con esMatriz en true.
SoloSucursales Solo los establecimientos que no son la matriz.

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.

curl -s "https://api-sandbox.mynexusapi.com/v1/consultas/establecimientos/0123456789001?filtro=SoloActivos" \
  -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);

using HttpResponseMessage respuesta = await http.GetAsync("/v1/consultas/establecimientos/0123456789001?filtro=SoloActivos");
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
import os
import requests

r = requests.get(
    "https://api-sandbox.mynexusapi.com/v1/consultas/establecimientos/0123456789001",
    headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]},
    params={"filtro": "SoloActivos"},
    timeout=30,
)
print(r.status_code, r.text)
// 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/establecimientos/0123456789001?filtro=SoloActivos', {
  headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY }
});
console.log(res.status, await res.text());
<?php
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/consultas/establecimientos/0123456789001?filtro=SoloActivos');
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.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/establecimientos/0123456789001?filtro=SoloActivos"))
    .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")!
});

EstablecimientosContribuyente resultado = await client.ListarEstablecimientosAsync("0123456789001", "SoloActivos");
foreach (EstablecimientoConsulta e in resultado.Establecimientos ?? new())
{
    Console.WriteLine(e.Numero + " " + e.Estado + " " + e.DireccionCompleta);
}
import os
from ecuafact import EcuafactClient, EcuafactClientOptions

client = EcuafactClient(EcuafactClientOptions(
    base_address="https://api-sandbox.mynexusapi.com/",
    api_key=os.environ["ECUAFACT_API_KEY"],
))

resultado = client.listar_establecimientos("0123456789001", "SoloActivos")
for e in resultado.establecimientos or []:
    print(e.numero, e.estado, e.direccion_completa)
// 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 resultado = await client.listarEstablecimientos("0123456789001", "SoloActivos");
for (const e of resultado.establecimientos ?? []) {
  console.log(e.numero, e.estado, e.direccionCompleta);
}
<?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'),
));

$resultado = $client->listarEstablecimientos('0123456789001', 'SoloActivos');
foreach ($resultado->establecimientos ?? [] as $e) {
    echo $e->numero . ' ' . $e->estado . ' ' . $e->direccionCompleta . PHP_EOL;
}
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.contracts.EstablecimientoConsulta;
import com.ecuafact.sdk.contracts.EstablecimientosContribuyente;

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

EstablecimientosContribuyente resultado = client.listarEstablecimientos("0123456789001", "SoloActivos");
for (EstablecimientoConsulta e : resultado.establecimientos()) {
    System.out.println(e.numero() + " " + e.estado() + " " + e.direccionCompleta());
}
# Resultado esperado: con un RUC que existe, sus establecimientos abiertos en tabla.
# Con el RUC de prueba 0123456789001, un error 404 con el `codEstado` 3013 (`no_encontrado`).
ecuafact establecimientos 0123456789001 --filtro SoloActivos --entorno sandbox

Con un RUC que existe, 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.

{
  "ruc": "0123456789001",
  "filtro": "SoloActivos",
  "cantidad": 2,
  "establecimientos": [
    {
      "numero": "001",
      "nombreComercial": "COMERCIAL DE PRUEBA",
      "tipo": "MATRIZ",
      "direccionCompleta": "AV. DE PRUEBA 123 Y CALLE FICTICIA",
      "estado": "ABIERTO",
      "esMatriz": true
    },
    {
      "numero": "002",
      "nombreComercial": "COMERCIAL DE PRUEBA SUCURSAL NORTE",
      "tipo": "LOCAL COMERCIAL",
      "direccionCompleta": "CALLE FICTICIA 456",
      "estado": "ABIERTO",
      "esMatriz": false
    }
  ]
}

Cualquier campo puede venir null si la fuente no tiene el dato.

Campo Tipo Descripción
ruc string RUC consultado.
filtro string Filtro aplicado, con su nombre canónico: Todos, SoloActivos, SoloCerrados, SoloMatriz o SoloSucursales.
cantidad integer Número de establecimientos devueltos después de aplicar el filtro.
establecimientos array Establecimientos que cumplen el filtro. Puede venir vacío ([]).
establecimientos[].numero string Código del establecimiento, de 3 dígitos. Es el valor de 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 en el SRI.
establecimientos[].estado string ABIERTO o CERRADO.
establecimientos[].esMatriz boolean true si es la matriz.

Estados de este endpoint#

codEstado HTTP Cuándo ocurre Qué hacer
- 200 La consulta se realizó. Lee establecimientos. Si cantidad es 0, ningún establecimiento cumple el filtro.
3012 (filtros_invalidos) 400 filtro no es uno de los valores permitidos. El detalle llega en errores. Corrige filtro u omítelo.
3003 (solicitud_invalida) 400 El RUC tiene un formato que la fuente no acepta. Corrige el RUC, que debe tener 13 dígitos.
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 El RUC no existe en el catastro o no tiene establecimientos registrados. Verifica el RUC.
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.

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.