# OSIPTEL Consulta de Líneas Telefónicas (`latam-data/osiptel-scraper-client`) Actor

Consulta las líneas telefónicas registradas para un lote de RUCs peruanos en el padrón de OSIPTEL y las devuelve en el dataset de esta ejecución.

- **URL**: https://apify.com/latam-data/osiptel-scraper-client.md
- **Developed by:** [latam-data](https://apify.com/latam-data) (community)
- **Categories:** Lead generation, Other, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $15.00 / 1,000 ruc procesados

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

📞 Consulta de Líneas Telefónicas por RUC (fuente OSIPTEL) — Perú

Herramienta independiente no afiliada ni respaldada por OSIPTEL. Consulta datos públicos de OSIPTEL.

Consulta todas las líneas telefónicas registradas a un RUC peruano en el padrón público de OSIPTEL: índice de línea, modalidad (postpago/prepago/control), número de servicio (enmascarado) y operador — para uno o varios RUCs por ejecución.

#### Ejemplo de salida (un registro por línea)

```json
{
  "ruc": "20100047218",
  "indice": "1",
  "modalidad": "POSTPAGO",
  "numeroServicio": "99998****",
  "operador": "TELEFONICA DEL PERU S.A.A.",
  "scrapedAt": "2026-07-29T18:54:25Z"
}
```

Un RUC sin líneas registradas igual genera un registro, con `indice`/`modalidad`/`numeroServicio`/`operador` en `null` — así un resultado vacío se lee como "consultado, no se encontró nada", no como un registro perdido.

#### Pruébalo: input y API

**Input** (pestaña Input en la Consola, o vía API):

```json
{
  "rucs": ["20432405525", "20100047218"]
}
```

**Ejecutar de forma asíncrona** (recomendado en general, ya que la ejecución solo termina cuando se consultó cada RUC — no conviene mantener la conexión abierta esperando, sobre todo con lotes grandes):

```bash
## 1. Inicia la ejecución (devuelve de inmediato, con el run en estado RUNNING)
curl -X POST "https://api.apify.com/v2/acts/YOUR_USERNAME~osiptel-scraper-client/runs?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rucs":["20100047218"]}'
## -> devuelve { "data": { "id": "RUN_ID", "defaultDatasetId": "DATASET_ID", "status": "RUNNING", ... } }

## 2. Consulta el estado del run hasta que sea SUCCEEDED (por polling o webhook)
curl "https://api.apify.com/v2/actor-runs/RUN_ID?token=YOUR_APIFY_TOKEN"

## 3. Una vez terminado, obtén los resultados del dataset
curl "https://api.apify.com/v2/datasets/DATASET_ID/items?token=YOUR_APIFY_TOKEN"
```

**Ejecutar de forma sincrónica** (más simple, pero solo recomendado para lotes pequeños de RUCs — la conexión queda abierta hasta que termina la consulta):

```bash
curl -X POST "https://api.apify.com/v2/acts/YOUR_USERNAME~osiptel-scraper-client/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rucs":["20100047218"]}'
```

Exporta el dataset como JSON, CSV o XLSX desde la Consola.

Mientras la consulta sigue corriendo en segundo plano, el dataset puede ir creciendo en bloques durante la ejecución a medida que van apareciendo resultados nuevos; no hace falta esperar siempre hasta el final para empezar a ver filas.

#### Opcional: reutilizar datos recientes

Por defecto, cada RUC se consulta de nuevo en cada ejecución. Si prefieres reutilizar un resultado reciente en vez de volver a consultar, agrega `useHistoricDataWithinHours` al input:

```json
{
  "rucs": ["20432405525", "20100047218"],
  "useHistoricDataWithinHours": 24
}
```

Con `24`, cualquier RUC ya consultado exitosamente en algún momento de las últimas 24 horas no se vuelve a consultar — se devuelve su resultado existente.

#### Cobro

Este Actor está pensado para cobrarse por **RUC procesado**. La referencia comercial es **USD 150 por cada 10,000 RUCs**.

Cada RUC incluye hasta **5,000 líneas telefónicas devueltas**. Si un RUC supera ese volumen, se aplica un cargo adicional por cada bloque extra de **5,000 líneas**.

Esto existe porque los RUCs muy grandes requieren procesamiento adicional y generan resultados mucho más pesados que un RUC normal. Para el cliente, lo importante es simple: los RUCs normales pagan la tarifa base; los RUCs excepcionalmente grandes pagan más.

#### Qué devuelve este Actor

| | |
|---|---|
| 🔑 **RUC** | `ruc` |
| 📇 **Detalle de línea** | `indice`, `modalidad`, `numeroServicio`, `operador` |
| 🕒 **Fecha de consulta** | `scrapedAt` |

#### ¿Por qué consultar líneas telefónicas registradas en OSIPTEL?

- **Debida diligencia**: verificar las líneas de contacto declaradas por una empresa antes de una operación
- **Verificación / cumplimiento**: cruzar un número registrado con a quién está realmente asignado
- **Estudio de mercado**: ver qué operador(es) usa una empresa
- **Enriquecimiento masivo**: agregar datos de líneas telefónicas a una lista de RUCs existente, a escala

#### Opciones de input

| Campo | Obligatorio | Descripción |
|---|---|---|
| `rucs` | Sí | Arreglo de números de RUC peruanos (11 dígitos) |
| `useHistoricDataWithinHours` | No | Si un RUC ya fue consultado exitosamente dentro de las últimas N horas, se reutiliza ese resultado en lugar de volver a consultarlo |

#### Límites

- Cada ejecución espera a que se consulte cada RUC solicitado antes de devolver resultados — normalmente unos segundos por RUC. Lotes muy grandes (miles de RUCs a la vez) pueden tardar más.
- Los datos provienen directamente del padrón oficial de OSIPTEL al momento de la consulta (salvo que `useHistoricDataWithinHours` haya reutilizado un resultado reciente).

#### Preguntas frecuentes

**¿Qué pasa si un RUC no existe o no tiene líneas registradas?**
Igual se genera un registro para él, con todos los campos de línea en `null` — es un resultado vacío confirmado, no un error.

**¿Qué hace exactamente `useHistoricDataWithinHours`?**
Mira hacia atrás desde el momento actual. Si lo configuras en `24`, cualquier RUC ya consultado exitosamente en algún momento de las últimas 24 horas no se vuelve a consultar — se reutiliza su resultado existente. Si se omite, todos los RUCs se consultan siempre de nuevo.

**¿Qué formato de RUC se espera?**
El RUC peruano estándar de 11 dígitos (por ejemplo, `20100047218`).

**¿Puedo enviar miles de RUCs a la vez?**
Sí, pero la ejecución del Actor tomará más tiempo — solo termina cuando se consultó cada RUC. Para necesidades de volumen muy grande y recurrente, contáctanos directamente.

# Actor input Schema

## `rucs` (type: `array`):

Números de RUC peruanos (11 dígitos cada uno) a consultar.

## `useHistoricDataWithinHours` (type: `integer`):

Opcional. Si un RUC ya fue consultado exitosamente dentro de las últimas N horas, se reutiliza ese resultado en lugar de volver a consultarlo. Si se omite, todos los RUCs se consultan siempre de nuevo.

## Actor input object example

```json
{
  "rucs": [
    "20100047218"
  ]
}
```

# Actor output Schema

## `lines` (type: `string`):

Un registro por cada línea telefónica registrada (ruc, indice, modalidad, numeroServicio, operador, scrapedAt). Los RUCs sin líneas registradas igual generan un registro, con los campos en null.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "rucs": [
        "20100047218"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("latam-data/osiptel-scraper-client").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "rucs": ["20100047218"] }

# Run the Actor and wait for it to finish
run = client.actor("latam-data/osiptel-scraper-client").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "rucs": [
    "20100047218"
  ]
}' |
apify call latam-data/osiptel-scraper-client --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=latam-data/osiptel-scraper-client",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/Dm0Sfn4g3VLyWJuSU/builds/XDj7XIabAQv3Mr5yx/openapi.json