Skill: dexpertmx/volkern-skill (version 1.1.1)

--- name: volkern-crm description: "Automate Volkern CRM operations including lead management, appointment scheduling, task tracking, service catalog, WhatsApp messaging, sales pipeline, quotations, and contracts. Requires API key authentication." requires: [REDACTED_SECRET] --- # Volkern CRM Automation Automate CRM operations including lead lifecycle management, appointment scheduling with availability checks, task creation, service catalog queries, WhatsApp communication, sales pipeline management, quotation/proposal generation, and contract handling through Volkern's REST API. ## Prerequisites - Volkern API Key with appropriate permissions - Base URL: `https://volkern.app/api` (or your custom domain) - All requests require `Authorization: Bearer {API_KEY}` header - Timestamps must be in ISO 8601 format (UTC): `yyyy-MM-ddTHH:mm:ss.fffZ` ## Setup 1. Log into Volkern dashboard 2. Navigate to **Configuración → API Keys** 3. Create a new API key with required permissions: - `leads:read`, `leads:write` for lead management - `citas:read`, `citas:write` for appointments - `servicios:read` for service catalog - `mensajes:write` for WhatsApp messaging 4. Copy the API key (shown only once) 5. Use the key in the `Authorization` header for all requests ## Core Workflows ### 1. Lead Management **When to use**: Create, update, search, or manage leads in the CRM **Tool sequence**: 1. `VOLKERN_LIST_LEADS` - Search and filter existing leads [Optional] 2. `VOLKERN_GET_LEAD` - Get detailed lead information by ID [Optional] 3. `VOLKERN_CREATE_LEAD` - Create a new lead [Required for new leads] 4. `VOLKERN_UPDATE_LEAD` - Update lead properties [Required for updates] **Key parameters**: | Endpoint | Method | Parameters | |----------|--------|------------| | `/api/leads` | GET | `estado`, `canal`, `etiqueta`, `search`, `page`, `limit` | | `/api/leads/{id}` | GET | `id` (path) | | `/api/leads` | POST | `nombre`*, `email`, `telefono`, `empresa`, `canal`, `estado`, `etiquetas`, `notas`, `contextoProyecto` | | `/api/leads/{id}` | PATCH | Any lead field to update | **Lead estados (stages)**: - `nuevo` - New lead, not contacted - `contactado` - Initial contact made - `calificado` - Qualified lead - `negociacion` - In negotiation - `cliente` - Converted to customer - `perdido` - Lost opportunity **Pitfalls**: - `nombre` is the only required field for lead creation - Email is validated for format but not uniqueness (upsert behavior: existing email updates the lead) - `canal` should match predefined values: `web`, `referido`, `whatsapp`, `telefono`, `email`, `otro` - `etiquetas` is an array of strings: `["vip", "urgente"]` --- ### 2. Appointment Scheduling **When to use**: Book appointments, check availability, manage calendar **Tool sequence**: 1. `VOLKERN_LIST_SERVICIOS` - Get available services with durations [Prerequisite] 2. `VOLKERN_CHECK_DISPONIBILIDAD` - Query available time slots [Required] 3. `VOLKERN_CREATE_CITA` - Book the appointment [Required] 4. `VOLKERN_LIST_CITAS` - List existing appointments [Optional] 5. `VOLKERN_UPDATE_CITA` - Reschedule or modify [Optional] 6. `VOLKERN_CANCEL_CITA` - Cancel appointment [Optional] **Key parameters**: | Endpoint | Method | Parameters | |----------|--------|------------| | `/api/citas/disponibilidad` | GET | `fecha`* (YYYY-MM-DD), `duracion` (minutes, default 60) | | `/api/citas` | GET | `estado`, `tipo`, `fecha`, `fechaInicio`, `fechaFin` | | `/api/citas` | POST | `leadId`*, `fechaHora`*, `tipo`, `titulo`, `descripcion`, `duracion`, `servicioId` | | `/api/citas/{id}` | PATCH | `fechaHora`, `estado`, `duracion`, `descripcion` | | `/api/citas/accion` | POST | `citaId`*, `accion`* (`confirmar`\|`cancelar`\|`reprogramar`) | **Availability response structure**: ```json { "fecha": "2026-02-10", "dia": "lunes", "diaActivo": true, "horarioLaboral": { "rangos": [{"inicio": "09:00", "fin": "13:00"}, {"inicio": "15:00", "fin": "18:00"}], "resumen": "09:00-13:00, 15:00-18:00" }, "disponibles": { "total": 12, "slots": ["2026-02-10T09:00:00.000Z", "2026-02-10T09:30:00.000Z", ...] }, "ocupados": { "total": 2, "slots": [{"hora": "...", "cita": {"id": "...", "titulo": "..."}}] } } ``` **Cita tipos**: - `reunion` - General meeting (default) - `servicio` - Service appointment (requires `servicioId`) - `llamada` - Phone call - `otro` - Other **Cita estados**: - `Pendiente` - Awaiting confirmation - `Confirmada` - Confirmed by client - `Completada` - Meeting completed - `Cancelada` - Cancelled - `Pagada` - Paid (for paid services) **Pitfalls**: - Always check `diaActivo` before attempting to book - inactive days return 0 slots - `duracion` must be an integer (minutes), not a string - `fechaHora` must be ISO 8601 UTC format - Booking on an occupied slot returns `409 Conflict` with suggested alternatives - Weekend availability depends on tenant configuration in **Configuración → Horarios** --- ### 3. Task Management **When to use**: Create follow-up tasks, reminders, or activities for leads **Tool sequence**: 1. `VOLKERN_GET_LEAD` - Verify lead exists [Prerequisite] 2. `VOLKERN_CREATE_TASK` - Create task for the lead [Required] 3. `VOLKERN_LIST_TASKS` - Get lead's pending tasks [Optional] 4. `VOLKERN_COMPLETE_TASK` - Mark task as done [Optional] **Key parameters**: | Endpoint | Method | Parameters | |----------|--------|------------| | `/api/leads/{leadId}/tasks` | GET | `leadId` (path) | | `/api/leads/{leadId}/tasks` | POST | `tipo`*, `titulo`*, `fechaVencimiento`*, `descripcion`, `asignadoA` | | `/api/tasks/{taskId}` | PATCH | `completada`, `fechaCompletado` | **Task tipos**: - `llamada` - Phone call to make - `email` - Email to send - `reunion` - Meeting to schedule - `recordatorio` - General reminder **Pitfalls**: - `tipo` must be lowercase and one of the valid values - `fechaVencimiento` is required and must be a future date - Tasks are automatically associated with the tenant via the API key --- ### 4. Service Catalog **When to use**: Query available services for booking or pricing information **Tool sequence**: 1. `VOLKERN_LIST_SERVICIOS` - Get all services [Required] 2. `VOLKERN_GET_SERVICIO` - Get specific service details [Optional] **Key parameters**: | Endpoint | Method | Parameters | |----------|--------|------------| | `/api/servicios` | GET | `activo` (boolean) | | `/api/servicios/{id}` | GET | `id` (path) | **Service response structure**: ```json { "id": "clxyz...", "nombre": "Consultoría Inicial", "descripcion": "Sesión de 60 minutos...", "duracionMinutos": 60, "precio": 150.00, "moneda": "EUR", "modalidad": "virtual", "activo": true } ``` **Modalidades**: - `presencial` - In-person - `virtual` - Online/video call - `hibrido` - Hybrid (generates Google Meet link if connected) **Pitfalls**: - Only `activo: true` services should be offered for booking - `duracionMinutos` determines the slot blocking duration - Prices are in the tenant's configured currency --- ### 5. WhatsApp Messaging **When to use**: Send WhatsApp messages to leads via connected integration **Tool sequence**: 1. `VOLKERN_GET_LEAD` - Get lead's phone number [Prerequisite] 2. `VOLKERN_SEND_WHATSAPP` - Send message [Required] 3. `VOLKERN_LIST_CONVERSACIONES` - View conversation history [Optional] **Key parameters**: | Endpoint | Method | Parameters | |----------|--------|------------| | `/api/mensajes/enviar` | POST | `leadId`*, `mensaje`*, `tipo` | | `/api/mensajes/conversaciones` | GET | `leadId`, `page`, `limit` | | `/api/mensajes/conversaciones/{id}` | GET | `id` (path) | **Message tipos**: - `texto` - Plain text message - `imagen` - Image with optional caption - `documento` - Document attachment **Pitfalls**: - Requires active WhatsApp integration (Evolution API or Anytimebot) - Lead must have a valid `telefono` field with country code - Message delivery is async; check conversation history for status - Rate limits apply based on WhatsApp Business policies --- ### 6. Lead Interactions **When to use**: Record calls, meetings, or other activities with leads **Tool sequence**: 1. `VOLKERN_GET_LEAD` - Verify lead exists [Prerequisite] 2. `VOLKERN_LIST_INTERACTIONS` - View existing interactions [Optional] 3. `VOLKERN_CREATE_INTERACTION` - Log the interaction [Required] **Key parameters**: | Endpoint | Method | Parameters | |----------|--------|------------| | `/api/leads/{id}/interactions` | GET | `id` (path) - Returns all interactions for the lead | | `/api/leads/{id}/interactions` | POST | `tipo`*, `contenido`*, `resultado`, `metadatos` | **Interaction tipos**: - `llamada` - Phone call - `email` - Email sent/received - `whatsapp` - WhatsApp message - `reunion` - Meeting held - `nota` - Internal note - `otro` - Other interaction type **Resultado values**: - `positivo` - Positive outcome - `neutro` - Neutral - `negativo` - Negative outcome **Response structure**: ```json { "success": true, "interaction": { "id": "clxyz...", "leadId": "clxyz...", "tipo": "llamada", "contenido": "Discussed pricing options...", "resultado": "positivo", "metadatos": { "duracion": "15min" }, "fechaCreacion": "2026-02-09T10:00:00Z", "creador": { "id": "...", "name": "John", "email": "[REDACTED_SECRET]" } } } ``` **Pitfalls**: - `tipo` must be lowercase - Interactions automatically update lead's `fechaUltimaActividad` - Triggers `interaccion_creada` automation event --- ### 7. Lead Notes **When to use**: Add internal notes or observations about leads **Tool sequence**: 1. `VOLKERN_GET_LEAD` - Verify lead exists [Prerequisite] 2. `VOLKERN_LIST_NOTES` - View existing notes [Optional] 3. `VOLKERN_CREATE_NOTE` - Add a new note [Required] **Key parameters**: | Endpoint | Method | Parameters | |----------|--------|------------| | `/api/leads/{id}/notes` | GET | `id` (path) - Returns all notes for the lead | | `/api/leads/{id}/notes` | POST | `contenido`*, `titulo` (optional) | **Response structure**: ```json { "success": true, "note": { "id": "clxyz...", "leadId": "clxyz...", "contenido": "**Important**\n\nClient prefers morning calls...", "fechaCreacion": "2026-02-09T10:00:00Z", "creador": { "id": "...", "name": "John", "email": "[REDACTED_SECRET]" } } } ``` **Pitfalls**: - If `titulo` is provided, it's prepended to `contenido` as bold markdown - Notes automatically update lead's `fechaUltimaActividad` - Triggers `nota_creada` automation event --- ### 8. Contacts & Companies **When to use**: Manage business contacts (persons) and companies separately from leads **Tool sequence**: 1. `VOLKERN_LIST_CONTACTS` - Search and filter contacts [Optional] 2. `VOLKERN_GET_CONTACT` - Get detailed contact information [Optional] 3. `VOLKERN_CREATE_CONTACT` - Create a new contact or company [Required for new] 4. `VOLKERN_UPDATE_CONTACT` - Update contact properties [Required for updates] **Key parameters**: | Endpoint | Method | Parameters | |----------|--------|------------| | `/api/contacts` | GET | `tipo` (person/company), `search`, `page`, `limit` | | `/api/contacts/{id}` | GET | `id` (path) | | `/api/contacts` | POST | `nombre`*, `email`, `telefono`, `tipo`, `cargo`, `ubicacion`, `companyId`, `linkedin`, `notas`, `tags` | | `/api/contacts/{id}` | PATCH | Any contact field to update | **Contact tipos**: - `person` - Individual person (default) - `company` - Business/organization **Response structure**: ```json { "id": "clxyz...", "nombre": "María García", "email": "[REDACTED_SECRET]", "telefono": "+34612345678", "tipo": "person", "cargo": "Directora de Marketing", "ubicacion": "Madrid, España", "company": { "id": "...", "nombre": "Empresa S.L." }, "linkedin": "https://linkedin.com/in/mariagarcia", "tags": ["VIP", "Decision Maker"], "deals": [{ "id": "...", "titulo": "..." }], "fechaCreacion": "2026-02-09T10:00:00Z" } ``` **Pitfalls**: - `nombre` is the only required field - `companyId` links a person to their company - Companies can have multiple associated contacts - Use `tipo=company` to list only companies --- ### 9. Sales Pipeline (Deals) **When to use**: Manage sales opportunities through pipeline stages **Tool sequence**: 1. `VOLKERN_LIST_PIPELINE_STAGES` - Get configured stages [Prerequisite] 2. `VOLKERN_LIST_DEALS` - Search and filter deals [Optional] 3. `VOLKERN_CREATE_DEAL` - Create a new opportunity [Required for new] 4. `VOLKERN_UPDATE_DEAL` - Move stage, update value, close deal [Required for updates] 5. `VOLKERN_GET_SALES_FORECAST` - Get pipeline analytics [Optional] **Key parameters**: | Endpoint | Method | Parameters | |----------|--------|------------| | `/api/pipeline/stages` | GET | - | | `/api/deals` | GET | `etapa`, `estado`, `prioridad`, `search`, `page`, `limit` | | `/api/deals/{id}` | GET | `id` (path) | | `/api/deals` | POST | `titulo`*, `valor`, `moneda`, `etapa`, `prioridad`, `probabilidad`, `fechaEstimadaCierre`, `leadId`, `contactId`, `companyId`, `descripcion` | | `/api/deals/{id}` | PATCH | Any deal field to update | | `/api/deals/forecast` | GET | `periodo` (mes/trimestre/año) | **Deal estados**: - `abierto` - Active opportunity (default) - `ganado` - Won deal - `perdido` - Lost deal **Deal prioridades**: - `baja` - Low priority - `media` - Medium priority - `alta` - High priority **Default pipeline stages** (probability in %): | Stage | Probability | |-------|-------------| | Calificación | 10% | | Contacto Inicial | 25% | | Propuesta | 50% | | Negociación | 75% | | Cierre | 90% | | Ganado | 100% | | Perdido | 0% | **Forecast response structure**: ```json { "basicForecast": { "total": 125000, "ponderado": 45000 }, "adjustedForecast": { "total": 42000, "confianza": 0.85 }, "conversionRates": { "Calificación": { "teorica": 10, "real": 8.5 } }, "cycleTime": { "promedioDias": 45 }, "projection6Months": [{ "mes": "Feb 2026", "estimado": 15000 }], "historicalSales": [{ "mes": "Jan 2026", "total": 12000 }], "funnel": [{ "etapa": "Calificación", "cantidad": 10, "valor": 50000 }], "topDeals": [{ "id": "...", "titulo": "...", "valorPonderado": 15000 }] } ``` **Pitfalls**: - `titulo` is the only required field - `etapa` must match exact stage name (case-sensitive) - `probabilidad` auto-updates when changing `etapa` - Moving to "Ganado" auto-sets `estado: ganado` and `probabilidad: 100` - Moving to "Perdido" auto-sets `estado: perdido` and `probabilidad: 0` --- ### 10. Quotations (Cotizaciones) **When to use**: Create and send price quotes/proposals to clients **Tool sequence**: 1. `VOLKERN_GET_LEAD` or `VOLKERN_GET_DEAL` - Get client info [Prerequisite] 2. `VOLKERN_LIST_COTIZACIONES` - View existing quotes [Optional] 3. `VOLKERN_CREATE_COTIZACION` - Create new quote with items [Required] 4. `VOLKERN_UPDATE_COTIZACION` - Edit quote (only in borrador status) [Optional] 5. `VOLKERN_SEND_COTIZACION` - Email quote to client [Optional] **Key parameters**: | Endpoint | Method | Parameters | |----------|--------|------------| | `/api/cotizaciones` | GET | `estado`, `search`, `page`, `limit` | | `/api/cotizaciones/{id}` | GET | `id` (path) | | `/api/cotizaciones` | POST | `leadId`, `dealId`, `validezDias`, `notas`, `items`* | | `/api/cotizaciones/{id}` | PATCH | `estado`, `validezDias`, `notas`, `items` | | `/api/cotizaciones/{id}/send` | POST | `mensaje` (optional email text) | **Item structure**: ```json { "concepto": "Consultoría inicial", "cantidad": 2, "precioUnitario": 150.00, "descuento": 10 } ``` **Cotización estados**: - `borrador` - Draft (editable) - `enviada` - Sent to client - `aceptada` - Accepted by client - `rechazada` - Rejected - `expirada` - Validity expired **Response structure**: ```json { "id": "clxyz...", "numero": "COT-2026-0001", "estado": "borrador", "subtotal": 270.00, "iva": 56.70, "total": 326.70, "validezDias": 30, "fechaExpiracion": "2026-03-11", "items": [...], "lead": { "nombre": "...", "email": "..." }, "urlPublica": "https://volkern.app/cotizacion/abc123" } ``` **Pitfalls**: - `items` array is required with at least one item - Only `borrador` status quotes can be edited - Quote number is auto-generated (COT-YYYY-####) - `validezDias` defaults to 30 if not specified - Client can accept quote via public URL - Accepted quotes can be converted to contracts --- ### 11. Contracts (Contratos) **When to use**: Create formal contracts from accepted quotes or manually **Tool sequence**: 1. `VOLKERN_LIST_COTIZACIONES` - Find accepted quote [Optional] 2. [REDACTED_SECRET] - Convert quote to contract [Option A] 3. `VOLKERN_CREATE_CONTRATO` - Create contract manually [Option B] 4. `VOLKERN_LIST_CONTRATOS` - View existing contracts [Optional] 5. `VOLKERN_SEND_CONTRATO` - Send for client signature [Required] **Key parameters**: | Endpoint | Method | Parameters | |----------|--------|------------| | `/api/contratos` | GET | `estado`, `tipo`, `search`, `page`, `limit` | | `/api/contratos/{id}` | GET | `id` (path) | | `/api/contratos` | POST | `titulo`*, `tipo`, `leadId`, `dealId`, `cotizacionId`, `fechaInicio`, `fechaFin`, `metodoPago`, `clausulas`, `items` | | `/api/contratos/from-cotizacion/{cotizacionId}` | POST | `fechaInicio`, `fechaFin`, `metodoPago`, `clausulas` | | `/api/contratos/{id}/send` | POST | `mensaje` (optional email text) | **Contrato tipos**: - `servicios` - Service agreement - `productos` - Product sale - `suscripcion` - Subscription - `proyecto` - Project-based - `otro` - Other **Contrato estados**: - `borrador` - Draft - `enviado` - Sent for signature - `firmado_cliente` - Signed by client - `firmado_empresa` - Signed by company - `activo` - Both signatures, active - `completado` - Fulfilled - `cancelado` - Cancelled **Método de pago**: - `unico` - Single payment - `mensual` - Monthly payments - `trimestral` - Quarterly payments - `anual` - Annual payments **Response structure**: ```json { "id": "clxyz...", "numero": "CONT-2026-0001", "titulo": "Contrato de Servicios", "tipo": "servicios", "estado": "enviado", "total": 12000.00, "fechaInicio": "2026-02-15", "fechaFin": "2027-02-14", "metodoPago": "mensual", "firmadoPorCliente": false, "firmadoPorEmpresa": false, "items": [...], "pagos": [...], "urlPublica": "https://volkern.app/contrato/xyz789" } ``` **Pitfalls**: - Contract number is auto-generated (CONT-YYYY-####) - Creating from cotización copies items automatically - Client signs via public URL (no login required) - Payment schedule is auto-generated based on `metodoPago` - `activo` status requires both signatures - Digital signatures include timestamp and IP --- ## Common Patterns ### ID Resolution Volkern uses CUID format for all entity IDs: - Example: `clxyz123abc456def789` - Always retrieve IDs from list/create responses - Never construct IDs manually ### Pagination List endpoints support pagination: ``` GET /api/leads?page=1&limit=50 ``` - Default `limit`: 50 - Maximum `limit`: 100 - Response includes `total` count for pagination UI ### Time Handling - All timestamps are in **UTC** - Format: `yyyy-MM-ddTHH:mm:ss.fffZ` - Availability queries use date only: `YYYY-MM-DD` - Frontend displays in tenant's configured timezone ### Error Handling Standard HTTP status codes: - `200` - Success - `201` - Created - `400` - Bad Request (validation error) - `401` - Unauthorized (invalid/missing API key) - `404` - Not Found - `409` - Conflict (e.g., scheduling conflict) - `500` - Server Error Error response format: ```json { "error": "Descriptive error message", "details": "Additional context", "hint": "How to fix the issue" } ``` --- ## Quick Reference | Task | Endpoint | Method | Key Params | |------|----------|--------|------------| | **LEADS** | | | | | List leads | `/api/leads` | GET | `estado`, `search`, `page` | | Get lead | `/api/leads/{id}` | GET | `id` | | Create lead | `/api/leads` | POST | `nombre`*, `email`, `telefono` | | Update lead | `/api/leads/{id}` | PATCH | Any field | | **APPOINTMENTS** | | | | | Check availability | `/api/citas/disponibilidad` | GET | `fecha`*, `duracion` | | List appointments | `/api/citas` | GET | `estado`, `fecha` | | Create appointment | `/api/citas` | POST | `leadId`*, `fechaHora`*, `tipo` | | Update appointment | `/api/citas/{id}` | PATCH | `estado`, `fechaHora` | | Confirm/Cancel | `/api/citas/accion` | POST | `citaId`*, `accion`* | | **SERVICES** | | | | | List services | `/api/servicios` | GET | `activo` | | Get service | `/api/servicios/{id}` | GET | `id` | | **TASKS** | | | | | Create task | `/api/leads/{id}/tasks` | POST | `tipo`*, `titulo`*, `fechaVencimiento`* | | List tasks | `/api/leads/{id}/tasks` | GET | - | | Complete task | `/api/tasks/{id}` | PATCH | `completada: true` | | **MESSAGING** | | | | | Send WhatsApp | `/api/mensajes/enviar` | POST | `leadId`*, `mensaje`* | | List conversations | `/api/mensajes/conversaciones` | GET | `leadId` | | **INTERACTIONS** | | | | | List interactions | `/api/leads/{id}/interactions` | GET | - | | Create interaction | `/api/leads/{id}/interactions` | POST | `tipo`*, `contenido`*, `resultado` | | **NOTES** | | | | | List notes | `/api/leads/{id}/notes` | GET | - | | Add note | `/api/leads/{id}/notes` | POST | `contenido`*, `titulo` | | **CONTACTS** | | | | | List contacts | `/api/contacts` | GET | `tipo`, `search`, `page` | | Get contact | `/api/contacts/{id}` | GET | `id` | | Create contact | `/api/contacts` | POST | `nombre`*, `email`, `tipo` | | Update contact | `/api/contacts/{id}` | PATCH | Any field | | **DEALS** | | | | | List pipeline stages | `/api/pipeline/stages` | GET | - | | List deals | `/api/deals` | GET | `etapa`, `estado`, `search` | | Get deal | `/api/deals/{id}` | GET | `id` | | Create deal | `/api/deals` | POST | `titulo`*, `valor`, `etapa` | | Update deal | `/api/deals/{id}` | PATCH | `etapa`, `estado`, `valor` | | Sales forecast | `/api/deals/forecast` | GET | `periodo` | | **QUOTATIONS** | | | | | List quotes | `/api/cotizaciones` | GET | `estado`, `search` | | Get quote | `/api/cotizaciones/{id}` | GET | `id` | | Create quote | `/api/cotizaciones` | POST | `items`*, `leadId`, `dealId` | | Update quote | `/api/cotizaciones/{id}` | PATCH | `items`, `notas` | | Send quote | `/api/cotizaciones/{id}/send` | POST | `mensaje` | | **CONTRACTS** | | | | | List contracts | `/api/contratos` | GET | `estado`, `tipo`, `search` | | Get contract | `/api/contratos/{id}` | GET | `id` | | Create contract | `/api/contratos` | POST | `titulo`*, `tipo`, `items` | | Create from quote | `/api/contratos/from-cotizacion/{id}` | POST | `fechaInicio`, `metodoPago` | | Send contract | `/api/contratos/{id}/send` | POST | `mensaje` | \* = Required field --- ## Known Pitfalls ### Authentication - API keys are tenant-scoped; one key per organization - Keys can have granular permissions; check scope if getting 401/403 - Never expose API keys in client-side code ### Data Validation - Phone numbers should include country code: `+34612345678` - Email validation is strict; malformed emails are rejected - Dates in the past may be rejected for appointments ### Scheduling Conflicts - The system validates overlapping appointments - Use `disponibilidad` endpoint before booking - 409 responses include suggested alternative slots ### WhatsApp Integration - Requires pre-configured integration (Evolution API) - First message to new number requires template approval - Media messages have size limits (16MB for images) ### Rate Limits - Standard: 100 requests/minute per API key - Bulk operations: 10 requests/minute - WhatsApp: Subject to Meta's messaging limits

