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
estab002, comprueba que ese establecimiento existe y estáABIERTOen el RUC emisor. - Llenar direcciones. Usa
direccionCompletacomo dirección del establecimiento emisor o, en una guía de remisión, comodirPartidaodirDestinatariocuando 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#
- Contribuyente por identificación: obtiene la ficha completa del RUC, incluidos sus establecimientos.
- Guía de remisión: usa las direcciones de los establecimientos en el traslado.
- Errores: catálogo completo de códigos y qué hacer ante cada uno.