Cómo integrar una API de RUC de Ecuador

Qué devuelve el endpoint de RUC

Usa GET /api/v1/rucs/{ruc} con un RUC de 13 dígitos. La respuesta incluye razón social, estado, tipo de contribuyente, actividad económica y condiciones de agente de retención y contribuyente especial.

El listado de establecimientos se consulta por separado en GET /api/v1/rucs/{ruc}/establecimientos. Su respuesta incluye count, establishments y fetched_at; comprueba is_headquarters en cada establecimiento para identificar la matriz.

Los datos tributarios no son una garantía comercial. Diseña tu flujo para admitir campos null y actualizaciones posteriores.

Requisitos antes de integrar

• Crea una API key y configúrala como ECUADORAPI_KEY en el entorno del servidor.
• Valida que el RUC contenga 13 dígitos antes de enviarlo.
• No expongas la clave en aplicaciones web, móviles ni repositorios públicos.
• Define qué campos necesitas para facturación, proveedores o registro y evita conservar el resto sin propósito.

Ejemplos para consultar un RUC desde código

Copia el ejemplo de tu lenguaje y reemplaza el RUC ficticio. La API devuelve el mismo envelope JSON en todos los casos.

curl "https://api.ecuadorapi.com/api/v1/rucs/1790012345001" \
  -H "Authorization: Bearer $ECUADORAPI_KEY"

const response = await fetch("https://api.ecuadorapi.com/api/v1/rucs/1790012345001", {
  headers: {
    Authorization: "Bearer " + process.env.ECUADORAPI_KEY,
  },
})
const { data } = await response.json()

import os
import requests

response = requests.get(
    "https://api.ecuadorapi.com/api/v1/rucs/1790012345001",
    headers={"Authorization": f"Bearer {os.environ['ECUADORAPI_KEY']}"},
)
data = response.json()["data"]

$ch = curl_init("https://api.ecuadorapi.com/api/v1/rucs/1790012345001");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("ECUADORAPI_KEY")],
    CURLOPT_RETURNTRANSFER => true,
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
$data = $body["data"];

{
  "data": {
    "id": "1790012345001",
    "business_name": "EJEMPLO COMERCIAL S.A.",
    "status": "ACTIVO",
    "taxpayer_type": "SOCIEDAD",
    "is_withholding_agent": true,
    "is_special_taxpayer": false,
    "economic_activity": "VENTA AL POR MENOR DE OTROS PRODUCTOS",
    "start_date": "2015-03-01",
    "fetched_at": "2026-06-20T16:00:00Z"
  },
  "error": null,
  "message": null
}

Cómo leer la respuesta JSON

• data.id contiene el RUC consultado.
• data.business_name identifica la razón social. El nombre comercial se consulta como establishments[].commercial_name en el endpoint de establecimientos.
• data.status y data.taxpayer_type describen el estado y el tipo de contribuyente reportados.
• data.economic_activity resume la actividad principal registrada.
• La consulta principal no incluye trade_name ni address. Consulta establishments[].address en el endpoint de establecimientos y usa is_headquarters para identificar la matriz.

Errores y decisiones de negocio

• 400: el RUC no cumple el formato esperado.
• 401, 402 o 403: revisa autenticación, saldo y verificación de la cuenta según el mensaje.
• 404: no se encontraron datos para el RUC enviado; permite corregirlo y volver a intentar.
• 429: espera el tiempo indicado en Retry-After.
• 502 o 503: muestra un estado temporal y reintenta con espera progresiva; no bloquees permanentemente al proveedor o cliente.

Checklist para facturación y proveedores

• Compara el RUC devuelto con el valor enviado.
• Presenta la razón social para que el usuario confirme antes de guardar.
• No conviertas un estado aislado en una decisión automática sin las reglas de tu negocio.
• Revisa el precio vigente del endpoint y registra métricas sin incluir el RUC ni la respuesta completa.