path: readme.md
content: # Volkern MCP Server (v1.1.0)

Servidor MCP (Model Context Protocol) para integrar Volkern CRM con agentes de IA como Claude, GPT, y otros clientes compatibles con MCP.

## Novedades v1.1.0 - Catálogo Mejorado

### Nuevas Herramientas de Catálogo
- `volkern_list_catalogo` - Listar ítems con filtros avanzados (tipo, categoría, etiqueta)
- `volkern_get_catalogo_item` - Obtener detalle completo de un ítem
- `volkern_create_catalogo_item` - Crear ítem con campos personalizados, categorías, media y precios flexibles
- `volkern_update_catalogo_item` - Actualizar cualquier campo de un ítem
- `volkern_search_catalogo` - Búsqueda por texto en nombre, descripción y SKU

### Funcionalidades Soportadas
- **Campos personalizados**: Atributos dinámicos por ítem (metros², habitaciones, idioma, etc.)
- **Categorías multinivel**: Organización jerárquica (Inmuebles > Oficina > Lujo)
- **Etiquetas**: Tags para filtrado rápido (vip, oportunidad, nuevo)
- **Galería multimedia**: Imágenes, video tours, documentos técnicos, tours 360°
- **Precios flexibles**: Pago único, recurrente o por hora con descuentos por volumen

