Documentación de la API

API compatible con apiperu.dev para consultas de RUC y DNI. La fuente es el padrón reducido público de SUNAT, que se actualiza a diario de madrugada.

Base URL: https://consultas.efact.si

Autenticación: cabecera Authorization: Bearer <token>. Pide tu token al administrador.

Límite: 60 consultas por minuto por token (salvo que el token tenga otro límite). Las cabeceras X-RateLimit-Limit y X-RateLimit-Remaining indican tu consumo.

Consultar RUC

POST /api/ruc con cuerpo JSON {"ruc": "20100047218"}, o GET /api/ruc/{ruc}.

curl -X POST https://consultas.efact.si/api/ruc \
  -H "Authorization: Bearer TU_TOKEN" -H "Content-Type: application/json" \
  -d '{"ruc":"20100047218"}'

{
  "success": true,
  "code": "found",
  "retryable": false,
  "data": {
    "ruc": "20100047218",
    "nombre_o_razon_social": "BANCO DE CREDITO DEL PERU",
    "direccion": "JR. CENTENARIO NRO. 156 URB. LAS LADERAS DE MELGAREJO",
    "direccion_completa": "JR. CENTENARIO NRO. 156 URB. LAS LADERAS DE MELGAREJO, LIMA - LIMA - LA MOLINA",
    "estado": "ACTIVO",
    "condicion": "HABIDO",
    "departamento": "LIMA",
    "provincia": "LIMA",
    "distrito": "LA MOLINA",
    "ubigeo_sunat": "150114",
    "ubigeo": ["15", "1501", "150114"]
  },
  "source": "consultas.efact.si",
  "time": 0.012
}

Si no hay ubigeo: ubigeo_sunat: "" y ubigeo: [null, null, null]. El padrón reducido no incluye agentes de retención, así que el campo es_agente_de_retencion no se envía.

Consultar DNI

POST /api/dni con cuerpo JSON {"dni": "45215942"}, o GET /api/dni/{dni}.

Se busca el RUC de persona natural 10 + DNI + dígito verificador. Solo se encuentran las personas que tienen RUC. Los apellidos y nombres se separan a partir del texto del padrón ("APELLIDO_PATERNO APELLIDO_MATERNO NOMBRES"), así que esa separación es una aproximación.

{
  "success": true,
  "code": "found",
  "retryable": false,
  "data": {
    "numero": "45215942",
    "nombre_completo": "GARCIA CHANCO CARLOS AUGUSTO",
    "nombres": "CARLOS AUGUSTO",
    "apellido_paterno": "GARCIA",
    "apellido_materno": "CHANCO",
    "codigo_verificacion": 8,
    "direccion": "", "direccion_completa": "",
    "departamento": null, "provincia": null, "distrito": null,
    "ubigeo_sunat": "", "ubigeo": [null, null, null]
  },
  "source": "consultas.efact.si",
  "time": 0.010
}

Errores

Todos los errores usan el mismo formato: {"success": false, "code": "...", "retryable": bool, "message": "...", "source": "...", "time": n}

HTTP	code	retryable	Cuándo
400	`invalid_input`	false	RUC sin 11 dígitos o con dígito verificador inválido; DNI sin 8 dígitos
401	`unauthorized`	false	Token ausente, inválido o revocado
404	`document_not_found`	false	El documento no figura en el padrón
429	`rate_limited`	true	Superaste el límite por minuto (ver cabecera `Retry-After`)
503	`upstream_unavailable`	true	El padrón no está disponible (BD caída o aún no importado)

Uso desde efact

En la configuración de efact (admin o empresa), en el campo de URL de apiperu, poner https://consultas.efact.si y como token el que generes aquí. No hace falta cambiar código: efact usa GET /api/ruc/{numero} y GET /api/dni/{numero}, que esta API soporta.