ProspectIQ API — Explainer

Concepto

ProspectIQ automatiza el outreach B2B en LinkedIn mediante IA. Los equipos de ventas añaden perfiles de LinkedIn a campañas; el sistema extrae el perfil, construye un prompt contextualizado y genera múltiples borradores de mensaje personalizados mediante un LLM (OpenAI GPT-4o-mini por defecto, configurable).

Inspirado en Aimfox.

---

Arquitectura

┌─────────────────────────────────────────────────┐
│                  Spring Boot 4.0.4              │
│                   Java 25 / JVM                 │
│                                                 │
│  AuthController  ─────► AuthService             │
│  CampaignController ──► CampaignService         │
│                    └──► ProspectingService      │
│  UserController  ─────► UserService             │
│                                                 │
│  ProspectingService:                            │
│    1. LinkedInProfileExtractor (mock/API)       │
│    2. LlmService ──► LlmClient (Feign)         │
│       → OpenAI /v1/chat/completions             │
│    3. Virtual Thread (I/O non-blocking)         │
│                                                 │
│  Spring Security 7 (JWT Stateless)              │
│  Spring Data JPA + H2 (dev) / PostgreSQL (prod) │
└─────────────────────────────────────────────────┘

Capas:

Capa	Paquete	Responsabilidad
Controller	controller/	HTTP routing, validación entrada
Service	service/	Lógica de negocio
Repository	repository/	Spring Data JPA
Model	model/	Entidades JPA + enums
DTO	dto/	Java Records (inmutables)
Security	security/	JWT filter + UserDetails
Client	client/	Feign → OpenAI API

---

Endpoints

Auth — /api/auth

Method	Path	Auth	Body	Descripción
%%INLINE8%%	%%INLINE9%%	❌	RegisterRequest	Registro de usuario → devuelve JWT
%%INLINE11%%	%%INLINE12%%	❌	LoginRequest	Login → devuelve JWT

Users — /api/users

Method	Path	Auth	Descripción
%%INLINE15%%	%%INLINE16%%	✅	Perfil del usuario autenticado
%%INLINE17%%	%%INLINE18%%	✅	Upgrade subscription tier

Campaigns — /api/campaigns

Method	Path	Auth	Descripción
%%INLINE20%%	%%INLINE21%%	✅	Crear campaña
%%INLINE22%%	%%INLINE23%%	✅	Listar campañas del usuario
%%INLINE24%%	%%INLINE25%%	✅	Detalle de campaña + prospectos
%%INLINE26%%	%%INLINE27%%	✅	Actualizar campaña
%%INLINE28%%	%%INLINE29%%	✅	Eliminar campaña
%%INLINE30%%	%%INLINE31%%	✅	Añadir prospecto → genera mensajes (async, HTTP 202)
%%INLINE32%%	%%INLINE33%%	✅	Ver prospecto + borradores generados

Autenticación: Authorization: Bearer <token> en todas las rutas protegidas.

---

Flujo de Generación de Mensajes

POST /api/campaigns/{id}/prospects
  { "linkedinUrl": "https://linkedin.com/in/john-doe" }

  → HTTP 202 Accepted  { "id": 1, "status": "PENDING", ... }

[Virtual Thread]
  1. LinkedInProfileExtractor.extract(url)   ← mock / scraping API
  2. LlmService.generateMessages(profile, objective, productDesc, 3)
       → LlmClient.chat(request)  ← OpenAI API
  3. Persiste 3 × GeneratedMessage en BD
  4. Prospect.status = COMPLETED

GET /api/campaigns/{id}/prospects/1
  → { "status": "COMPLETED", "messages": [ {...}, {...}, {...} ] }

---

Modelos de Dominio

User (1) ──── (N) Campaign (1) ──── (N) Prospect (1) ──── (N) GeneratedMessage

• User: email, password (BCrypt), firstName, lastName, subscriptionTier, analysisUsedThisMonth
• Campaign: name, objective, productDescription, owner (User)
• Prospect: linkedinUrl, profileData, status (PENDING→PROCESSING→COMPLETED|FAILED)
• GeneratedMessage: content, messageIndex, prospect