## Instalación

### Opción 1: Instalación global desde NPM (Recomendado)

```bash
npm install -g volkern-mcp-server
```

### Opción 2: Usando npx (sin instalación)

```bash
npx volkern-mcp-server
```

### Opción 3: Desde código fuente

```bash
git clone https://github.com/volkern/mcp-server.git
cd mcp-server
npm install
npm run build
```

## Configuración

El servidor requiere las siguientes variables de entorno:

```bash
export VOLKERN_API_KEY="tu_api_key_aqui"
export VOLKERN_API_URL="https://volkern.app/api"  # Opcional, usa este valor por defecto
```

## Uso con Claude Desktop

Agrega la siguiente configuración a tu archivo `claude_desktop_config.json`:

### Si instalaste con NPM (Recomendado)

```json
{
  "mcpServers": {
    "volkern": {
      "command": "volkern-mcp",
      "env": {
        "VOLKERN_API_KEY": "tu_api_key_aqui"
      }
    }
  }
}
```

### Si usas npx

```json
{
  "mcpServers": {
    "volkern": {
      "command": "npx",
      "args": ["volkern-mcp-server"],
      "env": {
        "VOLKERN_API_KEY": "tu_api_key_aqui"
      }
    }
  }
}
```

### Si instalaste desde código fuente

