TimeChimp MCP Server

Un servidor para interactuar con la API v2 de TimeChimp para gestionar el seguimiento del tiempo y proyectos.

GitHub
4
Prueba este MCPPatrocinado

Documentación

Servidor MCP de TimeChimp

Un servidor integral del Protocolo de Contexto de Modelos (MCP) para interactuar con la API v2 de TimeChimp. Este servidor proporciona herramientas para recuperar y gestionar todos los recursos principales de TimeChimp, incluidos proyectos, usuarios, registros de tiempo, contactos, clientes, tareas, facturas, gastos, kilometraje y etiquetas.

Características

  • Proyectos: Operaciones CRUD completas (Crear, Leer, Actualizar, Eliminar) con gestión integral de proyectos, incluida la facturación, presupuestos, asignaciones de tareas/usuarios y perspectivas
  • Usuarios: Operaciones CRUD completas (Crear, Leer, Actualizar, Eliminar) con gestión de usuarios, incluidos roles, contratos, etiquetas e información de empleados
  • Registros de tiempo: Obtener registros de tiempo con rangos de fechas, filtrado por usuario/proyecto y ordenación
  • Contactos: Operaciones CRUD completas (Crear, Leer, Actualizar, Eliminar) para la gestión de contactos
  • Clientes: Operaciones CRUD completas (Crear, Leer, Actualizar, Eliminar) para la gestión de clientes
  • Tareas: Obtener información de tareas con filtrado por proyecto y ordenación
  • Facturas: Recuperar facturas con filtrado por cliente y fecha
  • Gastos: Operaciones CRUD completas (Crear, Leer, Actualizar, Eliminar) para la gestión de gastos con seguimiento de estado
  • Kilometraje: Operaciones CRUD completas (Crear, Leer, Actualizar, Eliminar) para la gestión de kilometraje con seguimiento de estado y asignación de vehículos
  • Vehículos de kilometraje: Recuperar información de vehículos de kilometraje para la asignación de vehículos
  • Etiquetas: Obtener información de etiquetas para organización y categorización
  • Construido como un único archivo JavaScript para facilitar su implementación
  • Utiliza la API v2 de TimeChimp con autenticación adecuada y convenciones OData
  • Manejo integral de errores y validación
  • Soporte para $expand, $count y todos los parámetros de consulta OData

Requisitos previos

  • Node.js 18.0.0 o superior
  • Una cuenta de TimeChimp con acceso a la API
  • Clave de API de TimeChimp

Instalación

  1. Clona o descarga este repositorio:
git clone <repository-url>
cd TimeJS
  1. Instala las dependencias:
npm install
  1. Haz que el servidor sea ejecutable:
chmod +x timechimp-mcp-server.js

Configuración

Configuración de la clave de API

Debes configurar tu clave de API de TimeChimp como una variable de entorno:

export TIMECHIMP_API_KEY="your-api-key-here"

O crea un archivo .env:

TIMECHIMP_API_KEY=your-api-key-here

Cómo obtener tu clave de API de TimeChimp

  1. Inicia sesión en tu cuenta de TimeChimp
  2. Ve a la configuración de tu perfil
  3. Navega a la sección de API
  4. Genera o copia tu clave de API

Integración con Claude Desktop

Para usar este servidor MCP de TimeChimp con Claude Desktop, debes agregarlo a la configuración de Claude Desktop.

Paso 1: Clonar el repositorio

git clone https://github.com/Sungdaddy/TimeyChimpey.git
cd TimeyChimpey
npm install

Paso 2: Configurar tu clave de API

Crea un archivo .env en el directorio del proyecto:

echo "TIMECHIMP_API_KEY=your-actual-api-key-here" > .env

Paso 3: Configurar Claude Desktop

Agrega la siguiente configuración a los ajustes de Claude Desktop. La ubicación del archivo de configuración depende de tu sistema operativo:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "timechimp": {
      "command": "node",
      "args": ["timechimp-mcp-server.js"],
      "cwd": "/path/to/your/TimeyChimpey",
      "env": {
        "TIMECHIMP_API_KEY": "your-actual-api-key-here"
      }
    }
  }
}

Importante: Reemplaza /path/to/your/TimeyChimpey con la ruta real donde clonaste el repositorio y reemplaza your-actual-api-key-here con tu clave de API real de TimeChimp.

Paso 4: Reiniciar Claude Desktop

Después de agregar la configuración, reinicia Claude Desktop por completo para que los cambios surtan efecto.

Paso 5: Verificar la integración

Una vez que Claude Desktop se reinicie, deberías poder usar comandos relacionados con TimeChimp. Intenta pedirle a Claude que:

  • "Obtén todos mis proyectos de TimeChimp"
  • "Muéstrame los registros de tiempo recientes"
  • "Lista todos los clientes"
  • "Crea un nuevo registro de gasto"

Ejemplo de configuración

Aquí tienes un ejemplo completo de archivo de configuración:

{
  "mcpServers": {
    "timechimp": {
      "command": "node",
      "args": ["timechimp-mcp-server.js"],
      "cwd": "/Users/yourname/TimeyChimpey",
      "env": {
        "TIMECHIMP_API_KEY": "your-actual-api-key-here"
      }
    }
  }
}

Solución de problemas de integración con Claude Desktop

  1. El servidor no se conecta: Asegúrate de que la ruta en cwd sea correcta y apunte al directorio que contiene timechimp-mcp-server.js

  2. Errores de clave de API: Verifica que tu clave de API sea correcta y tenga los permisos adecuados en TimeChimp

  3. Node.js no encontrado: Asegúrate de que Node.js esté instalado y sea accesible desde la línea de comandos

  4. Errores de permisos: Asegúrate de que Claude Desktop tenga permiso para ejecutar Node.js y acceder al directorio del proyecto

  5. La configuración no se carga: Verifica dos veces la sintaxis JSON en tu archivo de configuración: debe ser JSON válido

Herramientas disponibles en Claude Desktop

Una vez configurado, tendrás acceso a las 46 herramientas de TimeChimp a través de Claude Desktop:

  • Proyectos: Crear, leer, actualizar, eliminar proyectos con perspectivas
  • Usuarios: Gestionar usuarios con contratos y roles
  • Registros de tiempo: Rastrear y gestionar registros de tiempo
  • Contactos: Gestión completa de contactos
  • Clientes: Gestión completa del ciclo de vida del cliente
  • Gastos: Seguimiento de gastos con flujos de aprobación
  • Kilometraje: Seguimiento de kilometraje con gestión de vehículos
  • Y mucho más...

Puedes pedirle a Claude que realice cualquier operación de TimeChimp de forma natural, como "Crea un nuevo proyecto para el cliente ABC" o "Muéstrame todos los gastos pendientes que necesitan aprobación".

Uso

Ejecutar el servidor

# Start the server
npm start

# Or run directly
node timechimp-mcp-server.js

# For development with debugging
npm run dev

Herramientas disponibles

Proyectos

1. get_projects

Recupera proyectos de TimeChimp.

Parámetros:

  • top (número, opcional): Número máximo de proyectos a devolver (1-10000, predeterminado: 100)
  • skip (número, opcional): Número de proyectos a omitir para la paginación (predeterminado: 0)
  • count (booleano, opcional): Si se debe incluir el recuento total de resultados (predeterminado: true)
  • expand (cadena, opcional): Lista de propiedades separadas por comas para expandir (p. ej., "customer,tasks")
  • active_only (booleano, opcional): Devolver solo proyectos activos (predeterminado: false)
  • filter (cadena, opcional): Expresión de filtro OData
  • orderby (cadena, opcional): Expresión de ordenación OData

Ejemplo:

{
  "name": "get_projects",
  "arguments": {
    "top": 50,
    "active_only": true,
    "expand": "customer,tasks",
    "orderby": "name desc"
  }
}
2. get_project_by_id

Obtiene un proyecto específico por ID.

Parámetros:

  • id (número, obligatorio): ID del proyecto
  • expand (cadena, opcional): Lista de propiedades separadas por comas para expandir

Ejemplo:

{
  "name": "get_project_by_id",
  "arguments": {
    "id": 123,
    "expand": "customer,tasks"
  }
}
3. create_project

Crea un nuevo proyecto.

