<!-- source_url: https://docs.mynexusapi.com/v1/guias/consulta-establecimientos | last_updated: 2026-11-19 -->

# Establecimientos de un RUC

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

Un [establecimiento](/v1/guias/glosario) es un local que el
[contribuyente](/v1/guias/glosario) tiene registrado en el
[SRI](/v1/guias/glosario), 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.

> [!IMPORTANT]
> 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](/v1/guias/glosario). |
| `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](/v1/guias/limites).

## 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](/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).
- [ ] 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.

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

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

```python
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)
```

```javascript
// 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
<?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;
```

```java
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());
```

```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")!
});

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

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

resultado = client.listar_establecimientos("0123456789001", "SoloActivos")
for e in resultado.establecimientos or []:
    print(e.numero, e.estado, e.direccion_completa)
```

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

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

$resultado = $client->listarEstablecimientos('0123456789001', 'SoloActivos');
foreach ($resultado->establecimientos ?? [] as $e) {
    echo $e->numero . ' ' . $e->estado . ' ' . $e->direccionCompleta . PHP_EOL;
}
```

```java-sdk
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());
}
```

```bash-cli
# 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.

```json
{
  "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](/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 | 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](/v1/guias/errores#catalogo-de-codestado).

## Siguientes pasos

- [Contribuyente por identificación](/v1/guias/consulta-contribuyente): obtiene la ficha completa del RUC, incluidos sus establecimientos.
- [Guía de remisión](/v1/guias/emision-06): usa las direcciones de los establecimientos en el traslado.
- [Errores](/v1/guias/errores): catálogo completo de códigos y qué hacer ante cada uno.