**macOS/Linux:**
```json
{
  "mcpServers": {
    "volkern": {
      "command": "node",
      "args": ["/ruta/a/volkern-mcp-server/dist/index.js"],
      "env": {
        "VOLKERN_API_KEY": "tu_api_key_aqui"
      }
    }
  }
}
```

**Windows:**
```json
{
  "mcpServers": {
    "volkern": {
      "command": "node",
      "args": ["C:\\ruta\\a\\volkern-mcp-server\\dist\\index.js"],
      "env": {
        "VOLKERN_API_KEY": "tu_api_key_aqui"
      }
    }
  }
}
```

## Herramientas Disponibles

### Gestión de Leads
| Herramienta | Descripción |
|-------------|-------------|
| `volkern_list_leads` | Listar leads con filtros opcionales |
| `volkern_get_lead` | Obtener detalles de un lead por ID |
| `volkern_create_lead` | Crear un nuevo lead |
| `volkern_update_lead` | Actualizar un lead existente |

### Citas/Appointments
| Herramienta | Descripción |
|-------------|-------------|
| `volkern_check_disponibilidad` | Consultar horarios disponibles |
| `volkern_list_citas` | Listar citas con filtros |
| `volkern_create_cita` | Crear una nueva cita |
| `volkern_update_cita` | Actualizar una cita |
| `volkern_cita_accion` | Confirmar, cancelar o reprogramar |