Parámetros:

  • name (cadena, obligatorio): El nombre del proyecto
  • active (booleano, opcional): Si el proyecto puede utilizarse (predeterminado: true)
  • code (cadena, opcional): El código del proyecto
  • notes (cadena, opcional): La descripción del proyecto
  • color (cadena, opcional): El color del proyecto
  • startDate (cadena, opcional): La fecha de inicio del proyecto (formato AAAA-MM-DD)
  • endDate (cadena, opcional): La fecha de fin del proyecto (formato AAAA-MM-DD)
  • invoicing (objeto, opcional): La configuración de facturación del proyecto
    • method (cadena, opcional): El método de facturación del proyecto utilizado
      • Valores permitidos: NoInvoicing, TaskHourlyRate, UserHourlyRate, ProjectHourlyRate, CustomerHourlyRate, ProjectRate, TaskRate
    • hourlyRate (número, opcional): La tarifa por hora del proyecto (solo se usa cuando el método de facturación = ProjectHourlyRate)
    • fixedRate (número, opcional): La tarifa/precio fijo del proyecto (solo se usa cuando el método de facturación = ProjectRate)
    • reference (cadena, opcional): La referencia de facturación del proyecto
    • date (cadena, opcional): La fecha de facturación del proyecto (formato AAAA-MM-DD, solo se usa cuando el método de facturación = ProjectRate)
  • budget (objeto, opcional): La configuración de presupuesto del proyecto
    • method (cadena, opcional): El método de presupuesto del proyecto utilizado
      • Valores permitidos: NoBudget, TotalHours, TaskHours, UserHours, TotalRate, TaskRate, TotalCost
    • hours (número, opcional): El presupuesto por horas del proyecto (solo se usa cuando el método de presupuesto = TotalHours)
    • rate (número, opcional): La tarifa de presupuesto del proyecto (solo se usa cuando el método de presupuesto = TotalRate o TotalCost)
    • notificationPercentage (número, opcional): El umbral de porcentaje de presupuesto en el que se envía una notificación
  • customer (objeto, opcional): Cliente a vincular con el proyecto
    • id (número, obligatorio): Identificador único del cliente
  • mainProject (objeto, opcional): Proyecto principal a vincular con el proyecto (si es un subproyecto)
    • id (número, obligatorio): Identificador único del proyecto
  • subprojects (matriz, opcional): Lista de subproyectos a vincular al proyecto (si es un proyecto principal)
  • managers (matriz, opcional): Lista de gestores a vincular al proyecto
  • tags (matriz, opcional): Lista de etiquetas a vincular al proyecto
  • projectTasks (matriz, obligatorio): Lista de tareas de proyecto a vincular al proyecto (si no se especifican tareas, se completarán previamente las tareas comunes activas)
  • projectUsers (matriz, obligatorio): Lista de usuarios de proyecto a vincular al proyecto (si no se especifican usuarios, se completarán previamente los usuarios activos)

Ejemplo:

{
  "name": "create_project",
  "arguments": {
    "name": "Website Redesign",
    "code": "WEB-2024",
    "notes": "Complete redesign of company website",
    "color": "#3498db",
    "startDate": "2024-01-15",
    "endDate": "2024-06-30",
    "invoicing": {
      "method": "ProjectHourlyRate",
      "hourlyRate": 125.00,
      "reference": "WEB-2024-INV"
    },
    "budget": {
      "method": "TotalHours",
      "hours": 400,
      "notificationPercentage": 80
    },
    "customer": {"id": 123},
    "managers": [{"id": 456}],
    "tags": [{"id": 1}, {"id": 2}],
    "projectTasks": [
      {
        "active": true,
        "billable": true,
        "hourlyRate": 125.00,
        "task": {"id": 789}
      }
    ],
    "projectUsers": [
      {
        "active": true,
        "hourlyRate": 125.00,
        "budgetHours": 200,
        "user": {"id": 101}
      }
    ]
  }
}
4. update_project

Actualiza un proyecto existente.

Parámetros:

  • id (número, obligatorio): ID del proyecto
  • name (cadena, obligatorio): El nombre del proyecto
  • active (booleano, opcional): Si el proyecto puede utilizarse
  • code (cadena, opcional): El código del proyecto
  • notes (cadena, opcional): La descripción del proyecto
  • color (cadena, opcional): El color del proyecto
  • startDate (cadena, opcional): La fecha de inicio del proyecto (formato AAAA-MM-DD)
  • endDate (cadena, opcional): La fecha de fin del proyecto (formato AAAA-MM-DD)
  • invoicing (objeto, obligatorio): La configuración de facturación del proyecto
    • method (cadena, opcional): El método de facturación del proyecto utilizado
      • Valores permitidos: NoInvoicing, TaskHourlyRate, UserHourlyRate, ProjectHourlyRate, CustomerHourlyRate, ProjectRate, TaskRate, Subscription
    • hourlyRate (número, opcional): La tarifa por hora del proyecto (solo se usa cuando el método de facturación = ProjectHourlyRate)
    • fixedRate (número, opcional): La tarifa/precio fijo del proyecto (solo se usa cuando el método de facturación = ProjectRate)
    • reference (cadena, opcional): La referencia de facturación del proyecto
    • date (cadena, opcional): La fecha de facturación del proyecto (formato AAAA-MM-DD, solo se usa cuando el método de facturación = ProjectRate)
  • budget (objeto, obligatorio): La configuración de presupuesto del proyecto
    • method (cadena, opcional): El método de presupuesto del proyecto utilizado
      • Valores permitidos: NoBudget, TotalHours, TaskHours, UserHours, TotalRate, TaskRate, Invoiced, TotalCost
    • hours (número, opcional): El presupuesto por horas del proyecto (solo se usa cuando el método de presupuesto = TotalHours)
    • rate (número, opcional): La tarifa de presupuesto del proyecto (solo se usa cuando el método de presupuesto = TotalRate o TotalCost)
    • notificationPercentage (número, opcional): El umbral de porcentaje de presupuesto en el que se envía una notificación
  • customer (objeto, opcional): Cliente a vincular con el proyecto
    • id (número, obligatorio): Identificador único del cliente
  • mainProject (objeto, opcional): Proyecto principal a vincular con el proyecto (si es un subproyecto)
    • id (número, obligatorio): Identificador único del proyecto
  • subprojects (matriz, opcional): Lista de subproyectos a vincular al proyecto (si es un proyecto principal)
  • managers (matriz, opcional): Lista de gestores a vincular al proyecto
  • tags (matriz, opcional): Lista de etiquetas a vincular al proyecto
  • projectTasks (matriz, obligatorio): Lista de tareas de proyecto a vincular al proyecto
  • projectUsers (matriz, obligatorio): Lista de usuarios de proyecto a vincular al proyecto

Ejemplo:

{
  "name": "update_project",
  "arguments": {
    "id": 123,
    "name": "Website Redesign - Phase 2",
    "endDate": "2024-08-31",
    "invoicing": {
      "method": "ProjectHourlyRate",
      "hourlyRate": 150.00
    },
    "budget": {
      "method": "TotalHours",
      "hours": 600,
      "notificationPercentage": 85
    },
    "projectTasks": [
      {
        "id": 456,
        "active": true,
        "billable": true,
        "hourlyRate": 150.00,
        "budgetHours": 120,
        "task": {"id": 789}
      }
    ],
    "projectUsers": [
      {
        "id": 789,
        "active": true,
        "hourlyRate": 150.00,
        "budgetHours": 300,
        "costHourlyRate": 90.00,
        "user": {"id": 101}
      }
    ]
  }
}
5. delete_project

Elimina un proyecto.

Parámetros:

  • id (número, obligatorio): ID del proyecto

Ejemplo:

{
  "name": "delete_project",
  "arguments": {
    "id": 123
  }
}
6. get_project_insights

Obtiene perspectivas del proyecto, incluidos horas, presupuesto, costos y datos de ingresos.

Parámetros:

  • id (número, obligatorio): ID del proyecto

Ejemplo:

{
  "name": "get_project_insights",
  "arguments": {
    "id": 123
  }
}

Usuarios

7. get_users

Recupera usuarios de TimeChimp.

Parámetros:

  • top (número, opcional): Número máximo de usuarios a devolver (1-10000, predeterminado: 100)
  • skip (número, opcional): Número de usuarios a omitir para paginación (predeterminado: 0)
  • count (booleano, opcional): Si se debe incluir el recuento total de resultados (predeterminado: true)
  • expand (cadena, opcional): Lista de propiedades separadas por comas para expandir
  • active_only (booleano, opcional): Devolver solo usuarios activos (predeterminado: false)
  • filter (cadena, opcional): Expresión de filtro OData
  • orderby (cadena, opcional): Expresión de ordenación OData

Ejemplo:

{
  "name": "get_users",
  "arguments": {
    "top": 100,
    "filter": "firstName eq 'John' and active eq true",
    "orderby": "lastName asc"
  }
}
8. get_user_by_id

Obtener un usuario específico por ID.

Parámetros:

  • id (número, obligatorio): ID del usuario
  • expand (cadena, opcional): Lista de propiedades separadas por comas para expandir
9. create_user

Crear un nuevo usuario (nota: agregar usuarios puede resultar en facturación adicional y costo extra).

