Communitygithub.com

CraftOS-dev/CraftBot

Intégration de l'API Zoho CRM avec OAuth géré. Gérez les prospects, contacts, comptes, affaires et autres enregistrements CRM.

Qu'est-ce que CraftBot ?

Cette compétence permet aux agents d'IA (tels que Claude Code, Cursor, etc.) d'interagir avec l'API Zoho CRM via une passerelle Maton, qui gère automatiquement l'authentification OAuth. Elle prend en charge toutes les opérations CRUD (créer, lire, mettre à jour, supprimer) sur les modules principaux de Zoho CRM, y compris les prospects, contacts, comptes, affaires, campagnes, tâches, appels, événements et produits. De plus, elle permet la recherche avancée avec des critères, des filtres par email ou téléphone, et la récupération de données organisationnelles et de métadonnées de modules. La gestion des connexions OAuth se fait via `ctrl.maton.ai`, où vous pouvez lister, créer, obtenir et supprimer des connexions. La compétence fonctionne en nécessitant une clé API Maton (`MATON_API_KEY`) dans l'en-tête Authorization. Elle fournit des exemples Python prêts à l'emploi pour toutes les opérations, via le point d'accès `https://gateway.maton.ai/zoho-crm/crm/v8/`. Idéale pour automatiser les flux de vente, la gestion de leads, et l'intégration de données CRM dans des environnements de développement ou d'automatisation.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/CraftOS-dev/CraftBot/tree/HEAD/skills/zoho-crm

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Zoho CRM

Accédez à l'API Zoho CRM avec authentification OAuth gérée. Gérez les prospects, contacts, comptes, affaires et autres modules CRM avec des opérations CRUD complètes, y compris la recherche et les opérations par lot. Prend également en charge les détails de l'organisation, la gestion des utilisateurs et la récupération des métadonnées des modules.

Démarrage rapide

# Lister les prospects
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 de base

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

La passerelle transmet les requêtes à www.zohoapis.com/crm/v8 et injecte automatiquement votre jeton OAuth.

Authentification

Toutes les requêtes nécessitent la clé API Maton dans l'en-tête Authorization :

Authorization: Bearer $MATON_API_KEY

Variable d'environnement : Définissez votre clé API comme MATON_API_KEY :

export MATON_API_KEY="YOUR_API_KEY"

Obtenir votre clé API

  1. Connectez-vous ou créez un compte sur maton.ai
  2. Allez dans maton.ai/settings
  3. Copiez votre clé API

Gestion des connexions

Gérez vos connexions OAuth Zoho CRM sur https://ctrl.maton.ai.

Lister les connexions

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

Créer une connexion

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

Obtenir une connexion

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

Réponse :

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

Ouvrez l'url renvoyée dans un navigateur pour terminer l'autorisation OAuth.

Supprimer une connexion

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

Spécifier une connexion

Si vous avez plusieurs connexions Zoho CRM, spécifiez laquelle utiliser avec l'en-tête 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 omis, la passerelle utilise la connexion active par défaut (la plus ancienne).

Référence de l'API

Modules

Zoho CRM organise les données en modules. Les modules principaux incluent :

ModuleNom APIDescription
ProspectsLeadsClients potentiels
ContactsContactsPersonnes individuelles
ComptesAccountsOrganisations/entreprises
AffairesDealsOpportunités de vente
CampagnesCampaignsCampagnes marketing
TâchesTasksÉléments à faire
AppelsCallsJournaux d'appels téléphoniques
ÉvénementsEventsRendez-vous du calendrier
ProduitsProductsArticles que vous vendez

Lister les enregistrements

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

Paramètres de requête :

ParamètreTypeDescription
fieldsstringObligatoire. Noms des champs API séparés par des virgules (max 50)
pageintegerNuméro de page (défaut : 1)
per_pageintegerEnregistrements par page (défaut/max : 200)
sort_bystringTrier par : id, Created_Time ou Modified_Time
sort_orderstringasc ou desc (défaut)
cvidlongID de vue personnalisée
page_tokenstringPour la pagination de >2000 enregistrements

Exemple - Lister les prospects :

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

Réponse :

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

Exemple - Lister les contacts :

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

Exemple - Lister les comptes :

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

Exemple - Lister les affaires :

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

Obtenir un enregistrement

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

Exemple :

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

Créer des enregistrements

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

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

Champs obligatoires par module :

ModuleChamps requis
ProspectsLast_Name
ContactsLast_Name
ComptesAccount_Name
AffairesDeal_Name, Stage
TâchesSubject
AppelsSubject, Call_Type, Call_Start_Time, Call_Duration
ÉvénementsEvent_Title, Start_DateTime, End_DateTime

Exemple - Créer un prospect :

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

Réponse :

{
  "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"
    }
  ]
}

Exemple - Créer un contact :

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

Exemple - Créer un compte :

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

Mettre à jour des enregistrements

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

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

Exemple :

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

Réponse :

{
  "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"
    }
  ]
}

Supprimer des enregistrements

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

Paramètres de requête :

ParamètreTypeDescription
idsstringIDs d'enregistrements séparés par des virgules (obligatoire, max 100)
wf_triggerbooleanExécuter les workflows (défaut : true)

Exemple :

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

Réponse :

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

Rechercher des enregistrements

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

Paramètres de requête (un obligatoire) :

ParamètreTypeDescription
criteriastringCritères de recherche (p. ex., (Last_Name:equals:Smith))
emailstringRecherche par adresse email
phonestringRecherche par numéro de téléphone
wordstringRecherche textuelle globale
pageintegerNuméro de page
per_pageintegerEnregistrements par page (max 200)

Format des critères : ((field_api_name:operator:value) and/or (...))

Opérateurs :

  • Champs texte : equals, not_equal, starts_with, in
  • Champs date/nombre : equals, not_equal, greater_than, less_than, between, in
  • Champs booléens : equals, not_equal

Exemple - Recherche par 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

Exemple - Recherche par critères :

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

Réponse :

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

Détails de l'organisation

...

Individual skills in this repo

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

Skills associés