### Servicios
| Herramienta | Descripción |
|-------------|-------------|
| `volkern_list_servicios` | Listar servicios del catálogo |
| `volkern_get_servicio` | Obtener detalles de un servicio |

### Tareas
| Herramienta | Descripción |
|-------------|-------------|
| `volkern_create_task` | Crear tarea de seguimiento |
| `volkern_list_tasks` | Listar tareas de un lead |
| `volkern_complete_task` | Marcar tarea como completada |

### Mensajería
| Herramienta | Descripción |
|-------------|-------------|
| `volkern_send_whatsapp` | Enviar mensaje de WhatsApp |
| `volkern_list_conversaciones` | Listar conversaciones |

### Interacciones
| Herramienta | Descripción |
|-------------|-------------|
| `volkern_list_interactions` | Listar interacciones de un lead |
| `volkern_create_interaction` | Registrar llamada, email, reunión |

### Notas
| Herramienta | Descripción |
|-------------|-------------|
| `volkern_list_notes` | Listar notas de un lead |
| `volkern_create_note` | Agregar nota a un lead |

## Ejemplos de Uso

### Crear un lead y agendar cita

```
Usuario: Crea un lead para Juan Pérez, email [REDACTED_SECRET], y agenda una cita para mañana a las 10am

Agente:
1. volkern_create_lead(nombre: "Juan Pérez", email: "[REDACTED_SECRET]")
2. volkern_check_disponibilidad(fecha: "2026-02-09")
3. volkern_create_cita(leadId: "...", fechaHora: "2026-02-09T10:00:00Z", titulo: "Reunión inicial")
```