Parámetros:

  • userName (cadena, obligatorio): La dirección de correo electrónico del usuario
  • displayName (cadena, obligatorio): El nombre del usuario
  • language (cadena, opcional): El idioma del usuario (predeterminado: en)
    • Valores permitidos: en, nl, de, pl, fr, es
  • role (objeto, opcional): Rol a asignar al usuario (predeterminado: User)
    • id (número, obligatorio): Identificador único del rol
  • sendInvitation (booleano, opcional): Si se debe enviar una invitación al usuario (predeterminado: false)
  • contracts (matriz, opcional): Lista de contratos de usuario a vincular
    • startDate (cadena, opcional): Fecha de inicio del contrato (formato AAAA-MM-DD, predeterminado: hoy UTC)
    • endDate (cadena, opcional): Fecha de fin del contrato (formato AAAA-MM-DD)
    • weekHours (número, opcional): Horas por semana del contrato
    • hourlyRate (número, opcional): Tarifa horaria de venta del contrato
    • costHourlyRate (número, opcional): Tarifa horaria de compra del contrato
    • contractNumber (cadena, opcional): Número del contrato
    • contractType (objeto, obligatorio): Tipo de contrato a vincular al contrato
      • id (número, obligatorio): Identificador único del tipo de contrato

Ejemplo:

{
  "name": "create_user",
  "arguments": {
    "userName": "john.doe@company.com",
    "displayName": "John Doe",
    "language": "en",
    "role": {"id": 2},
    "sendInvitation": true,
    "contracts": [
      {
        "startDate": "2024-01-15",
        "endDate": "2024-12-31",
        "weekHours": 40,
        "hourlyRate": 75.00,
        "costHourlyRate": 50.00,
        "contractNumber": "EMP-2024-001",
        "contractType": {"id": 1}
      }
    ]
  }
}
10. update_user

Actualizar un usuario existente.

Parámetros:

  • id (número, obligatorio): ID del usuario
  • displayName (cadena, obligatorio): El nombre del usuario
  • language (cadena, opcional): El idioma del usuario (predeterminado: en)
    • Valores permitidos: en, nl, de, pl, fr, es
  • employeeNumber (cadena, opcional): El número de empleado del usuario
  • badgeNumber (cadena, opcional): El número de placa del usuario
  • citizenServiceNumber (cadena, opcional): El número de servicio ciudadano del usuario
  • role (objeto, opcional): Rol a asignar al usuario (predeterminado: User)
    • id (número, obligatorio): Identificador único del rol
  • tags (matriz, opcional): Lista de etiquetas a vincular con el usuario
  • contracts (matriz, opcional): Lista de contratos de usuario a vincular
    • id (número, opcional): Identificador único del contrato de usuario (puede ser null si se necesita agregar un nuevo contrato de usuario)
    • startDate (cadena, opcional): Fecha de inicio del contrato (formato AAAA-MM-DD, predeterminado: hoy UTC)
    • endDate (cadena, opcional): Fecha de fin del contrato (formato AAAA-MM-DD)
    • weekHours (número, opcional): Horas por semana del contrato
    • hourlyRate (número, opcional): Tarifa horaria de venta del contrato
    • costHourlyRate (número, opcional): Tarifa horaria de compra/costo del contrato
    • contractNumber (cadena, opcional): Número del contrato
    • contractType (objeto, obligatorio): Tipo de contrato a vincular con el contrato
      • id (número, obligatorio): Identificador único del tipo de contrato

Ejemplo:

{
  "name": "update_user",
  "arguments": {
    "id": 123,
    "displayName": "John Doe - Senior Developer",
    "language": "en",
    "employeeNumber": "EMP-001",
    "badgeNumber": "BADGE-001",
    "role": {"id": 3},
    "tags": [{"id": 1}, {"id": 2}],
    "contracts": [
      {
        "id": 456,
        "startDate": "2024-01-15",
        "endDate": "2024-12-31",
        "weekHours": 40,
        "hourlyRate": 85.00,
        "costHourlyRate": 55.00,
        "contractNumber": "EMP-2024-001-UPD",
        "contractType": {"id": 1}
      }
    ]
  }
}

Entradas de Tiempo

11. get_time_entries

Recupera entradas de tiempo de TimeChimp.

Parámetros:

  • top (número, opcional): Número máximo de entradas de tiempo a devolver (1-10000, predeterminado: 100)
  • skip (número, opcional): Número de entradas de tiempo a omitir para paginación (predeterminado: 0)
  • count (booleano, opcional): Si se debe incluir el recuento total de resultados (predeterminado: true)
  • expand (cadena, opcional): Lista de propiedades separadas por comas para expandir (p. ej., "user,project,task")
  • user_id (cadena, opcional): Filtrar por ID de usuario específico
  • project_id (cadena, opcional): Filtrar por ID de proyecto específico
  • from_date (cadena, opcional): Fecha de inicio para filtrar (formato AAAA-MM-DD)
  • to_date (cadena, opcional): Fecha de fin para filtrar (formato AAAA-MM-DD)
  • filter (cadena, opcional): Expresión de filtro OData
  • orderby (cadena, opcional): Expresión de ordenación OData

Ejemplo:

{
  "name": "get_time_entries",
  "arguments": {
    "top": 100,
    "from_date": "2024-01-01",
    "to_date": "2024-01-31",
    "user_id": "123",
    "expand": "user,project,task",
    "orderby": "date desc"
  }
}
12. get_time_entry_by_id

Obtener una entrada de tiempo específica por ID.

Parámetros:

  • id (número, obligatorio): ID de la entrada de tiempo
  • expand (cadena, opcional): Lista de propiedades separadas por comas para expandir

Contactos

13. get_contacts

Recupera todos los contactos de TimeChimp.

Parámetros:

  • top (número, opcional): Número máximo de contactos a devolver (1-10000, predeterminado: 100)
  • skip (número, opcional): Número de contactos a omitir para paginación (predeterminado: 0)
  • count (booleano, opcional): Si se debe incluir el recuento total de resultados (predeterminado: true)
  • expand (cadena, opcional): Lista de propiedades separadas por comas para expandir (p. ej., "customers")
  • active_only (booleano, opcional): Devolver solo contactos activos (predeterminado: false)
  • filter (cadena, opcional): Expresión de filtro OData
  • orderby (cadena, opcional): Expresión de ordenación OData

Ejemplo:

{
  "name": "get_contacts",
  "arguments": {
    "top": 50,
    "expand": "customers",
    "filter": "name eq 'John Doe'",
    "orderby": "name asc"
  }
}
14. get_contact_by_id

Obtener un contacto específico por ID.

Parámetros:

  • id (número, obligatorio): ID del contacto
  • expand (cadena, opcional): Lista de propiedades separadas por comas para expandir
15. create_contact

Crear un nuevo contacto.

Parámetros:

  • name (cadena, obligatorio): El nombre del contacto
  • jobTitle (cadena, opcional): El cargo del contacto
  • email (cadena, opcional): La dirección de correo electrónico del contacto
  • phone (cadena, opcional): El número de teléfono del contacto
  • useForInvoicing (booleano, opcional): Si la información del contacto se usará para facturación (predeterminado: false)
  • active (booleano, opcional): Si el contacto puede ser utilizado (predeterminado: true)
  • customers (matriz, opcional): Lista de IDs de clientes para vincular a este contacto

Ejemplo:

{
  "name": "create_contact",
  "arguments": {
    "name": "John Doe",
    "jobTitle": "Project Manager",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "useForInvoicing": true,
    "customers": [{"id": 123}, {"id": 456}]
  }
}
16. update_contact

Actualizar un contacto existente.

Parámetros:

  • id (número, obligatorio): ID del contacto
  • name (cadena, obligatorio): El nombre del contacto
  • jobTitle (cadena, opcional): El cargo del contacto
  • email (cadena, opcional): La dirección de correo electrónico del contacto
  • phone (cadena, opcional): El número de teléfono del contacto
  • useForInvoicing (booleano, opcional): Si la información del contacto se usará para facturación
  • active (booleano, opcional): Si el contacto puede ser utilizado
  • customers (matriz, opcional): Lista de IDs de clientes para vincular a este contacto
17. delete_contact

Eliminar un contacto.

Parámetros:

  • id (número, obligatorio): ID del contacto

Ejemplo:

{
  "name": "delete_contact",
  "arguments": {
    "id": 123
  }
}

Clientes

18. get_customers

Recupera todos los clientes de TimeChimp.

Parámetros:

  • top (número, opcional): Número máximo de clientes a devolver (1-10000, predeterminado: 100)
  • skip (número, opcional): Número de clientes a omitir para paginación (predeterminado: 0)
  • count (booleano, opcional): Si se debe incluir el recuento total de resultados (predeterminado: true)
  • expand (cadena, opcional): Lista de propiedades separadas por comas para expandir (p. ej., "contacts,projects")
  • active_only (booleano, opcional): Devolver solo clientes activos (predeterminado: false)
  • filter (cadena, opcional): Expresión de filtro OData
  • orderby (cadena, opcional): Expresión de ordenación OData