---

Monetización

Tier	Análisis/mes	Precio sugerido
STARTER	50	$29/mes
PRO	300	$99/mes
BUSINESS	Ilimitado	$299/mes

Cada llamada a POST /api/campaigns/{id}/prospects consume 1 análisis. Al superar la cuota → HTTP 409 con mensaje de upgrade.

---

Cómo Ejecutar

Prerrequisitos

• Java 25+
• Maven 3.9+

Dev (H2 in-memory)

cd solutions/2026-06-09-prospect-iq-api
mvn spring-boot:run
# API disponible en http://localhost:8080

Con OpenAI real

APP_LLM_API_KEY=sk-... mvn spring-boot:run

Con PostgreSQL

Añadir a application.yml (o via env vars):

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/prospectiq
    username: postgres
    password: secret
  jpa:
    hibernate:
      ddl-auto: update
app:
  jwt-secret: "my-production-secret-key-min-32-chars"
  llm-api-key: "sk-..."

Ejemplo de uso con curl

# 1. Registrar usuario
curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@prospectiq.ai","password":"demo1234","firstName":"Demo","lastName":"User"}'

# 2. Login → obtener token
TOKEN=$(curl -s -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@prospectiq.ai","password":"demo1234"}' | grep -o '"token":"[^"]*"' | cut -d'"' -f4)

# 3. Crear campaña
curl -X POST http://localhost:8080/api/campaigns \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Q3 SaaS Outreach","objective":"schedule a product demo","productDescription":"AI-powered sales automation tool that saves 10h/week"}'

# 4. Añadir prospecto → dispara generación IA
curl -X POST http://localhost:8080/api/campaigns/1/prospects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"linkedinUrl":"https://linkedin.com/in/john-doe"}'

# 5. Ver mensajes generados
curl http://localhost:8080/api/campaigns/1/prospects/1 \
  -H "Authorization: Bearer $TOKEN"

---

Referencias

• Aimfox — Product Hunt Dec 2024
• Spring Boot 4.0 Reference
• Spring Security 7 Reference
• OpenAI Chat Completions API
• JJWT 0.12.x Migration Guide

---

Análisis de Negocio

Problema real, mercado masivo. Los BDRs gastan 30–40% de su tiempo en prospección manual. Un equipo de 5 BDRs ahorra ~20h/semana → ROI claro en el nivel PRO ($99/mes).

Ventaja competitiva sostenible. El LLM personaliza en función del perfil real: experiencia laboral, publicaciones recientes, habilidades. La tasa de respuesta sube de ~5% (mensaje genérico) a ~15-25% (mensaje ultra-personalizado, según estudios de vendors similares).

Riesgos mitigados en el MVP:

• ToS LinkedIn: se integra con proveedores de scraping conformes (ProxyCurl, Nubela)

en lugar de scraping directo. El MVP usa datos mock.

• Coste LLM: gpt-4o-mini a $0.15/1M tokens → análisis completo ≈ $0.002/prospecto.

Margen neto >95% incluso en nivel STARTER.

• Lock-in: arquitectura con LlmClient intercambiable soporta Anthropic Claude,

Mistral, o modelos propios sin cambios en la lógica de negocio.

---

Análisis FinOps para ProspectIQ

Resumen de Costos y Rentabilidad

ProspectIQ, como micro-startup de IA, presenta un modelo de negocio con un margen de beneficio saludable desde sus etapas iniciales, principalmente debido a la eficiencia de los modelos LLM modernos y una estructura de costos de infraestructura lean. Se estima un margen de beneficio del 78% con una base inicial de 25 clientes.

Desglose de Costos Mensuales Estimados (~$251.62):

• APIs Externas: ~$211.62

* LinkedIn Scraper API: $210 (Este es el costo dominante, asumiendo 3000 análisis de perfil/mes a $0.07 por scrape). Es el cuello de botella principal para la escalabilidad de costos. * LLM (OpenAI gpt-4o-mini): ~$1.62 (Para 7.2M tokens/mes, incluyendo entrada y salida. Este costo es sorprendentemente bajo y demuestra la eficiencia de los modelos 'mini').

• Infraestructura Cloud (AWS): ~$35

* EC2 t3.small: ~$20/mes (Para la aplicación Spring Boot). * RDS PostgreSQL db.t3.micro: ~$15/mes (Para la base de datos persistente).

• Monitoring/Otros: ~$5 (Costos básicos de logs y métricas).

Ingresos Mensuales Estimados:

Con un promedio de 25 clientes pagando $45/mes (una mezcla de planes 'Starter' y 'Pro'), los ingresos mensuales se estiman en $1125.

Estrategias de Optimización FinOps

Para mantener y mejorar este margen a medida que la startup crece, se proponen las siguientes optimizaciones:

1. Optimización del Uso de la API de Scraping de LinkedIn:

* Caché de Perfiles: Implementar una capa de caché robusta para los perfiles de LinkedIn scrapeados. Si un perfil ya fue analizado recientemente y no hay indicios de cambio, se puede servir desde caché, evitando una nueva llamada a la API de scraping (y al LLM). Esto es crucial dado que es el mayor costo. * Negociación por Volumen: A medida que la base de usuarios y el volumen de análisis crezcan, negociar activamente tarifas por volumen con el proveedor de la API de scraping para obtener descuentos significativos. * Monitoreo y Alertas: Establecer monitoreo detallado del uso de la API de scraping para identificar patrones de uso ineficientes o picos inesperados que puedan inflar los costos.

1. Gestión Eficiente del Uso de LLM:

* Optimización de Prompts: Revisar y refinar continuamente los prompts enviados al LLM para asegurar que son concisos y eficientes, minimizando la cantidad de tokens de entrada y salida sin comprometer la calidad de la personalización. * Evaluación de Modelos Alternativos: Aunque gpt-4o-mini es muy económico, a medida que la startup evolucione, evaluar si modelos más pequeños y especializados (ej. modelos de código abierto finetuneados para tareas de prospección) podrían ofrecer una relación coste/rendimiento aún mejor, potencialmente ejecutados en infraestructura propia o con proveedores de inferencia más competitivos. * Batch Processing (si aplica): Para ciertos tipos de análisis menos sensibles al tiempo, considerar el procesamiento por lotes durante horas de menor demanda para aprovechar posibles descuentos o una utilización más eficiente de recursos.

1. Optimización de la Infraestructura Cloud:

* Instancias Reservadas (RI) / Planes de Ahorro: Una vez que la carga de trabajo sea predecible y la startup se comprometa a un uso a largo plazo, adquirir RIs o Savings Plans para EC2 y RDS puede reducir los costos de infraestructura en un 30-60%. * Monitoreo de Recursos: Continuar monitoreando el uso de CPU, RAM y I/O de las instancias de EC2 y RDS. Escalar hacia abajo si los recursos están infrautilizados o considerar el uso de opciones serverless (ej. AWS Fargate para contenedores, Aurora Serverless para DB) si la carga es muy elástica y con picos, pagando solo por el consumo real. * Automatización de Apagado/Encendido: Para entornos de desarrollo/staging, implementar la automatización para apagar las instancias fuera del horario laboral.

1. Modelo de Monetización y Pricing:

* Análisis de Valor: Realizar un análisis continuo del valor percibido por el cliente y el costo real de cada análisis de perfil para ajustar los niveles de suscripción y los precios. Asegurar que el pricing refleje el valor entregado y cubra los costos crecientes de las APIs externas. * Tiers de Alto Volumen: Introducir tiers de 'Business' o 'Enterprise' con precios más elevados para clientes que requieren un volumen muy alto de análisis, lo que puede mejorar la rentabilidad general y permitir negociaciones de costos de scraping más agresivas.

Implementando estas estrategias FinOps, ProspectIQ puede asegurar una base de costos eficiente y mantener su alta rentabilidad a medida que escala.