RUCs

Agente de retención

Indica si el contribuyente consta como agente de retención.

GET

/rucs/{ruc}/agente-retencion

Precio de lista por consulta con API key. Los errores no descuentan saldo.

Autenticación: Authorization: Bearer. Cómo usar tu API key

Parámetros

rucstringObligatorio · URL

Número de RUC (13 dígitos). Reemplaza {ruc} en la URL por el dato que quieres consultar.

Ejemplo ficticio: 1790012345001

Ejemplo de solicitud

Solicitud cURLbash

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

Ejecuta desde tu terminal. Configura ECUADORAPI_KEY en el entorno. Nunca publiques tu clave en el navegador.

Respuesta

JSON con datos ficticios. Los valores cambian según la consulta.

Respuesta de ejemplojson

{
  "data": {
    "id": "1790012345001",
    "business_name": "EJEMPLO COMERCIAL S.A.",
    "status": "ACTIVO",
    "is_withholding_agent": true,
    "fetched_at": "2026-09-14T16:00:00Z"
  },
  "error": null,
  "message": null
}

Qué significan los campos

Las claves del JSON están en inglés. Aquí tienes su significado en español; utiliza las claves originales en tu integración.

Agente de retención y contribuyente especial son dos condiciones distintas. La consulta principal de RUC incluye ambas y también puedes consultar cada una en su endpoint independiente. Una no permite deducir la otra.

true y false son valores booleanos de JSON, sin comillas. Interprétalos solo en una respuesta exitosa: un error no equivale a false.

Clave dentro de data	Significado en español	Cómo interpretarla
`id`	Número de RUC	Identificador consultado, de 13 dígitos.
`business_name`	Razón social	Nombre registrado del contribuyente.
`status`	Estado del contribuyente	Por ejemplo, ACTIVO. Este estado no indica por sí solo si es agente de retención o contribuyente especial.
`is_withholding_agent`	Es agente de retención	Withholding agent significa agente de retención. true: consta como agente de retención; false: no consta con esa condición.
`fetched_at`	Fecha de consulta	Fecha y hora de obtención de los datos, en formato ISO 8601.

null indica que un valor no está disponible.

Qué consulta cada endpoint de RUC

Las rutas usan el mismo RUC de 13 dígitos. Cada consulta tiene su propia respuesta y precio; revisa la ficha del endpoint que necesitas.

Consulta	Ruta GET	Qué devuelve
Datos de un RUC	`/api/v1/rucs/{ruc}`	Ficha general con razón social, estado, actividad y ambas condiciones tributarias.
Agente de retención	`/api/v1/rucs/{ruc}/agente-retencion`	is_withholding_agent: condición de agente de retención.
Contribuyente especial	`/api/v1/rucs/{ruc}/contribuyente-especial`	is_special_taxpayer: condición de contribuyente especial.
Establecimientos por RUC	`/api/v1/rucs/{ruc}/establecimientos`	count y establishments: cantidad y listado de establecimientos.

Guía de integración paso a paso

Sigue ejemplos en cURL, JavaScript, Python y PHP, interpreta la respuesta y prepara el manejo de errores.

Cómo consultar si un RUC es agente de retención

Ver errores y límites

Anterior Siguiente