Rutificador 2026 - Apify Actor

Actor de Apify para consultar personas en Chile por RUT o por nombre, usando un backend protegido por API key. El actor normaliza la respuesta, elimina duplicados por RUT y guarda resultados estructurados en Dataset.

Que hace

• Consulta por RUT: GET /api/personas/:rut
• Consulta por nombre: GET /api/personas/search?q=...
• Reintenta requests fallidos con backoff exponencial
• Deduplica resultados por rut
• Guarda:
  • Dataset con personas normalizadas
  • Registro OUTPUT en Key-Value Store con resumen de ejecucion

Input

El esquema de entrada esta definido en .actor/input_schema.json.

{
    "ruts": ["12.345.678-9"],
    "queries": ["juan perez"],
    "maxResultsPerQuery": 20,
    "requestTimeoutMs": 15000,
    "maxRetries": 2
}

Campos

• ruts (array de string): lista de RUTs a consultar.
• queries (array de string): lista de busquedas por nombre.
• maxResultsPerQuery (1-20, default 20): maximo de personas por query.
• requestTimeoutMs (min 1000, default 15000): timeout por request.
• maxRetries (0-5, default 2): reintentos ante errores transitorios.

Debe venir al menos un elemento en ruts o queries.

Variables de entorno requeridas

• BACKEND_API_BASE_URL: URL base del backend (ej. https://mi-backend.com)
• BACKEND_API_KEY: API key enviada como header X-API-Key

Si falta alguna, el actor termina con error de configuracion.

Output

Dataset

Cada item incluye datos de persona y metadatos de origen:

• sourceType: "rut" o "query"
• sourceQuery: valor original consultado
• Campos de persona: rut, name, firstName, lastName, birthDate, gender, nationality, contactInfo, addresses, primaryAddressLine, primaryCommune, primaryRegion, etc.

La vista de salida esta definida en .actor/dataset_schema.json.

Key-Value Store (OUTPUT)

Se guarda un resumen como:

{
    "requestedRuts": 1,
    "requestedQueries": 1,
    "matchedPeople": 3,
    "rutNotFound": 0,
    "rutUnderageOrForbidden": 0,
    "failures": 0,
    "apiBaseUrl": "https://mi-backend.com",
    "processedAt": "2026-03-24T12:34:56.000Z"
}

Logica de estados HTTP

Para consultas por RUT:

• 200: procesa y guarda persona
• 404: incrementa rutNotFound
• 403: incrementa rutUnderageOrForbidden
• otro estado: incrementa failures

Para consultas por nombre:

• Solo 200 se considera exito
• cualquier otro estado incrementa failures

Desarrollo local

Requisitos

• Node.js >=18
• npm
• Apify CLI (npm i -g apify-cli) opcional pero recomendado

Instalacion

$npm install

Ejecutar en modo desarrollo

$npm run start:dev

Ejecutar como actor local

$apify run

Scripts utiles

• npm run build: compila TypeScript a dist/
• npm run start:prod: ejecuta dist/main.js
• npm run lint: revisa ESLint
• npm run lint:fix: corrige lint automaticamente
• npm run format: formatea con Prettier
• npm run format:check: valida formato sin escribir

Deploy en Apify

1. Login:

$apify login

2. Publicar:

$apify push

Estructura del proyecto

.actor/
├── actor.json
├── input_schema.json
├── output_schema.json
└── dataset_schema.json
src/
└── main.ts
Dockerfile
tsconfig.json
package.json

Notas

• Este actor no hace crawling web; funciona como integrador de API.
• El storage en storage/ durante apify run es local y no se sincroniza automaticamente con Apify Console.