volkern-skill（沃尔克恩技能）

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

1. Copy the API key (shown only once)
2. 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:

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:

Availability response structure:

{
  "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:

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:

Service response structure:

{
  "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:

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:

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:

{
  "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": "john@example.com" }
  }
}

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:

Response structure:

{
  "success": true,
  "note": {
    "id": "clxyz...",
    "leadId": "clxyz...",
    "contenido": "**Important**\
\
Client prefers morning calls...",
    "fechaCreacion": "2026-02-09T10:00:00Z",
    "creador": { "id": "...", "name": "John", "email": "john@example.com" }
  }
}

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:

Contact tipos:

• person - Individual person (default)
• company - Business/organization

Response structure:

{
  "id": "clxyz...",
  "nombre": "María García",
  "email": "maria@empresa.com",
  "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:

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 %):

Forecast response structure:

{
  "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:

Item structure:

{
  "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:

{
  "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. VOLKERN_CREATE_CONTRATO_FROM_COTIZACION - 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:

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:

{
  "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:

{
  "error": "Descriptive error message",
  "details": "Additional context",
  "hint": "How to fix the issue"
}

Quick Reference

\* = 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