Communitygithub.com

CraftOS-dev/CraftBot

Integración con la API de Zoho CRM con OAuth administrado. Gestiona prospectos, contactos, cuentas, negocios y otros registros de CRM.

¿Qué es CraftBot?

Este skill proporciona una integración completa con la API de Zoho CRM a través de una pasarela que gestiona la autenticación OAuth de forma transparente. Permite a los agentes de IA realizar operaciones CRUD completas (crear, leer, actualizar y eliminar) sobre los módulos principales de Zoho CRM, como prospectos (Leads), contactos (Contacts), cuentas (Accounts) y negocios (Deals). Además, ofrece funcionalidades avanzadas como búsqueda por criterios, email o teléfono, gestión de conexiones OAuth, y la capacidad de listar y administrar conexiones activas. Está diseñado para usarse con cualquier API de IA que soporte ejecución de scripts de Python y acceso a redes. La autenticación se realiza mediante la clave de API de Maton, que se pasa en el encabezado 'Authorization'. Es útil para automatizar tareas de CRM, como la sincronización de datos de clientes, la gestión de pipelines de ventas y la actualización masiva de registros, todo desde un agente de IA.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/CraftOS-dev/CraftBot/tree/HEAD/skills/zoho-crm
Ver original→Ver todas las habilidades

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Documentación

Zoho CRM

Accede a la API de Zoho CRM con autenticación OAuth administrada. Gestiona prospectos, contactos, cuentas, negocios y otros módulos de CRM con operaciones CRUD completas, incluyendo búsqueda y operaciones masivas. También admite detalles de organización, gestión de usuarios y recuperación de metadatos de módulos.

Inicio Rápido

# Listar prospectos
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads?fields=First_Name,Last_Name,Email')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

URL Base

https://gateway.maton.ai/zoho-crm/crm/v8/{endpoint}

La pasarela envía las peticiones a www.zohoapis.com/crm/v8 e inyecta automáticamente tu token OAuth.

Autenticación

Todas las solicitudes requieren la clave de API de Maton en el encabezado Authorization:

Authorization: Bearer $MATON_API_KEY

Variable de Entorno: Establece tu clave de API como MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Cómo Obtener tu Clave de API

  1. Inicia sesión o crea una cuenta en maton.ai
  2. Ve a maton.ai/settings
  3. Copia tu clave de API

Gestión de Conexiones

Gestiona tus conexiones OAuth de Zoho CRM en https://ctrl.maton.ai.

Listar Conexiones

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=zoho-crm&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Crear Conexión

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'zoho-crm'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Obtener Conexión

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Respuesta:

{
  "connection": {
    "connection_id": "e55c5bac-241a-4cc8-9db5-50d2cad09136",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "zoho-crm",
    "metadata": {}
  }
}

Abre la url devuelta en un navegador para completar la autorización OAuth.

Eliminar Conexión

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Especificar Conexión

Si tienes varias conexiones de Zoho CRM, especifica cuál usar con el encabezado Maton-Connection:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads?fields=First_Name,Last_Name,Email')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', 'e55c5bac-241a-4cc8-9db5-50d2cad09136')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Si se omite, la pasarela usa la conexión activa por defecto (la más antigua).

Referencia de la API

Módulos

Zoho CRM organiza los datos en módulos. Los módulos principales incluyen:

MóduloNombre de APIDescripción
ProspectosLeadsClientes potenciales
ContactosContactsPersonas individuales
CuentasAccountsOrganizaciones/empresas
NegociosDealsOportunidades de venta
CampañasCampaignsCampañas de marketing
TareasTasksElementos pendientes
LlamadasCallsRegistros de llamadas telefónicas
EventosEventsCitas del calendario
ProductosProductsArtículos que vendes

Listar Registros

GET /zoho-crm/crm/v8/{module_api_name}?fields={field1},{field2}

Parámetros de Consulta:

ParámetroTipoDescripción
fieldsstringObligatorio. Nombres de campo de API separados por comas (máx. 50)
pageintegerNúmero de página (por defecto: 1)
per_pageintegerRegistros por página (por defecto/máx.: 200)
sort_bystringOrdenar por: id, Created_Time, o Modified_Time
sort_orderstringasc o desc (por defecto)
cvidlongID de vista personalizada
page_tokenstringPara paginación de >2000 registros

Ejemplo - Listar Prospectos:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads?fields=First_Name,Last_Name,Email,Phone,Company')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Respuesta:

{
  "data": [
    {
      "First_Name": "Christopher",
      "Email": "[email protected]",
      "Last_Name": "Maclead (Sample)",
      "Phone": "555-555-5555",
      "Company": "Rangoni Of Florence",
      "id": "7243485000000597000"
    }
  ],
  "info": {
    "per_page": 200,
    "count": 1,
    "page": 1,
    "sort_by": "id",
    "sort_order": "desc",
    "more_records": false,
    "next_page_token": null
  }
}

Ejemplo - Listar Contactos:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Contacts?fields=First_Name,Last_Name,Email,Phone')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Ejemplo - Listar Cuentas:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Accounts?fields=Account_Name,Website,Phone')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Ejemplo - Listar Negocios:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Deals?fields=Deal_Name,Stage,Amount')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Obtener Registro

GET /zoho-crm/crm/v8/{module_api_name}/{record_id}

Ejemplo:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads/7243485000000597000')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Crear Registros

POST /zoho-crm/crm/v8/{module_api_name}
Content-Type: application/json

{
  "data": [
    {
      "field_api_name": "value"
    }
  ]
}

Campos Obligatorios por Módulo:

MóduloCampos Obligatorios
ProspectosLast_Name
ContactosLast_Name
CuentasAccount_Name
NegociosDeal_Name, Stage
TareasSubject
LlamadasSubject, Call_Type, Call_Start_Time, Call_Duration
EventosEvent_Title, Start_DateTime, End_DateTime

Ejemplo - Crear Prospecto:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [{
        "Last_Name": "Smith",
        "First_Name": "John",
        "Email": "[email protected]",
        "Company": "Acme Corp",
        "Phone": "+1-555-0123"
    }]
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Respuesta:

{
  "data": [
    {
      "code": "SUCCESS",
      "details": {
        "Modified_Time": "2026-02-06T01:10:56-08:00",
        "Modified_By": {
          "name": "User Name",
          "id": "7243485000000590001"
        },
        "Created_Time": "2026-02-06T01:10:56-08:00",
        "id": "7243485000000619001",
        "Created_By": {
          "name": "User Name",
          "id": "7243485000000590001"
        }
      },
      "message": "record added",
      "status": "success"
    }
  ]
}

Ejemplo - Crear Contacto:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [{
        "Last_Name": "Doe",
        "First_Name": "Jane",
        "Email": "[email protected]",
        "Phone": "+1-555-9876"
    }]
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Contacts', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Ejemplo - Crear Cuenta:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [{
        "Account_Name": "Acme Corporation",
        "Website": "https://acme.com",
        "Phone": "+1-555-1234"
    }]
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Accounts', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Actualizar Registros

PUT /zoho-crm/crm/v8/{module_api_name}
Content-Type: application/json

{
  "data": [
    {
      "id": "record_id",
      "field_api_name": "updated_value"
    }
  ]
}

Ejemplo:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [{
        "id": "7243485000000619001",
        "Phone": "+1-555-9999",
        "Company": "Updated Company Name"
    }]
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads', data=data, method='PUT')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Respuesta:

{
  "data": [
    {
      "code": "SUCCESS",
      "details": {
        "Modified_Time": "2026-02-06T01:11:01-08:00",
        "Modified_By": {
          "name": "User Name",
          "id": "7243485000000590001"
        },
        "Created_Time": "2026-02-06T01:10:56-08:00",
        "id": "7243485000000619001",
        "Created_By": {
          "name": "User Name",
          "id": "7243485000000590001"
        }
      },
      "message": "record updated",
      "status": "success"
    }
  ]
}

Eliminar Registros

DELETE /zoho-crm/crm/v8/{module_api_name}?ids={record_id1},{record_id2}

Parámetros de Consulta:

ParámetroTipoDescripción
idsstringIDs de registros separados por comas (obligatorio, máx. 100)
wf_triggerbooleanEjecutar flujos de trabajo (por defecto: true)

Ejemplo:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads?ids=7243485000000619001', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Respuesta:

{
  "data": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "7243485000000619001"
      },
      "message": "record deleted",
      "status": "success"
    }
  ]
}

Buscar Registros

GET /zoho-crm/crm/v8/{module_api_name}/search

Parámetros de Consulta (uno obligatorio):

ParámetroTipoDescripción
criteriastringCriterio de búsqueda (ej., (Last_Name:equals:Smith))
emailstringBuscar por dirección de correo electrónico
phonestringBuscar por número de teléfono
wordstringBúsqueda de texto global
pageintegerNúmero de página
per_pageintegerRegistros por página (máx. 200)

Formato de Criterio: ((field_api_name:operator:value) and/or (...))

Operadores:

  • Campos de texto: equals, not_equal, starts_with, in
  • Campos de fecha/número: equals, not_equal, greater_than, less_than, between, in
  • Campos booleanos: equals, not_equal

