API v1.0.0 · CONSULTAS Y CATÁLOGOS

Consulta de RUC

Consulta en el catastro público del SRI la razón social, el estado, el régimen y los establecimientos de un RUC, para completar los datos de un cliente o de un proveedor antes de emitir.

Qué devuelve

Campo	Contenido
`ruc`, `razonSocial`, `nombreComercial`	Identificación y nombres registrados en el SRI.
`estado`, `activo`	Estado del RUC según el SRI (por ejemplo `ACTIVO` o `SUSPENDIDO`) y si está activo.
`tipoPersona`	`NATURAL` o `JURIDICA`.
`regimen`	`GENERAL`, `RIMPE_EMPRENDEDOR` o `RIMPE_NEGOCIO_POPULAR`.
`obligadoContabilidad`, `agenteRetencion`, `contribuyenteEspecial`	Calificaciones del contribuyente.
`direccionMatriz`	Dirección de la matriz.
`establecimientos`	Número, nombre comercial, dirección, si está abierto y si es la matriz.

Algunos campos pueden venir en null si el SRI no los informa.

Usos

Completar la razón social de un cliente nuevo o del sujeto retenido de una retención, tal como está registrada en el SRI.
Comprobar que el RUC de un proveedor está activo antes de registrar su factura y emitir la retención.

La consulta es solo por RUC (13 dígitos terminados en 001). Un número con otro formato responde 400 PARAMETRO_INVALIDO, y un RUC que el SRI no registra, 404 RUC_NO_REGISTRADO. Los ejemplos consultan 1760013210001, el RUC del Servicio de Rentas Internas, que está en el catastro; un RUC inventado para pruebas, como 0990000000001, responde 404.

Disponibilidad del SRI

La consulta depende del servicio del SRI. Si no responde, la respuesta es 503 SRI_NO_DISPONIBLE con Retry-After; tu sistema debe permitir registrar los datos a mano en ese caso. Golem guarda cada respuesta hasta una hora, así que un cambio reciente en el catastro puede tardar ese tiempo en verse.

Cada token puede hacer 20 consultas de RUC por minuto.

Consultar un RUC en el catastro del SRI

GET /ruc/{ruc}

Requiere token

Consulta en el catastro público del SRI la razón social, el estado, el régimen y los establecimientos de un RUC. Sirve para completar los datos de un cliente o de un proveedor antes de emitir. Depende de la disponibilidad del SRI: si no responde, 503 con Retry-After. Las respuestas se guardan en caché hasta una hora.

Límites: 60 solicitudes por minuto por token; 20 consultas de RUC por minuto por token.

Parámetros

Parámetros de consultar un ruc en el catastro del sri
Campo	Descripción
`ruc` ruta string obligatorio	RUC de 13 dígitos terminado en 001. Formato `^\d{10}001$`
`X-Request-Id` cabecera string	Identificador propio de la solicitud (hasta 64 caracteres: letras, números y `-`). Si no lo envías, Golem genera uno. Vuelve en la cabecera de respuesta y en los errores; cítalo al escribir a soporte. Hasta 64 caracteres Formato `^[A-Za-z0-9-]{1,64}$`

Ejemplo de solicitud

Los ejemplos leen el token de la variable de entorno GOLEM_TOKEN.

Terminal

curl https://api.golem.ec/v1/ruc/1760013210001 \
  --max-time 30 \
  -H "Authorization: Bearer $GOLEM_TOKEN"

Node.js 18+ (fetch)

const respuesta = await fetch('https://api.golem.ec/v1/ruc/1760013210001', {
  headers: {
    Authorization: `Bearer ${process.env.GOLEM_TOKEN}`,
  },
  signal: AbortSignal.timeout(30000),
});
const datos = await respuesta.json();
console.log(respuesta.status, datos);

Python (requests)

import os

import requests

respuesta = requests.get(
    "https://api.golem.ec/v1/ruc/1760013210001",
    headers={
        "Authorization": f"Bearer {os.environ['GOLEM_TOKEN']}",
    },
    timeout=30,
)
print(respuesta.status_code, respuesta.json())

PHP (Guzzle)

<?php
// composer require guzzlehttp/guzzle
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$cliente = new Client(['base_uri' => 'https://api.golem.ec/v1/', 'timeout' => 30]);

$respuesta = $cliente->get('ruc/1760013210001', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('GOLEM_TOKEN'),
    ],
    'http_errors' => false,
]);

echo $respuesta->getStatusCode(), PHP_EOL, $respuesta->getBody(), PHP_EOL;

Respuestas

200 application/json

Datos del RUC según el SRI.

