Búsqueda de persona

A partir de un nombre o de un DNI obtén en una sola llamada el DNI, el RUC, los nombres y apellidos separados y el estado/condición del contribuyente en SUNAT. Combina internamente las consultas por razón social, DNI y RUC.

Alcance: SUNAT solo indexa por nombre a personas que tienen o tuvieron RUC (trabajadores independientes, negocios unipersonales, arrendadores…). Una persona natural sin RUC no aparecerá al buscar por nombre; por DNI se devuelve el nombre pero sin estado SUNAT.

URL

GET /api/persona?nombre=PEREZ+GARCIA+JUAN
GET /api/persona?dni=12345678&detalle=1

Parámetros

Parámetro Tipo Descripción
nombre string Nombre y/o apellidos de la persona. Mínimo 3 caracteres. Excluyente con dni.
dni string DNI de 8 dígitos. Excluyente con nombre.
detalle 1 | true (opcional) Adjunta la ficha RUC completa (dirección, actividad, tipo, fecha de inscripción…) en las primeras 5 coincidencias. Consume más tiempo por request.

Ejemplo de request

curl -X GET "https://apisperu.gsalinas.site/api/persona?nombre=PEREZ+GARCIA+JUAN" \
  -H "Authorization: Bearer apk_demo_apisperu_pub_2BfHK7nN4tV9X8jE3LpQ5sUcZ"

Ejemplo de response

{
  "ok": true,
  "data": {
    "criterio": "nombre",
    "query": "PEREZ GARCIA JUAN",
    "total": 2,
    "matches": [
      {
        "dni": "45678912",
        "ruc": "10456789123",
        "nombreCompleto": "PEREZ GARCIA JUAN CARLOS",
        "apellidoPaterno": "PEREZ",
        "apellidoMaterno": "GARCIA",
        "nombres": "JUAN CARLOS",
        "estado": "ACTIVO",
        "condicion": "HABIDO"
      },
      {
        "dni": "07123456",
        "ruc": "10071234561",
        "nombreCompleto": "PEREZ GARCIA JUAN",
        "apellidoPaterno": "PEREZ",
        "apellidoMaterno": "GARCIA",
        "nombres": "JUAN",
        "estado": "BAJA DEFINITIVA",
        "condicion": "NO HABIDO"
      }
    ],
    "fuente": "sunat-scraper",
    "aviso": "Se omitieron 1 RUC de empresas (20xxxxxxxxx). Use /api/nombre para razón social."
  }
}

Campos de cada coincidencia

Campo Tipo Descripción
dni string DNI derivado del RUC de persona natural (dígitos 3–10 del RUC 10xxxxxxxxY).
ruc string RUC de persona natural. Vacío si la persona no tiene RUC (solo con criterio dni).
nombreCompleto string Nombre tal como figura en SUNAT (APELLIDOS NOMBRES).
apellidoPaterno / apellidoMaterno / nombres string Nombre descompuesto (heurístico; los apellidos compuestos con DE/DEL/LA se mantienen juntos).
estado string Estado del contribuyente: ACTIVO, BAJA DEFINITIVA, SUSPENSION TEMPORAL…
condicion string Condición del domicilio fiscal: HABIDO, NO HABIDO…
ficha object (opcional) Ficha RUC completa; solo si se envió detalle=1. Mismo formato que /api/ruc.

La búsqueda por nombre devuelve hasta 20 coincidencias (truncado: true si hubo más). Los RUC de empresas (20…) se descartan; para ellos use /api/nombre.

Errores específicos

Probar en el playground