Alkan – Apify Actor: Accela Lead Enrichment

Automatiza el enriquecimiento de leads de construcción de Seattle: Portal Accela → Cover Sheet PDF → LLM → Plataforma Alkan

---

Arquitectura

permit_numbers (input)
       │
       ▼
[PlaywrightCrawler]  ←── Apify Proxy (Residential US)
       │
       ▼  src/accela.js
  cosaccela.seattle.gov
  ├─ Búsqueda por permit_number
  ├─ Apertura de detalle del permiso
  ├─ Pestaña Attachments (AJAX)
  └─ Descarga del cover sheet PDF
       │
       ▼  src/extractor.js
  LLM (Gemini 2.5 Pro ó GPT-4o)
  └─ JSON con owner_name, phone, email, has_gc_assigned, etc.
       │
       ▼  src/ingest.js
  POST /api/public/leads-ingest
  └─ Upsert en tabla `leads` (client_id + permit_number)

---

Variables de entorno del Actor (NO van en el input)

Variable	Descripción	Requerida
LEADS_INGEST_SECRET	Secreto compartido del endpoint leads-ingest	✅
GEMINI_API_KEY	API Key de Google Gemini (preferido para PDFs)	✅ (o OPENAI)
OPENAI_API_KEY	API Key de OpenAI GPT-4o (alternativa)	✅ (o GEMINI)

---

Input del Actor

{
  "permit_numbers": ["7127087-DM", "7654321-CN"],
  "client_id": "alkan",
  "app_domain": "app.alkan.io",
  "batch_size": 50
}

Campo	Tipo	Descripción	Requerido
permit_numbers	string[]	Lista de números de permiso de Seattle	✅
client_id	string	Cliente destino en Alkan	✅
app_domain	string	Dominio de la app (sin https://)	✅
batch_size	integer	Leads por lote de ingesta (default: 50)	❌

---

Output

Dataset (auditoría por permiso)

Cada permiso genera una entrada:

{
  "permit_number": "7127087-DM",
  "status": "ok",
  "attachment_name": "Signed Application.pdf",
  "llm_data": { "owner_name": "BITC 58 LLC", "has_gc_assigned": false, ... },
  "lead_payload": { ... },
  "timestamp": "2026-05-30T..."
}

Valores de status:

• ok — enriquecido y enviado a Alkan
• not_found — permiso no encontrado en Accela
• no_attachment — no tiene documentos adjuntos
• no_attachment_tab — no se encontró la pestaña de Attachments
• download_error — error al descargar el PDF
• error — error inesperado
• failed_all_retries — falló todos los reintentos

Entrega de resultados a clientes

Todo usuario que ejecute este Actor recibe automáticamente sus resultados en el Dataset de esa ejecución (vía Apify), descargable en JSON, CSV o Excel, accesible por API, o entregable por webhook al finalizar el run. Esta es la entrega estándar y no requiere configuración adicional.

La sincronización directa a la tabla leads de Alkan (POST /api/public/leads-ingest) es un beneficio adicional, exclusivo para organizaciones que ya cuentan con una instancia de Alkan configurada con client_id y app_domain propios. Si el cliente no usa la plataforma Alkan, sus leads seguirán disponibles normalmente en el Dataset de Apify.

KeyValueStore

Los PDFs descargados se guardan con key pdf_{permitNumber} para re-extracción sin re-scraping.

---

Instalación local (desarrollo)

npm install
# Configurar .env con tus keys
cp .env.example .env

# Probar con un permiso real
node src/test.js

---

Configuraciones de Apify recomendadas

• Memory: 2048 MB (Playwright necesita memoria)
• Timeout: 3600 segundos para lotes grandes
• Proxy: Residential US (incluido en el código)
• Max concurrency: 2 (configurado en el código, no subir sin probar)

---

Criterios de aceptación (Sección 8 del brief)

• Dado un permit_number con cover sheet → descarga en < 30s
• LLM devuelve JSON válido con owner_name y has_gc_assigned
• POST a leads-ingest → 200 OK, lead enriquecido sin duplicarse
• Permiso sin attachments → status no_attachment, run continúa
• 20 permisos seguidos sin bloqueo (delays 3–6s configurados)

---

Notas de implementación

Por qué PlaywrightCrawler y no Cheerio

Accela ACA es una app WebForms ASP.NET con postbacks AJAX y ViewState. Sin JS real, el portal no funciona.

Disclaimer de Accela

La función handleDisclaimer() en accela.js detecta y acepta automáticamente la pantalla de términos que Accela muestra en la primera visita de sesión.

PDFs grandes

Si el PDF supera 10 MB, el extractor trunca al principio del archivo. El owner block siempre aparece en las primeras páginas del documento.

Deep-links vs búsqueda

El brief recomienda verificar si el deep-link CapDetail.aspx?capID1=... funciona. Esta implementación usa siempre la búsqueda por número de permiso (más robusta), que es la ruta recomendada en la Sección 3.

---

ALKAN · Andrés Alcántara · alkanassistant@gmail.com · Mayo 2026