Esquema Ruc.

Respuesta 200: Entidad pública activa (Servicio de Rentas Internas)

{
  "ruc": "1760013210001",
  "razonSocial": "SERVICIO DE RENTAS INTERNAS",
  "nombreComercial": null,
  "estado": "ACTIVO",
  "activo": true,
  "tipoPersona": "JURIDICA",
  "regimen": "GENERAL",
  "obligadoContabilidad": true,
  "agenteRetencion": true,
  "contribuyenteEspecial": true,
  "direccionMatriz": "PICHINCHA / QUITO / IÑAQUITO / AVENIDA AMAZONAS S/N Y UNIÓN NACIONAL DE PERIODISTAS",
  "establecimientos": [
    {
      "numero": "001",
      "nombreComercial": null,
      "direccion": "PICHINCHA / QUITO / MARISCAL SUCRE / PÁEZ N22-53 Y RAMIREZ DÁVALOS",
      "abierto": true,
      "matriz": false
    },
    {
      "numero": "002",
      "nombreComercial": null,
      "direccion": "GUAYAS / GUAYAQUIL / ROCAFUERTE / AV. 10 DE AGOSTO 212 Y PEDRO CARBO Y PICHINCHA",
      "abierto": false,
      "matriz": false
    },
    {
      "numero": "059",
      "nombreComercial": null,
      "direccion": "PICHINCHA / QUITO / IÑAQUITO / AVENIDA AMAZONAS S/N Y UNIÓN NACIONAL DE PERIODISTAS",
      "abierto": true,
      "matriz": true
    }
  ]
}

Errores: HTTP 400, 401, 404, 429, 500, 503

Códigos de error de consultar un ruc en el catastro del sri
HTTP	Código	Causa y solución
400	`JSON_INVALIDO`	El cuerpo no es un JSON válido. Revisa la sintaxis cerca de la línea y la columna que indica el mensaje.
400	`VALIDACION`	Uno o más campos no cumplen el formato. `detalles` lista cada campo con su código: `CAMPO_REQUERIDO`, `CAMPO_DESCONOCIDO`, `TIPO_INVALIDO`, `FORMATO_INVALIDO`, `VALOR_INVALIDO`, `LONGITUD_INVALIDA` o `DECIMALES_EXCEDIDOS`. Corrige los campos de `detalles`. Los campos que el API no conoce se rechazan: revisa los nombres.
400	`PARAMETRO_INVALIDO`	Un parámetro de la ruta o de la consulta no es válido: por ejemplo, una clave de acceso sin 49 dígitos, un rango de fechas de más de 366 días o un `cambiadoDesde` anterior a 90 días. Corrige el parámetro que indica `campo`.
400	`IDEMPOTENCY_KEY_INVALIDA`	La cabecera `Idempotency-Key` no tiene entre 8 y 100 caracteres, o usa caracteres distintos de letras, números, `-`, `_`, `.` y `:`. Genera la clave con un UUID v4.
400	`TOKEN_EN_URL`	La URL incluye `token`, `access_token` o `api_key`. Envía el token solo en la cabecera `Authorization`. Revoca ese token y crea otro: la URL pudo quedar en registros.
401	`TOKEN_REQUERIDO`	Falta la cabecera `Authorization`. Envía `Authorization: Bearer <token>`.
401	`TOKEN_INVALIDO`	El token no existe o no tiene el formato de un token de Golem. Copia el token completo, con su prefijo. Si no lo tienes, crea otro: Golem no puede mostrarlo de nuevo.
401	`TOKEN_REVOCADO`	El token fue revocado. Crea otro en Cuenta > API e integraciones.
404	`RUC_NO_REGISTRADO`	El catastro del SRI no registra ese RUC. Revisa el número con el proveedor o el cliente.
429	`LIMITE_EXCEDIDO`	Se superó un límite de solicitudes por minuto. Repite la solicitud después de los segundos de `Retry-After`.
500	`ERROR_INTERNO`	Error inesperado de Golem. Si ocurrió al emitir, repite la solicitud con la misma `Idempotency-Key`. Escribe a [email protected] con el `requestId`.
503	`SRI_NO_DISPONIBLE`	El SRI no responde. Repite la solicitud después de los segundos de `Retry-After`.
503	`SERVICIO_NO_DISPONIBLE`	Un servicio interno de Golem no responde. Repite la solicitud después de los segundos de `Retry-After`.
503	`MANTENIMIENTO`	Golem está en mantenimiento. Los mantenimientos se avisan por correo con 24 horas de anticipación. Repite la solicitud después de los segundos de `Retry-After`.

Formato y lista completa en Errores.