19. get_customer_by_id

Obtener un cliente específico por ID.

Parámetros:

  • id (número, obligatorio): ID del cliente
  • expand (cadena, opcional): Lista de propiedades separadas por comas para expandir
20. create_customer

Crear un nuevo cliente.

Parámetros:

  • name (cadena, obligatorio): El nombre del cliente
  • active (booleano, opcional): Si el cliente puede ser utilizado (predeterminado: true)
  • relationId (cadena, opcional): El número del cliente
  • address (objeto, opcional): La información de dirección del cliente
    • address (cadena, opcional): La línea de dirección
    • postalCode (cadena, opcional): El código postal
    • city (cadena, opcional): La ciudad
    • country (cadena, opcional): El país
  • phone (cadena, opcional): El número de teléfono del cliente
  • email (cadena, opcional): La dirección de correo electrónico del cliente
  • website (cadena, opcional): La URL del sitio web del cliente
  • paymentPeriod (número, opcional): El plazo de pago del cliente en días
  • hourlyRate (número, opcional): El precio horario predeterminado del cliente
  • mileageRate (número, opcional): El precio de kilometraje predeterminado del cliente, por KM
  • iban (cadena, opcional): El IBAN del cliente
  • bic (cadena, opcional): El BIC del cliente
  • vatNumber (cadena, opcional): El número de IVA del cliente
  • kvkNumber (cadena, opcional): El ID comercial del cliente
  • invoiceAddress (objeto, opcional): La información de dirección de facturación del cliente, anulación de la información de dirección del cliente
    • address (cadena, opcional): La línea de dirección
    • postalCode (cadena, opcional): El código postal
    • city (cadena, opcional): La ciudad
    • country (cadena, opcional): El país
  • notes (cadena, opcional): Las notas del cliente
  • prospect (booleano, opcional): Si el cliente es un prospecto
  • vatRate (objeto, opcional): Tasa de IVA a utilizar para este cliente
    • id (número, obligatorio): Identificador único de la tasa de IVA
  • tags (matriz, opcional): Lista de IDs de etiquetas para vincular a este cliente
  • contacts (matriz, opcional): Lista de IDs de contactos para vincular a este cliente

Ejemplo:

{
  "name": "create_customer",
  "arguments": {
    "name": "Acme Corporation",
    "email": "contact@acme.com",
    "phone": "+1234567890",
    "website": "https://acme.com",
    "address": {
      "address": "123 Business St",
      "postalCode": "12345",
      "city": "Business City",
      "country": "USA"
    },
    "paymentPeriod": 30,
    "hourlyRate": 150.00,
    "prospect": false,
    "tags": [{"id": 1}, {"id": 2}],
    "contacts": [{"id": 123}]
  }
}
21. update_customer

Actualizar un cliente existente. Parámetros:

  • id (number, obligatorio): ID del cliente
  • name (string, obligatorio): El nombre del cliente
  • active (boolean, opcional): Si el cliente puede ser utilizado
  • relationId (string, opcional): El número de cliente
  • address (object, opcional): La información de dirección del cliente
    • address (string, opcional): La línea de dirección
    • postalCode (string, opcional): El código postal
    • city (string, opcional): La ciudad
    • country (string, opcional): El país
  • phone (string, opcional): El número de teléfono del cliente
  • email (string, opcional): La dirección de correo electrónico del cliente
  • website (string, opcional): La URL del sitio web del cliente
  • paymentPeriod (number, opcional): El plazo de pago del cliente en días
  • hourlyRate (number, opcional): El precio por hora predeterminado del cliente
  • mileageRate (number, opcional): El precio por kilómetro predeterminado del cliente
  • iban (string, opcional): El IBAN del cliente
  • bic (string, opcional): El BIC del cliente
  • vatNumber (string, opcional): El número de IVA del cliente
  • kvkNumber (string, opcional): El ID de negocio del cliente
  • invoiceAddress (object, opcional): La información de dirección de facturación del cliente, si difiere de la información de dirección del cliente
    • address (string, opcional): La línea de dirección
    • postalCode (string, opcional): El código postal
    • city (string, opcional): La ciudad
    • country (string, opcional): El país
  • notes (string, opcional): Las notas del cliente
  • prospect (boolean, opcional): El cliente es un prospecto
  • vatRate (object, opcional): Tipo de IVA a vincular con el cliente
    • id (number, obligatorio): Identificador único para el tipo de IVA
  • tags (array, opcional): Lista de IDs de etiquetas para vincular a este cliente
  • contacts (array, opcional): Lista de IDs de contactos para vincular a este cliente

Ejemplo:

{
  "name": "update_customer",
  "arguments": {
    "id": 456,
    "name": "Acme Corporation Ltd",
    "email": "newcontact@acme.com",
    "paymentPeriod": 45,
    "hourlyRate": 175.00
  }
}
22. delete_customer

Eliminar un cliente.

Parámetros:

  • id (number, obligatorio): ID del cliente

Ejemplo:

{
  "name": "delete_customer",
  "arguments": {
    "id": 456
  }
}

Tareas

23. get_tasks

Recuperar todas las tareas de TimeChimp.

Parámetros:

  • top (number, opcional): Número máximo de tareas a devolver (1-10000, predeterminado: 100)
  • skip (number, opcional): Número de tareas a omitir para paginación (predeterminado: 0)
  • count (boolean, opcional): Si incluir el recuento total de resultados (predeterminado: true)
  • expand (string, opcional): Lista de propiedades separadas por comas para expandir (p. ej., "project")
  • active_only (boolean, opcional): Devolver solo tareas activas (predeterminado: false)
  • project_id (string, opcional): Filtrar por ID de proyecto específico
  • filter (string, opcional): Expresión de filtro OData
  • orderby (string, opcional): Expresión de ordenamiento OData
24. get_task_by_id

Obtener una tarea específica por ID.

Parámetros:

  • id (number, obligatorio): ID de la tarea
  • expand (string, opcional): Lista de propiedades separadas por comas para expandir

Facturas

25. get_invoices

Recuperar todas las facturas de TimeChimp.

Parámetros:

  • top (number, opcional): Número máximo de facturas a devolver (1-10000, predeterminado: 100)
  • skip (number, opcional): Número de facturas a omitir para paginación (predeterminado: 0)
  • count (boolean, opcional): Si incluir el recuento total de resultados (predeterminado: true)
  • expand (string, opcional): Lista de propiedades separadas por comas para expandir (p. ej., "customer,projects")
  • customer_id (string, opcional): Filtrar por ID de cliente específico
  • from_date (string, opcional): Fecha de inicio para filtrar (formato YYYY-MM-DD)
  • to_date (string, opcional): Fecha de fin para filtrar (formato YYYY-MM-DD)
  • filter (string, opcional): Expresión de filtro OData
  • orderby (string, opcional): Expresión de ordenamiento OData
26. get_invoice_by_id

Obtener una factura específica por ID.

Parámetros:

  • id (number, obligatorio): ID de la factura
  • expand (string, opcional): Lista de propiedades separadas por comas para expandir

Gastos

27. get_expenses

Recuperar todos los gastos de TimeChimp.

Parámetros:

  • top (number, opcional): Número máximo de gastos a devolver (1-10000, predeterminado: 100)
  • skip (number, opcional): Número de gastos a omitir para paginación (predeterminado: 0)
  • count (boolean, opcional): Si incluir el recuento total de resultados (predeterminado: true)
  • expand (string, opcional): Lista de propiedades separadas por comas para expandir (p. ej., "user,project,customer")
  • user_id (string, opcional): Filtrar por ID de usuario específico
  • project_id (string, opcional): Filtrar por ID de proyecto específico
  • customer_id (string, opcional): Filtrar por ID de cliente específico
  • from_date (string, opcional): Fecha de inicio para filtrar (formato YYYY-MM-DD)
  • to_date (string, opcional): Fecha de fin para filtrar (formato YYYY-MM-DD)
  • filter (string, opcional): Expresión de filtro OData
  • orderby (string, opcional): Expresión de ordenamiento OData
28. get_expense_by_id

Obtener un gasto específico por ID.

Parámetros:

  • id (number, obligatorio): ID del gasto
  • expand (string, opcional): Lista de propiedades separadas por comas para expandir
29. create_expense

Crear un nuevo gasto.

