Consultar un RUC: GET /ruc/{id}

Devuelve los datos del padrón reducido de SUNAT para un RUC. Cada consulta cuesta 1 crédito.

GET https://consultaruc-api.karvesol.com/ruc/{id}

Autenticación

Cabecera Authorization: Bearer <api_key>. Sin key válida la API responde 401.

Parámetro

Nombre	En	Descripción
`id`	ruta	RUC de 11 dígitos, solo números.

Respuesta `200`

Un objeto JSON con estos campos:

Campo	Tipo	Descripción
`ruc`	número	El RUC consultado.
`razon_social`	texto o `null`	Razón social o nombre del contribuyente.
`estado`	texto o `null`	Estado del contribuyente según SUNAT (por ejemplo `ACTIVO`, `BAJA DEFINITIVA`, `SUSPENSION TEMPORAL`).
`condicion`	texto o `null`	Condición de domicilio según SUNAT (por ejemplo `HABIDO`, `NO HABIDO`).
`direccion`	texto o `null`	Domicilio fiscal.
`ubigeo`	texto o `null`	Código de ubigeo de 6 dígitos.
`distrito`	texto o `null`	Distrito del domicilio fiscal.
`provincia`	texto o `null`	Provincia del domicilio fiscal.
`departamento`	texto o `null`	Departamento del domicilio fiscal.
`es_agente_retencion`	booleano	`true` si el RUC figura como agente de retención del IGV.

Ten en cuenta:

Los datos se devuelven tal como los publica SUNAT. Algunos textos de estado y condicion vienen abreviados o truncados en la fuente (por ejemplo NO HALLADO SE MUDO D) y no se completan.
direccion, ubigeo, distrito, provincia y departamento solo vienen para RUC que empiezan con 20 (empresas). Para otros RUC son null, porque SUNAT no los publica.
Un campo sin dato llega como null.

Ejemplo (datos ficticios)

{
  "ruc": 20100000008,
  "razon_social": "EMPRESA DE EJEMPLO S.A.C.",
  "estado": "ACTIVO",
  "condicion": "HABIDO",
  "direccion": "AV. EJEMPLO 123",
  "ubigeo": "150101",
  "distrito": "LIMA",
  "provincia": "LIMA",
  "departamento": "LIMA",
  "es_agente_retencion": false
}

Códigos de estado

Código	Cuándo	Cuerpo
`200`	El RUC existe.	El JSON de arriba.
`400`	El `id` no tiene 11 dígitos o no es numérico.	`{"error": "…"}`
`401`	Falta la key o no es válida.	`{"error": "no autorizado"}`
`404`	El RUC no está en el padrón.	`{"error": "RUC no encontrado"}`
`429`	Superaste el límite por minuto o la cuota del plan Free.	`{"error": "…"}` y cabecera `Retry-After`
`503`	El padrón no está disponible por un momento.	`{"error": "padrón no disponible"}`