Búsqueda de Contribuyentes

Encuentra contribuyentes buscando por su razón social o nombre comercial.

Endpoint

GET /api/contribuyentes/search

Parámetros de query

Parámetro	Tipo	Requerido	Descripción
`razonSocial`	string	Sí	Texto a buscar (mínimo 3 caracteres)
`limit`	number	No	Máximo de resultados (default: 10, max: 50)

Headers

Header	Requerido	Descripción
`X-API-KEY`	Sí	Tu API Key de KipuDev

Ejemplo de solicitud

curl -X GET "https://api.kipudev.com/api/contribuyentes/search?razonSocial=SUNAT&limit=5" \
  -H "X-API-KEY: tu-api-key"

Respuesta exitosa

[
  {
    "ruc": "20131312955",
    "razonSocial": "SUNAT - SUPERINTENDENCIA NACIONAL DE ADUANAS Y DE ADMINISTRACION TRIBUTARIA",
    "estado": "ACTIVO",
    "condicion": "HABIDO"
  },
  {
    "ruc": "20504743307",
    "razonSocial": "SUNAT ADUANAS",
    "estado": "ACTIVO",
    "condicion": "HABIDO"
  },
  {
    "ruc": "20100130204",
    "razonSocial": "BANCO DE LA NACION - SUNAT",
    "estado": "ACTIVO",
    "condicion": "HABIDO"
  }
]

Campos de respuesta

Cada elemento del array contiene:

Campo	Tipo	Descripción
`ruc`	string	Número de RUC
`razonSocial`	string	Nombre o razón social
`estado`	string	Estado del contribuyente
`condicion`	string	Condición domiciliaria

Para obtener información completa de un contribuyente específico, usa el endpoint Consulta RUC con el RUC obtenido de la búsqueda.

Comportamiento de búsqueda

La búsqueda es case-insensitive (no distingue mayúsculas/minúsculas)
Busca coincidencias parciales (LIKE '%texto%')
Los resultados se ordenan por relevancia
Si no hay coincidencias, devuelve un array vacío []

Errores

Código	Error	Descripción
400	`Búsqueda muy corta`	El texto debe tener al menos 3 caracteres
400	`Límite inválido`	El límite debe ser entre 1 y 50

{
  "error": "El texto de búsqueda debe tener al menos 3 caracteres",
  "code": "SEARCH_TOO_SHORT"
}

Rate Limiting

Este endpoint consume 1 consulta de tu cuota diaria, independientemente del número de resultados.

Para búsquedas muy genéricas (ej: "SAC", "EIRL"), el endpoint puede devolver muchos resultados. Usa el parámetro limit para controlar la cantidad.

Ejemplo en código

async function buscarContribuyentes(texto: string, limit = 10) {
  const params = new URLSearchParams({
    razonSocial: texto,
    limit: limit.toString(),
  });

  const response = await fetch(
    `https://api.kipudev.com/api/contribuyentes/search?${params}`,
    {
      headers: { "X-API-KEY": process.env.KIPUDEV_API_KEY },
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error);
  }

  return response.json();
}

// Uso
const resultados = await buscarContribuyentes("SUNAT", 5);
console.log(resultados);