Parámetros:

  • date (string, opcional): La fecha del gasto (formato YYYY-MM-DD, predeterminado: hoy en UTC)
  • notes (string, opcional): Las notas del gasto
  • quantity (number, opcional): La cantidad del gasto (predeterminado: 1)
  • rate (number, obligatorio): La tarifa/precio del gasto
  • billable (boolean, opcional): Si el gasto puede ser facturado (predeterminado: true)
  • customer (object, opcional): Cliente a vincular con el gasto
    • id (number, obligatorio): Identificador único para el cliente
  • project (object, opcional): Proyecto a vincular con el gasto
    • id (number, obligatorio): Identificador único para el proyecto
  • product (object, opcional): Producto a vincular con el gasto
    • id (number, obligatorio): Identificador único para el producto
  • user (object, obligatorio): Usuario a vincular con el gasto
    • id (number, obligatorio): Identificador único para el usuario
  • vatRate (object, opcional): Tipo de IVA a vincular con el gasto (predeterminado: porcentaje más alto)
    • id (number, obligatorio): Identificador único para el tipo de IVA

Ejemplo:

{
  "name": "create_expense",
  "arguments": {
    "date": "2024-01-15",
    "notes": "Business lunch with client",
    "quantity": 1,
    "rate": 75.50,
    "billable": true,
    "customer": {"id": 123},
    "project": {"id": 456},
    "user": {"id": 789}
  }
}
30. update_expense

Actualizar un gasto existente.

Parámetros:

  • id (number, obligatorio): ID del gasto
  • date (string, opcional): La fecha del gasto (formato YYYY-MM-DD)
  • notes (string, opcional): Las notas del gasto
  • quantity (number, opcional): La cantidad del gasto
  • rate (number, obligatorio): La tarifa/precio del gasto
  • billable (boolean, opcional): Si el gasto puede ser facturado
  • customer (object, opcional): Cliente a vincular con el gasto
    • id (number, obligatorio): Identificador único para el cliente
  • project (object, opcional): Proyecto a vincular con el gasto
    • id (number, obligatorio): Identificador único para el proyecto
  • product (object, opcional): Producto a vincular con el gasto
    • id (number, obligatorio): Identificador único para el producto
  • user (object, obligatorio): Usuario a vincular con el gasto
    • id (number, obligatorio): Identificador único para el usuario
  • vatRate (object, opcional): Tipo de IVA a vincular con el gasto
    • id (number, obligatorio): Identificador único para el tipo de IVA

Ejemplo:

{
  "name": "update_expense",
  "arguments": {
    "id": 123,
    "notes": "Updated: Business lunch with client and partner",
    "rate": 85.00,
    "user": {"id": 789}
  }
}
31. delete_expense

Eliminar un gasto.

Parámetros:

  • id (number, obligatorio): ID del gasto

Ejemplo:

{
  "name": "delete_expense",
  "arguments": {
    "id": 123
  }
}
32. update_expense_status

Actualizar el estado de los gastos (estado interno de aprobación/facturación).

Parámetros:

  • message (string, opcional): Mensaje del historial de estado
  • expenses (array, obligatorio): Lista de gastos a actualizar (máximo de 100 entradas)
    • id (number, obligatorio): Identificador único para el gasto
  • status (string, obligatorio): El estado interno de aprobación/facturación
    • Valores permitidos: Open, PendingApproval, Approved, Invoiced, WrittenOff, Rejected

Ejemplo:

{
  "name": "update_expense_status",
  "arguments": {
    "message": "Approved by manager",
    "expenses": [{"id": 123}, {"id": 124}],
    "status": "Approved"
  }
}
33. update_expense_client_status

Actualizar el estado del cliente de los gastos (estado externo de aprobación/facturación).

Parámetros:

  • clientStatus (string, obligatorio): El estado externo de aprobación/facturación (usado solo cuando el portal del cliente está habilitado)
    • Valores permitidos: Open, PendingApproval, Approved, Invoiced, WrittenOff, Rejected
  • message (string, opcional): Mensaje del historial de estado
  • expenses (array, obligatorio): Lista de gastos a actualizar (máximo de 100 entradas)
    • id (number, obligatorio): Identificador único para el gasto

Ejemplo:

{
  "name": "update_expense_client_status",
  "arguments": {
    "clientStatus": "Approved",
    "message": "Client approved expenses",
    "expenses": [{"id": 123}, {"id": 124}]
  }
}
34. get_expense_status_history

Consultar los registros de modificación del historial de estado de un gasto.

Parámetros:

  • id (number, obligatorio): ID del gasto
  • top (number, opcional): Número máximo de registros del historial de estado a devolver (1-10000, predeterminado: 100)
  • skip (number, opcional): Número de registros del historial de estado a omitir para paginación (predeterminado: 0)
  • count (boolean, opcional): Si incluir el recuento total de resultados (predeterminado: true)
  • expand (string, opcional): Lista de propiedades separadas por comas para expandir
  • filter (string, opcional): Expresión de filtro OData
  • orderby (string, opcional): Expresión de ordenamiento OData (p. ej., "modifiedOn desc")

Ejemplo:

{
  "name": "get_expense_status_history",
  "arguments": {
    "id": 123,
    "orderby": "modifiedOn desc",
    "top": 50
  }
}

Kilometraje

35. get_mileage

Recuperar todas las entradas de kilometraje de TimeChimp.

Parámetros:

  • top (number, opcional): Número máximo de entradas de kilometraje a devolver (1-10000, predeterminado: 100)
  • skip (number, opcional): Número de entradas de kilometraje a omitir para paginación (predeterminado: 0)
  • count (boolean, opcional): Si incluir el recuento total de resultados (predeterminado: true)
  • expand (string, opcional): Lista de propiedades separadas por comas para expandir (p. ej., "user,project,customer")
  • user_id (string, opcional): Filtrar por ID de usuario específico
  • project_id (string, opcional): Filtrar por ID de proyecto específico
  • customer_id (string, opcional): Filtrar por ID de cliente específico
  • from_date (string, opcional): Fecha de inicio para filtrar (formato YYYY-MM-DD)
  • to_date (string, opcional): Fecha de fin para filtrar (formato YYYY-MM-DD)
  • filter (string, opcional): Expresión de filtro OData
  • orderby (string, opcional): Expresión de ordenamiento OData
36. get_mileage_by_id

Obtener una entrada de kilometraje específica por ID.

Parámetros:

  • id (number, obligatorio): ID de la entrada de kilometraje
  • expand (string, opcional): Lista de propiedades separadas por comas para expandir
37. create_mileage

Crear una nueva entrada de kilometraje. Parámetros:

  • date (string, opcional): La fecha del kilometraje (formato AAAA-MM-DD, por defecto: hoy UTC)
  • fromAddress (string, opcional): La dirección de origen del kilometraje
  • toAddress (string, opcional): La dirección de destino del kilometraje
  • notes (string, opcional): Las notas del kilometraje
  • distance (number, obligatorio): La distancia del kilometraje en km
  • billable (boolean, opcional): Si el kilometraje puede facturarse (por defecto: true)
  • type (string, obligatorio): El tipo de kilometraje
    • Valores permitidos: Private, Business, HomeWork
  • customer (object, opcional): Cliente a vincular con el kilometraje
    • id (number, obligatorio): Identificador único del cliente
  • project (object, opcional): Proyecto a vincular con el kilometraje
    • id (number, obligatorio): Identificador único del proyecto
  • vehicle (object, opcional): Vehículo a vincular con el kilometraje
    • id (number, obligatorio): Identificador único del vehículo de kilometraje
  • user (object, obligatorio): Usuario a vincular con el kilometraje
    • id (number, obligatorio): Identificador único del usuario

Ejemplo:

{
  "name": "create_mileage",
  "arguments": {
    "date": "2024-01-15",
    "fromAddress": "Office - 123 Business St, Business City",
    "toAddress": "Client Site - 456 Client Ave, Client City",
    "notes": "Client meeting and project consultation",
    "distance": 45.5,
    "billable": true,
    "type": "Business",
    "customer": {"id": 123},
    "project": {"id": 456},
    "vehicle": {"id": 789},
    "user": {"id": 101}
  }
}
38. update_mileage

Actualizar una entrada de kilometraje existente.

Parámetros:

  • id (number, obligatorio): ID de la entrada de kilometraje
  • date (string, opcional): La fecha del kilometraje (formato AAAA-MM-DD)
  • fromAddress (string, opcional): La dirección de origen del kilometraje
  • toAddress (string, opcional): La dirección de destino del kilometraje
  • notes (string, opcional): Las notas del kilometraje
  • distance (number, obligatorio): La distancia del kilometraje en km
  • billable (boolean, opcional): Si el kilometraje puede facturarse
  • type (string, obligatorio): El tipo de kilometraje
    • Valores permitidos: Private, Business, HomeWork
  • customer (object, opcional): Cliente a vincular con el kilometraje
    • id (number, obligatorio): Identificador único del cliente
  • project (object, opcional): Proyecto a vincular con el kilometraje
    • id (number, obligatorio): Identificador único del proyecto
  • vehicle (object, opcional): Vehículo a vincular con el kilometraje
    • id (number, obligatorio): Identificador único del vehículo de kilometraje
  • user (object, obligatorio): Usuario a vincular con el kilometraje
    • id (number, obligatorio): Identificador único del usuario

