Prompt para integrar con IA
Pega este prompt en Claude, ChatGPT, Cursor o tu asistente de código antes de empezar una integración. Le explica cómo está organizada la API, sus convenciones y dónde leer la especificación OpenAPI, para que no se invente endpoints.
Cómo usarlo
- Copia el prompt y sustituye lo resaltado por lo que quieres integrar.
- Pégalo al empezar una conversación nueva en tu asistente de IA.
- Si tu asistente puede navegar o leer URLs, pídele que descargue la especificación OpenAPI antes de escribir código.
Vas a ayudarme a construir una integración con la API REST pública de Vixiees. Vixiees es un sistema de ventas para equipos comerciales: contactos, deals, tareas, llamadas, WhatsApp y Cerebros de Ventas (playbooks). ## Mi objetivo Describe qué quieres integrar, por ejemplo: sincronizar los contactos de Vixiees con mi CRM cada noche ## Fuente de verdad - Especificación OpenAPI (léela antes de escribir código y consúltala para cada endpoint que uses): https://api.vixiees.com/api-docs/v1/swagger.yaml - No inventes endpoints, campos, parámetros ni valores de enums: si algo no está en la especificación, no existe. - Documentación para personas: https://developers.vixiees.com/es - Resumen para modelos: https://developers.vixiees.com/llms.txt ## Lo básico - URL base: https://api.vixiees.com/api/v1 - Autenticación: cabecera `X-Api-Key: <API_KEY>`. La clave se obtiene en Vixiees, en Settings → Account → API. Léela de una variable de entorno (por ejemplo `VIXIEES_API_KEY`); nunca la pongas en el código ni en el frontend. - Peticiones y respuestas en JSON, salvo las subidas de ficheros, que van en multipart cuando la especificación lo indica. - Los IDs son cadenas hexadecimales de 24 caracteres. ## Convenciones - Paginación: `page` (desde 1) y `limit` (máximo 100). Recorre páginas hasta que una devuelva menos de `limit` resultados. - Sincronización incremental: usa los filtros de fecha de cada endpoint (por ejemplo `updated_at_from` / `updated_at_to` en `GET /contacts`). - Límites de uso: 25 peticiones por minuto por licencia (×60 por hora, ×24 por día) y un tope absoluto de 40 peticiones cada 2 segundos. Si recibes `429`, espera y reintenta con backoff exponencial. - Errores: `{ "error": "mensaje", "details": { ... } }`. Códigos habituales: 400 (parámetros inválidos), 401 (API key inválida), 404 (no existe), 422 (validación o límite de paginación), 429 (límite de uso). ## Webhooks - Vixiees hace un `POST` a una única URL tuya (configurada en Settings → Account → API) con el cuerpo `{ "event", "payload", "timestamp", "source" }`; `timestamp` es Unix en segundos. - Responde 2xx rápido y procesa en segundo plano. Haz que el receptor sea idempotente, para que procesar dos veces el mismo evento no duplique datos. - Para cambios en tiempo real, usa webhooks en lugar de consultar la API cada poco. ## Mapa de la API ### Recursos - **Contacts** (Manage contacts (leads and clients)) - `POST /contacts/{contact_id}/calls`: Logs a call made outside Vixiees - `GET /contacts/{contact_id}/documents`: Retrieves documents for a contact - `POST /contacts/{contact_id}/documents`: Uploads a document to a contact - `GET /contacts/{contact_id}/feed`: Retrieves the activity feed for a contact - `GET /contacts/{contact_id}/whatsapp_conversations`: Retrieves whatsapp conversations for a contact - `GET /contacts`: Retrieves contacts - `POST /contacts`: Creates a new contact - `GET /contacts/{id}`: Retrieves a specific contact - `DELETE /contacts/{id}`: Deletes a contact - `PUT /contacts/{id}`: Updates a contact - `POST /contacts/{id}/update_current_playbook`: Updates a contact's current playbook - `POST /contacts/{id}/assign_user`: Assigns a user to a contact - `POST /contacts/{id}/add_comment`: Adds a comment to a contact - **Deals** (Track sales opportunities) - `GET /deals`: Retrieves deals - `POST /deals`: Creates a new deal - `GET /deals/{id}`: Retrieves a deal - `PUT /deals/{id}`: Updates a deal - `DELETE /deals/{id}`: Deletes a deal - **Tasks** (Manage follow-up tasks) - `GET /tasks`: Retrieves tasks - `POST /tasks`: Creates a new task - `POST /tasks/{id}/cancel`: Cancels a task - `POST /tasks/{id}/complete`: Completes a task - **Task Templates** (Task template definitions) - `GET /task_templates`: Retrieves task templates - **Playbooks** (Sales workflow definitions) - `GET /playbooks`: Retrieves all playbooks - **Flow Steps** (Stages within playbooks) - `GET /playbooks/{playbook_id}/flow_steps`: Retrieves flow steps for a playbook - **Contracts** (Contract documents) - `GET /contracts`: Retrieves contracts - **Submitted Forms** (Lead capture forms) - `GET /submitted_forms`: Retrieves submitted forms - `GET /submitted_forms/{id}`: Retrieves a submitted form - **Call Recordings** (Access call recordings) - `GET /call_recordings`: Retrieves call recordings - **WhatsApp Templates** (Send WhatsApp messages) - `GET /whatsapp_templates`: Retrieves WhatsApp templates - `POST /whatsapp_templates/{id}/send_message`: Sends a WhatsApp template message ### Datos y analítica (solo lectura) - **Dashboard** (Analytics dashboard data export) - `GET /dashboard/leaderboard`: Retrieves dashboard leaderboard - `GET /dashboard/overview`: Retrieves dashboard overview stats - `GET /dashboard/pending_tasks`: Retrieves dashboard tasks distribution - `GET /dashboard/statuses`: Retrieves dashboard flow step transitions - `GET /dashboard/playbook_value`: Retrieves all playbook value dashboard data in one request - **Sales Dashboard** (Per-agent sales dashboard data export) - `GET /sales_dashboard/performance`: Retrieves sales dashboard performance data for a single agent - `GET /sales_dashboard/sales_goals`: Retrieves daily sales goals and their goal/actual records ### Webhooks (eventos que Vixiees envía a tu URL) - `contact_created`, `contact_updated`, `contact_deleted`, `contact_comment_created`, `document_created`, `whatsapp_received`, `deal_created`, `deal_updated`, `task_completed`, `incoming_call`, `submitted_form_created` ## Cómo trabajar 1. Si no tengo claro qué quiero integrar, pregúntame antes de escribir código. 2. Descarga la especificación OpenAPI y comprueba el esquema exacto (parámetros, cuerpo y respuesta) de cada endpoint que vayas a usar. 3. Escribe un cliente pequeño y tipado: autenticación, paginación, reintentos ante 429 y 5xx, y errores con su `details`. 4. Dame ejemplos que pueda ejecutar y dime qué permisos o configuración necesito en Vixiees. Nota: el servidor MCP (https://api.vixiees.com/mcp) es para conectar asistentes de IA a Vixiees, no para integraciones entre sistemas. Para eso, usa esta API REST.
Sustituye lo resaltado por tus datos antes de enviarlo.
El mapa de endpoints del prompt se genera a partir de la especificación OpenAPI publicada, así que siempre está al día.