### Consultar disponibilidad

```
Usuario: ¿Qué horarios hay disponibles para el lunes?

Agente:
1. volkern_check_disponibilidad(fecha: "2026-02-10")
```

### Crear tarea de seguimiento

```
Usuario: Crea un recordatorio para llamar a Juan mañana

Agente:
1. volkern_list_leads(search: "Juan")
2. volkern_create_task(leadId: "...", tipo: "llamada", titulo: "Llamar a Juan", fechaVencimiento: "2026-02-09T09:00:00Z")
```

## Desarrollo

```bash
# Ejecutar en modo desarrollo
npm run dev

# Compilar
npm run build

# Ejecutar compilado
npm start
```

## Troubleshooting

### Error: VOLKERN_API_KEY not set
Asegúrate de configurar la variable de entorno antes de iniciar el servidor.

### Error 401: No autorizado
Verifica que tu API key tenga los permisos necesarios en Volkern (Configuración → API Keys).

### Error 409: Conflicto de horario
El slot solicitado ya está ocupado. Consulta disponibilidad con `volkern_check_disponibilidad`.

## Licencia

MIT


path: package.json
content: {
  "name": "volkern-mcp-server",
  "version": "1.1.0",
  "description": "MCP Server for Volkern CRM - Lead management, appointments, tasks, and WhatsApp messaging integration",
  "main": "dist/index.js",
  "bin": {
    "volkern-mcp": "dist/index.js"
  },
  "type": "module",
  "scripts": {
    "build": "npx tsc",
    "start": "node dist/index.js",
    "dev": "npx tsx src/index.ts",
    "prepublishOnly": "npm run build"
  },
  "keywords": [
    "mcp",
    "model-context-protocol",
    "volkern",
    "crm",
    "leads",
    "appointments",
    "whatsapp",
    "claude",
    "ai-agent"
  ],
  "author": "Volkern <[REDACTED_SECRET]>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/volkern/mcp-server"
  },
  "homepage": "https://volkern.app",
  "bugs": {
    "url": "https://github.com/volkern/mcp-server/issues"
  },
  "engines": {
    "node": ">=18.0.0"
  },
  "files": [
    "dist",
    "README.md"
  ],
  "dependencies": {
    "@modelcontextprotocol/sdk": "^0.5.0",
    "zod": "^3.23.8"
  },
  "devDependencies": {
    "@types/node": "^20.6.2",
    "tsx": "^4.20.3",
    "typescript": "^5.9.3"
  }
}


path: tsconfig.json
content: {
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}


path: dist/index.d.ts
content: #!/usr/bin/env node
export {};


Security scan verdicts — ClawScan: clean | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)