Ejemplo:

{
  "name": "update_mileage",
  "arguments": {
    "id": 123,
    "notes": "Updated: Client meeting, project consultation, and site inspection",
    "distance": 52.3,
    "fromAddress": "Office - 123 Business St, Business City",
    "toAddress": "Client Site - 456 Client Ave, Client City (with site inspection)",
    "type": "Business",
    "user": {"id": 101}
  }
}
39. delete_mileage

Eliminar una entrada de kilometraje.

Parámetros:

  • id (number, obligatorio): ID de la entrada de kilometraje

Ejemplo:

{
  "name": "delete_mileage",
  "arguments": {
    "id": 123
  }
}
40. update_mileage_status

Actualizar el estado de las entradas de kilometraje (estado interno de aprobación/facturación).

Parámetros:

  • message (string, opcional): Mensaje del historial de estado
  • mileages (array, obligatorio): Lista de entradas de kilometraje a actualizar (máximo de 100 entradas)
    • id (number, obligatorio): Identificador único del kilometraje
  • status (string, obligatorio): El estado interno de aprobación/facturación
    • Valores permitidos: Open, PendingApproval, Approved, Invoiced, WrittenOff, Rejected

Ejemplo:

{
  "name": "update_mileage_status",
  "arguments": {
    "message": "Approved by manager after review",
    "mileages": [{"id": 123}, {"id": 124}],
    "status": "Approved"
  }
}
41. update_mileage_client_status

Actualizar el estado del cliente de las entradas de kilometraje (estado externo de aprobación/facturación).

Parámetros:

  • clientStatus (string, obligatorio): El estado externo de aprobación/facturación (se usa solo cuando el portal del cliente está habilitado)
    • Valores permitidos: Open, PendingApproval, Approved, Invoiced, WrittenOff, Rejected
  • message (string, opcional): Mensaje del historial de estado
  • mileages (array, obligatorio): Lista de entradas de kilometraje a actualizar (máximo de 100 entradas)
    • id (number, obligatorio): Identificador único del kilometraje

Ejemplo:

{
  "name": "update_mileage_client_status",
  "arguments": {
    "clientStatus": "Approved",
    "message": "Client approved mileage claims",
    "mileages": [{"id": 123}, {"id": 124}]
  }
}
42. get_mileage_status_history

Consultar los registros de modificación del historial de estado de una entrada de kilometraje.

Parámetros:

  • id (number, obligatorio): ID de la entrada de kilometraje
  • top (number, opcional): Número máximo de registros del historial de estado a devolver (1-10000, por defecto: 100)
  • skip (number, opcional): Número de registros del historial de estado a omitir para la paginación (por defecto: 0)
  • count (boolean, opcional): Si se debe incluir el recuento total de resultados (por defecto: true)
  • expand (string, opcional): Lista de propiedades separadas por comas para expandir
  • filter (string, opcional): Expresión de filtro OData
  • orderby (string, opcional): Expresión de ordenación OData (p. ej., "modifiedOn desc")

Ejemplo:

{
  "name": "get_mileage_status_history",
  "arguments": {
    "id": 123,
    "orderby": "modifiedOn desc",
    "top": 50
  }
}
43. get_mileage_vehicles

Recuperar todos los vehículos de kilometraje de TimeChimp.

Parámetros:

  • top (number, opcional): Número máximo de vehículos de kilometraje a devolver (1-10000, por defecto: 100)
  • skip (number, opcional): Número de vehículos de kilometraje a omitir para la paginación (por defecto: 0)
  • count (boolean, opcional): Si se debe incluir el recuento total de resultados (por defecto: true)
  • expand (string, opcional): Lista de propiedades separadas por comas para expandir (p. ej., "users")
  • active_only (boolean, opcional): Devolver solo vehículos de kilometraje activos (por defecto: false)
  • filter (string, opcional): Expresión de filtro OData
  • orderby (string, opcional): Expresión de ordenación OData

Ejemplo:

{
  "name": "get_mileage_vehicles",
  "arguments": {
    "active_only": true,
    "expand": "users",
    "orderby": "brand asc"
  }
}
44. get_mileage_vehicle_by_id

Obtener un vehículo de kilometraje específico por ID.

Parámetros:

  • id (number, obligatorio): ID del vehículo de kilometraje
  • expand (string, opcional): Lista de propiedades separadas por comas para expandir

Ejemplo:

{
  "name": "get_mileage_vehicle_by_id",
  "arguments": {
    "id": 789,
    "expand": "users"
  }
}

Etiquetas

45. get_tags

Recuperar todas las etiquetas de TimeChimp.

Parámetros:

  • top (number, opcional): Número máximo de etiquetas a devolver (1-10000, por defecto: 100)
  • skip (number, opcional): Número de etiquetas a omitir para la paginación (por defecto: 0)
  • count (boolean, opcional): Si se debe incluir el recuento total de resultados (por defecto: true)
  • expand (string, opcional): Lista de propiedades separadas por comas para expandir
  • active_only (boolean, opcional): Devolver solo etiquetas activas (por defecto: false)
  • filter (string, opcional): Expresión de filtro OData
  • orderby (string, opcional): Expresión de ordenación OData
46. get_tag_by_id

Obtener una etiqueta específica por ID.

Parámetros:

  • id (number, obligatorio): ID de la etiqueta
  • expand (string, opcional): Lista de propiedades separadas por comas para expandir

Características de la API v2 de TimeChimp

Paginación

El servidor utiliza los parámetros de paginación estándar de TimeChimp:

  • $top: Número máximo de registros a devolver (1-10000, por defecto: 100)
  • $skip: Número de registros a omitir para la paginación

Filtrado (OData)

El servidor admite las convenciones de filtrado OData de TimeChimp:

  • Filtros básicos: name eq 'Project Name'
  • Filtros booleanos: active eq true
  • Filtros de fecha: date eq 2023-12-31
  • Filtros de fecha y hora: start gt 2023-12-31T23:59:59Z
  • Filtros combinados: active eq true and name eq 'Project Name'
  • Filtros de colección: projects/any(project:project/id eq 123)

Ordenación (OData)

El servidor admite la ordenación OData:

  • Campo único: name desc
  • Varios campos: name desc, createdAt asc
  • Propiedades anidadas: address/city asc

Expansión (OData)

El servidor admite la expansión de entidades relacionadas:

  • Expansión única: customer
  • Expansiones múltiples: customer,projects,tasks
  • Expansiones anidadas: customer/contacts

Recuento

El servidor admite el recuento de resultados totales:

  • $count=true: Incluir el recuento total en la respuesta
  • $count=false: Excluir el recuento total (por defecto por rendimiento)

Puntos de conexión de la API

El servidor interactúa con los siguientes puntos de conexión de la API v2 de TimeChimp:

  • GET /projects - Recuperar proyectos
  • GET /projects/{id} - Obtener un proyecto específico por ID
  • POST /projects - Crear un nuevo proyecto
  • PUT /projects/{id} - Actualizar un proyecto existente
  • DELETE /projects/{id} - Eliminar proyecto
  • GET /projects/{id}/insights - Obtener información del proyecto
  • GET /users - Recuperar usuarios
  • GET /users/{id} - Obtener un usuario específico por ID
  • POST /users - Crear un nuevo usuario
  • PUT /users/{id} - Actualizar un usuario existente
  • GET /times - Recuperar entradas de tiempo
  • GET /times/{id} - Obtener una entrada de tiempo específica por ID
  • GET /contacts - Recuperar contactos
  • GET /contacts/{id} - Obtener un contacto específico por ID
  • POST /contacts - Crear un nuevo contacto
  • PUT /contacts/{id} - Actualizar un contacto existente
  • DELETE /contacts/{id} - Eliminar contacto
  • GET /customers - Recuperar clientes
  • GET /customers/{id} - Obtener un cliente específico por ID
  • POST /customers - Crear un nuevo cliente
  • PUT /customers/{id} - Actualizar un cliente existente
  • DELETE /customers/{id} - Eliminar cliente
  • GET /tasks - Recuperar tareas
  • GET /tasks/{id} - Obtener una tarea específica por ID
  • GET /invoices - Recuperar facturas
  • GET /invoices/{id} - Obtener una factura específica por ID
  • GET /expenses - Recuperar gastos
  • GET /expenses/{id} - Obtener un gasto específico por ID
  • POST /expenses - Crear un nuevo gasto
  • PUT /expenses/{id} - Actualizar un gasto existente
  • DELETE /expenses/{id} - Eliminar gasto
  • PUT /expenses/status - Actualizar el estado del gasto (interno)
  • PUT /expenses/clientStatus - Actualizar el estado del cliente del gasto (externo)
  • GET /expenses/{id}/statusHistory - Obtener el historial de estado del gasto
  • GET /mileage - Recuperar entradas de kilometraje
  • GET /mileage/{id} - Obtener una entrada de kilometraje específica por ID
  • POST /mileage - Crear una nueva entrada de kilometraje
  • PUT /mileage/{id} - Actualizar una entrada de kilometraje existente
  • DELETE /mileage/{id} - Eliminar entrada de kilometraje
  • PUT /mileage/status - Actualizar el estado del kilometraje (interno)
  • PUT /mileage/clientStatus - Actualizar el estado del cliente del kilometraje (externo)
  • GET /mileage/{id}/statusHistory - Obtener el historial de estado del kilometraje
  • GET /mileageVehicles - Recuperar vehículos de kilometraje
  • GET /mileageVehicles/{id} - Obtener un vehículo de kilometraje específico por ID
  • GET /tags - Recuperar etiquetas
  • GET /tags/{id} - Obtener una etiqueta específica por ID