Ejemplo - Buscar por email:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads/[email protected]')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Ejemplo - Buscar por criterio:

python <<'EOF'
import urllib.request, os, json
import urllib.parse
criteria = urllib.parse.quote('(Last_Name:starts_with:Smith)')
req = urllib.request.Request(f'https://gateway.maton.ai/zoho-crm/crm/v8/Leads/search?criteria={criteria}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Respuesta:

{
  "data": [
    {
      "First_Name": "Christopher",
      "Email": "[email protected]",
      "Last_Name": "Maclead (Sample)",
      "id": "7243485000000597000"
    }
  ],
  "info": {
    "per_page": 200,
    "count": 1,
    "page": 1,
    "more_records": false
  }
}

Detalles de la Organización

Obtener Detalles de la Organización

GET /zoho-crm/crm/v8/org

Ejemplo:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/org')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Obtener Metadatos de Módulos

GET /zoho-crm/crm/v8/settings/modules/{module_api_name_or_id}

Ejemplo - Obtener metadatos de Prospectos:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/settings/modules/Leads')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Obtener Todos los Módulos

GET /zoho-crm/crm/v8/settings/modules

Gestión de Usuarios

GET /zoho-crm/crm/v8/users?type={type}

Parámetros de Consulta:

ParámetroTipoDescripción
typestringTipo de usuario: ActiveUsers, DeactiveUsers, AllUsers, AdminUsers, ActiveConfirmedAdmins
pageintegerNúmero de página
per_pageintegerRegistros por página (máx. 200)

Ejemplo - Listar Usuarios Activos:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/users?type=ActiveUsers')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Gestión de Roles

GET /zoho-crm/crm/v8/settings/roles

Gestión de Perfiles

GET /zoho-crm/crm/v8/settings/profiles

Obtener Campos de Módulo Personalizados

GET /zoho-crm/crm/v8/settings/fields?module={module_api_name}

Ejemplo - Obtener campos de Prospectos:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/settings/fields?module=Leads')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Pipeline de Ventas

Obtener Etapas de Pipeline

GET /zoho-crm/crm/v8/settings/pipelines/{module_api_name}

Ejemplo - Obtener pipelines de Negocios:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/settings/pipelines/Deals')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Operaciones Masivas

Crear Registros Masivamente

POST /zoho-crm/crm/v8/{module_api_name}
Content-Type: application/json

{
  "data": [
    { ... },
    { ... },
    { ... }
  ]
}

Ejemplo - Crear Múltiples Prospectos:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [
        {"Last_Name": "Smith", "First_Name": "John", "Company": "Acme Corp"},
        {"Last_Name": "Doe", "First_Name": "Jane", "Company": "Beta Inc"},
        {"Last_Name": "Brown", "First_Name": "Bob", "Company": "Gamma LLC"}
    ]
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Actualizar Registros Masivamente

PUT /zoho-crm/crm/v8/{module_api_name}
Content-Type: application/json

{
  "data": [
    {"id": "1", ...},
    {"id": "2", ...},
    ...
  ]
}

Ejemplo - Actualizar Múltiples Prospectos:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [
        {"id": "7243485000000619001", "Phone": "+1-555-1111"},
        {"id": "7243485000000619002", "Phone": "+1-555-2222"}
    ]
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads', data=data, method='PUT')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Eliminar Registros Masivamente

DELETE /zoho-crm/crm/v8/{module_api_name}?ids=1,2,3

Manejo de Errores

La API responde con códigos de error HTTP estándar junto con el cuerpo:

{
  "data": [
    {
      "code": "INVALID_DATA",
      "details": {},
      "message": "El campo obligatorio Last_Name no se ha proporcionado.",
      "status": "error"
    }
  ]
}

Códigos de Error Comunes

Código HTTPSignificado
400Solicitud incorrecta - Campos faltantes o inválidos
401No autorizado - Clave de API de Maton inválida
403Prohibido - Token OAuth inválido
404No encontrado - Registro o módulo no encontrado
429Demasiadas solicitudes - Límite de tasa excedido
500Error interno del servidor

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

CraftOS-dev/CraftBot

Agent skill at skills/cli-anything/SKILL.md

CraftOS-dev/CraftBot

Complete toolkit for programmatic video creation with Remotion + React. Covers animations, timing, rendering (CLI/Node.js/Lambda/Cloud Run), captions, 3D, charts, text effects, transitions, and media handling. Use when writing Remotion code, building video generation pipelines, or creating data-driven video templates.

Skills relacionados

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community