Registro Público del Contribuyente (RUC)

Este endpoint permite la consulta directa e inmediata de la información pública registrada para un número de RUC específico. No requiere autenticación de usuario (sin credenciales de inicio de sesión), solo la clave de API para el consumo del servicio.

Detalles Técnicos

Endpoint y Método

• Método: GET
• Endpoint: /taxpayer/{taxpayerId}/registry

Parámetro de Ruta

• (string): El RUC o identificador fiscal que se desea consultar (ejemplo: 1721743399001)

Headers Requeridos

• x-api-key: [Tu Clave] - La clave de API es obligatoria para acceder al servicio

Body/Payload

No Aplica. Al ser una consulta GET, la identificación se realiza mediante el parámetro de ruta.

Código de Ejemplo

const axios = require('axios');

let config = {
  method: 'get',
  url: 'https://staging-api.taxo.ws/taxpayer/1721743399001/registry',
  headers: { 
    'x-api-key': 'tu_api_key'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Respuesta de la solicitud

La respuesta es un objeto JSON que detalla la información pública del contribuyente:

{
  "status": "success",
  "data": {
    "numeroRuc": "1726051285001",
    "razonSocial": "SOTO ESPINOSA ANDREA ESTEFANIA",
    "estadoContribuyenteRuc": "ACTIVO",
    "actividadEconomicaPrincipal": "PRESTACION DE SERVICIOS PROFESIONALES.",
    "tipoContribuyente": "PERSONA NATURAL",
    "regimen": "GENERAL",
    "categoria": null,
    "obligadoLlevarContabilidad": "NO",
    "agenteRetencion": "NO",
    "contribuyenteEspecial": "NO",
    "informacionFechasContribuyente": {
      "fechaInicioActividades": "2021-12-28 00:00:00.0"
    },
    "representantesLegales": null,
    "establishment": []
  }
}

Campos de la Respuesta

• status (string): Debe ser "success"
• data (object): Contenedor principal de la información
• data.numeroRuc (string): RUC consultado
• data.razonSocial (string): Nombre legal del contribuyente
• data.estadoContribuyenteRuc (string): Estado actual (ej. "ACTIVO")
• data.tipoContribuyente (string): Tipo de persona (ej. "PERSONA NATURAL")
• data.informacionFechasContribuyente (object): Sub-objeto con los hitos temporales del RUC
• data.establishment (array): Lista de establecimientos o sucursales registrados

Código de Respuesta HTTP

200 OK: Es el código esperado para una consulta GET síncrona exitosa que devuelve el recurso directamente en el cuerpo de la respuesta.

404 Not Found: Posiblemente devuelto si el RUC no existe o no se encuentra en el registro.