Todas las solicitudes se autentican mediante el encabezado api-key y admiten parámetros de consulta OData.

Ejemplos avanzados

Filtrado complejo

{
  "name": "get_time_entries",
  "arguments": {
    "filter": "date ge 2024-01-01 and date le 2024-01-31 and user/id eq 123 and project/active eq true",
    "expand": "user,project,task",
    "orderby": "date desc, start desc",
    "top": 50
  }
}

Ejemplo de paginación

{
  "name": "get_projects",
  "arguments": {
    "top": 25,
    "skip": 50,
    "count": true,
    "orderby": "name asc"
  }
}

Creación y gestión de contactos

// Create a contact
{
  "name": "create_contact",
  "arguments": {
    "name": "Jane Smith",
    "jobTitle": "CEO",
    "email": "jane@company.com",
    "useForInvoicing": true,
    "customers": [{"id": 123}]
  }
}

// Update the contact
{
  "name": "update_contact",
  "arguments": {
    "id": 456,
    "name": "Jane Smith-Johnson",
    "phone": "+1987654321"
  }
}

// Get contact with expanded customers
{
  "name": "get_contact_by_id",
  "arguments": {
    "id": 456,
    "expand": "customers"
  }
}

Creación y gestión de clientes

// Create a customer
{
  "name": "create_customer",
  "arguments": {
    "name": "Acme Corporation",
    "email": "contact@acme.com",
    "phone": "+1234567890",
    "website": "https://acme.com",
    "address": {
      "address": "123 Business St",
      "postalCode": "12345",
      "city": "Business City",
      "country": "USA"
    },
    "paymentPeriod": 30,
    "hourlyRate": 150.00,
    "prospect": false,
    "tags": [{"id": 1}, {"id": 2}],
    "contacts": [{"id": 123}]
  }
}

// Update the customer
{
  "name": "update_customer",
  "arguments": {
    "id": 456,
    "name": "Acme Corporation Ltd",
    "email": "newcontact@acme.com",
    "paymentPeriod": 45,
    "hourlyRate": 175.00
  }
}

// Get customer with expanded contacts and tags
{
  "name": "get_customer_by_id",
  "arguments": {
    "id": 456,
    "expand": "contacts,tags"
  }
}

Creación y gestión de gastos

// Create an expense
{
  "name": "create_expense",
  "arguments": {
    "date": "2024-01-15",
    "notes": "Business lunch with client",
    "quantity": 1,
    "rate": 75.50,
    "billable": true,
    "customer": {"id": 123},
    "project": {"id": 456},
    "user": {"id": 789}
  }
}

// Update the expense
{
  "name": "update_expense",
  "arguments": {
    "id": 123,
    "notes": "Updated: Business lunch with client and partner",
    "rate": 85.00,
    "user": {"id": 789}
  }
}

// Update expense status (approve multiple expenses)
{
  "name": "update_expense_status",
  "arguments": {
    "message": "Approved by manager",
    "expenses": [{"id": 123}, {"id": 124}],
    "status": "Approved"
  }
}

// Get expense status history
{
  "name": "get_expense_status_history",
  "arguments": {
    "id": 123,
    "orderby": "modifiedOn desc"
  }
}

Creación y gestión de proyectos

// Create a project with comprehensive settings
{
  "name": "create_project",
  "arguments": {
    "name": "Website Redesign Project",
    "code": "WEB-2024-001",
    "notes": "Complete redesign of company website with modern UI/UX",
    "color": "#3498db",
    "startDate": "2024-01-15",
    "endDate": "2024-06-30",
    "invoicing": {
      "method": "ProjectHourlyRate",
      "hourlyRate": 125.00,
      "reference": "WEB-2024-INV"
    },
    "budget": {
      "method": "TotalHours",
      "hours": 400,
      "notificationPercentage": 80
    },
    "customer": {"id": 123},
    "managers": [{"id": 456}],
    "tags": [{"id": 1}, {"id": 2}],
    "projectTasks": [
      {
        "active": true,
        "billable": true,
        "hourlyRate": 125.00,
        "budgetHours": 100,
        "task": {"id": 789}
      },
      {
        "active": true,
        "billable": true,
        "hourlyRate": 150.00,
        "budgetHours": 80,
        "task": {"id": 790}
      }
    ],
    "projectUsers": [
      {
        "active": true,
        "hourlyRate": 125.00,
        "budgetHours": 200,
        "costHourlyRate": 80.00,
        "user": {"id": 101}
      },
      {
        "active": true,
        "hourlyRate": 150.00,
        "budgetHours": 200,
        "costHourlyRate": 100.00,
        "user": {"id": 102}
      }
    ]
  }
}

// Update the project with new requirements
{
  "name": "update_project",
  "arguments": {
    "id": 123,
    "name": "Website Redesign Project - Phase 2",
    "endDate": "2024-08-31",
    "invoicing": {
      "method": "ProjectHourlyRate",
      "hourlyRate": 150.00
    },
    "budget": {
      "method": "TotalHours",
      "hours": 600,
      "notificationPercentage": 85
    },
    "projectTasks": [
      {
        "id": 456,
        "active": true,
        "billable": true,
        "hourlyRate": 150.00,
        "budgetHours": 120,
        "task": {"id": 789}
      }
    ],
    "projectUsers": [
      {
        "id": 789,
        "active": true,
        "hourlyRate": 150.00,
        "budgetHours": 300,
        "costHourlyRate": 90.00,
        "user": {"id": 101}
      }
    ]
  }
}

// Get project insights for performance analysis
{
  "name": "get_project_insights",
  "arguments": {
    "id": 123
  }
}

// Get project with expanded relationships
{
  "name": "get_project_by_id",
  "arguments": {
    "id": 123,
    "expand": "customer,managers,tags,projectTasks,projectUsers"
  }
}

Creación y gestión de usuarios

// Create a user with contract and role assignment
{
  "name": "create_user",
  "arguments": {
    "userName": "john.doe@company.com",
    "displayName": "John Doe",
    "language": "en",
    "role": {"id": 2},
    "sendInvitation": true,
    "contracts": [
      {
        "startDate": "2024-01-15",
        "endDate": "2024-12-31",
        "weekHours": 40,
        "hourlyRate": 75.00,
        "costHourlyRate": 50.00,
        "contractNumber": "EMP-2024-001",
        "contractType": {"id": 1}
      }
    ]
  }
}

// Update the user with new role and contract terms
{
  "name": "update_user",
  "arguments": {
    "id": 123,
    "displayName": "John Doe - Senior Developer",
    "language": "en",
    "employeeNumber": "EMP-001",
    "badgeNumber": "BADGE-001",
    "citizenServiceNumber": "123456789",
    "role": {"id": 3},
    "tags": [{"id": 1}, {"id": 2}],
    "contracts": [
      {
        "id": 456,
        "startDate": "2024-01-15",
        "endDate": "2024-12-31",
        "weekHours": 40,
        "hourlyRate": 85.00,
        "costHourlyRate": 55.00,
        "contractNumber": "EMP-2024-001-UPD",
        "contractType": {"id": 1}
      }
    ]
  }
}

// Get user with expanded relationships
{
  "name": "get_user_by_id",
  "arguments": {
    "id": 123,
    "expand": "role,team,tags,contracts,selfBilling,customSchedule"
  }
}

// Get users with filtering and expansion
{
  "name": "get_users",
  "arguments": {
    "filter": "active eq true and role/name eq 'Developer'",
    "expand": "role,contracts",
    "orderby": "displayName asc",
    "top": 50
  }
}

Creación y gestión de kilometraje

// Create a mileage entry
{
  "name": "create_mileage",
  "arguments": {
    "date": "2024-01-15",
    "fromAddress": "Office - 123 Business St, Business City",
    "toAddress": "Client Site - 456 Client Ave, Client City",
    "notes": "Client meeting and project consultation",
    "distance": 45.5,
    "billable": true,
    "type": "Business",
    "customer": {"id": 123},
    "project": {"id": 456},
    "vehicle": {"id": 789},
    "user": {"id": 101}
  }
}

// Update the mileage entry
{
  "name": "update_mileage",
  "arguments": {
    "id": 123,
    "notes": "Updated: Client meeting, project consultation, and site inspection",
    "distance": 52.3,
    "fromAddress": "Office - 123 Business St, Business City",
    "toAddress": "Client Site - 456 Client Ave, Client City (with site inspection)",
    "type": "Business",
    "user": {"id": 101}
  }
}

// Update mileage status (approve multiple mileage entries)
{
  "name": "update_mileage_status",
  "arguments": {
    "message": "Approved by manager after review",
    "mileages": [{"id": 123}, {"id": 124}],
    "status": "Approved"
  }
}

// Update mileage client status
{
  "name": "update_mileage_client_status",
  "arguments": {
    "clientStatus": "Approved",
    "message": "Client approved mileage claims",
    "mileages": [{"id": 123}, {"id": 124}]
  }
}

// Get mileage status history
{
  "name": "get_mileage_status_history",
  "arguments": {
    "id": 123,
    "orderby": "modifiedOn desc"
  }
}

// Get mileage entries with filtering
{
  "name": "get_mileage",
  "arguments": {
    "user_id": "101",
    "from_date": "2024-01-01",
    "to_date": "2024-01-31",
    "filter": "type eq 'Business' and billable eq true",
    "expand": "user,project,customer,vehicle",
    "orderby": "date desc"
  }
}

// Get mileage vehicles
{
  "name": "get_mileage_vehicles",
  "arguments": {
    "active_only": true,
    "expand": "users",
    "orderby": "brand asc"
  }
}

// Get specific mileage vehicle with users
{
  "name": "get_mileage_vehicle_by_id",
  "arguments": {
    "id": 789,
    "expand": "users"
  }
}

Manejo de errores

El servidor incluye un manejo integral de errores:

  • Errores de autenticación: Cuando falta la clave de API o no es válida
  • Errores de API: Cuando la API de TimeChimp devuelve respuestas de error (incluida la limitación de velocidad 429)
  • Errores de red: Cuando las solicitudes fallan debido a problemas de conectividad
  • Errores de validación: Cuando se proporcionan parámetros no válidos
  • Errores de OData: Cuando se utilizan expresiones de filtro u ordenación no válidas

Las respuestas de error incluyen mensajes de error detallados para ayudar con la depuración.

Desarrollo

Estructura del proyecto

TimeJS/
├── timechimp-mcp-server.js    # Main server file
├── package.json               # Node.js dependencies and scripts
└── README.md                  # This file

Agregar nuevas herramientas

Para agregar nuevas herramientas:

  1. Agregue la definición de la herramienta al controlador ListToolsRequestSchema
  2. Agregue un caso para la herramienta en el controlador CallToolRequestSchema
  3. Implemente el método de la herramienta en la clase TimechimpMCPServer
  4. Use los métodos genéricos handleGetRequest o handleGetByIdRequest para mantener la coherencia

Pruebas

Puede probar el servidor con cualquier cliente MCP o ejecutándolo directamente y enviando mensajes JSON-RPC a través de stdin.

Solución de problemas

Problemas comunes

  1. "Se requiere la variable de entorno TIMECHIMP_API_KEY"

    • Asegúrese de haber configurado la variable de entorno TIMECHIMP_API_KEY
    • Verifique que la clave de API sea correcta y tenga los permisos adecuados

  2. "Error de la API de TimeChimp: 401 No autorizado"

    • Compruebe que su clave de API sea válida y no haya caducado
    • Asegúrese de que su cuenta de TimeChimp tenga habilitado el acceso a la API

  3. "TimeChimp API error: 404 Not Found"

    • El endpoint de la API podría no existir o la URL podría ser incorrecta
    • Verifica que estás usando la URL base correcta de la API v2 de TimeChimp

  4. "TimeChimp API error: 429 Too Many Requests"

    • Has superado el límite de solicitudes (100 solicitudes por minuto por empresa)
    • Espera a que se restablezca el límite de solicitudes o implementa una limitación de solicitudes

  5. Errores de filtro OData

    • Verifica que la sintaxis de tu filtro siga las convenciones de OData
    • Comprueba que los nombres de los campos sean correctos y estén correctamente escapados
    • Usa comillas simples para valores de cadena: name eq 'Project Name'

  6. Errores de conexión de red

    • Verifica tu conexión a internet
    • Comprueba si hay restricciones de firewall

Modo de depuración

Ejecuta el servidor en modo de depuración para obtener un registro más detallado:

npm run dev

Contribuciones

  1. Haz un fork del repositorio
  2. Crea una rama de características
  3. Realiza tus cambios
  4. Prueba exhaustivamente
  5. Envía una solicitud de extracción (pull request)

Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulta el archivo LICENSE para obtener más detalles.

Soporte

Para problemas relacionados con:

  • Este servidor MCP: Abre un issue en este repositorio
  • API de TimeChimp: Contacta con el soporte de TimeChimp en ict@timechimp.com
  • Protocolo MCP: Consulta la documentación del Model Context Protocol

Registro de cambios

v0.7.0

  • Se añadieron operaciones CRUD completas para kilometraje (Crear, Leer, Actualizar, Eliminar)
  • Se añadió la gestión de estados de kilometraje con actualizaciones de estado internas y externas
  • Se añadió la funcionalidad de seguimiento del historial de estados de kilometraje
  • Se añadió la gestión de vehículos de kilometraje (operaciones de lectura)
  • Se mejoró la gestión de kilometraje con vinculación integral a clientes, proyectos, vehículos y usuarios
  • Se añadieron capacidades de actualización masiva de estados para kilometraje (hasta 100 entradas a la vez)
  • Se actualizó el número de herramientas a 46 herramientas en total
  • Se añadieron ejemplos de CRUD de kilometraje a la documentación

v0.6.0

  • Se añadieron operaciones CRUD completas para usuarios (Crear, Leer, Actualizar, Eliminar)
  • Se añadió la gestión de contratos de usuario y la asignación de roles
  • Se actualizó el número de herramientas a 38 herramientas en total
  • Se añadieron ejemplos de CRUD de usuarios a la documentación

v0.5.0

  • Se añadieron operaciones CRUD completas para proyectos (Crear, Leer, Actualizar, Eliminar)
  • Se añadió la funcionalidad de información de proyectos
  • Se actualizó el número de herramientas a 36 herramientas en total
  • Se añadieron ejemplos de CRUD de proyectos a la documentación

v0.4.0

  • Se añadieron operaciones CRUD completas para gastos (Crear, Leer, Actualizar, Eliminar)
  • Se añadió la gestión de estados de gastos con actualizaciones de estado internas y externas
  • Se añadió la funcionalidad de seguimiento del historial de estados de gastos
  • Se mejoró la gestión de gastos con vinculación integral a clientes, proyectos, productos, usuarios y tipos de IVA
  • Se añadieron capacidades de actualización masiva de estados para gastos (hasta 100 gastos a la vez)
  • Se actualizó el número de herramientas a 32 herramientas en total
  • Se añadieron ejemplos de CRUD de gastos a la documentación

v0.3.0

  • Se añadieron operaciones CRUD completas para clientes (Crear, Leer, Actualizar, Eliminar)
  • Se añadió una gestión integral de clientes con dirección, condiciones de pago, tarifas y relaciones
  • Se mejoraron las herramientas de clientes con soporte para tipos de IVA, etiquetas y vinculación de contactos
  • Se actualizó el número de herramientas a 26 herramientas en total
  • Se añadieron ejemplos de CRUD de clientes a la documentación

v0.2.0

  • Se añadió soporte integral para todos los endpoints principales de la API v2 de TimeChimp
  • Se añadieron operaciones CRUD completas para contactos (Crear, Leer, Actualizar, Eliminar)
  • Se añadió soporte para clientes, tareas, facturas, gastos, kilometraje y etiquetas
  • Se añadieron manejadores de solicitudes genéricos para consistencia y mantenibilidad
  • Se mejoró el soporte de OData con $expand, $count y un filtrado mejorado
  • Se añadieron herramientas individuales de "obtener por ID" para todos los tipos de recursos
  • Se mejoró el manejo de errores y la validación
  • Se actualizó el encabezado de versión de la API a 2.0

v0.1.0

  • Versión inicial
  • Soporte para las herramientas GetProjects, Users y TimeEntries
  • Integración con la API v2 de TimeChimp con soporte de OData
  • Manejo integral de errores y validación
  • Ordenación predeterminada para proyectos (más recientes primero)