Zoho CRM

Acesse a API do Zoho CRM com autenticação OAuth gerenciada. Gerencie leads, contatos, contas, negócios e outros módulos do CRM com operações CRUD completas, incluindo pesquisa e operações em lote. Também suporta detalhes da organização, gerenciamento de usuários e recuperação de metadados de módulos.

Início Rápido

# Listar leads
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}

O gateway encaminha requisições para www.zohoapis.com/crm/v8 e injeta automaticamente seu token OAuth.

Autenticação

Todas as requisições exigem a chave de API Maton no cabeçalho Authorization:

Authorization: Bearer $MATON_API_KEY

Variável de Ambiente: Defina sua chave de API como MATON_API_KEY:

export MATON_API_KEY="SUA_CHAVE_API"

Obtendo Sua Chave de API

Faça login ou crie uma conta em maton.ai
Vá para maton.ai/settings
Copie sua chave de API

Gerenciamento de Conexão

Gerencie suas conexões OAuth do Zoho CRM em https://ctrl.maton.ai.

Listar Conexões

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

Criar Conexão

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

Obter Conexão

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

Resposta:

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

Abra a url retornada em um navegador para concluir a autorização OAuth.

Excluir Conexão

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

Especificando Conexão

Se você tiver várias conexões do Zoho CRM, especifique qual usar com o cabeçalho 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

Se omitido, o gateway usa a conexão ativa padrão (a mais antiga).

Referência da API

Módulos

O Zoho CRM organiza dados em módulos. Módulos principais incluem:

Módulo	Nome da API	Descrição
Leads	`Leads`	Clientes potenciais
Contatos	`Contacts`	Pessoas individuais
Contas	`Accounts`	Organizações/empresas
Negócios	`Deals`	Oportunidades de vendas
Campanhas	`Campaigns`	Campanhas de marketing
Tarefas	`Tasks`	Itens a fazer
Chamadas	`Calls`	Registros de chamadas telefônicas
Eventos	`Events`	Compromissos de calendário
Produtos	`Products`	Itens que você vende

Listar Registros

GET /zoho-crm/crm/v8/{nome_api_modulo}?fields={campo1},{campo2}

Parâmetros de Consulta:

Parâmetro	Tipo	Descrição
`fields`	string	Obrigatório. Nomes de campos da API separados por vírgula (máx. 50)
`page`	inteiro	Número da página (padrão: 1)
`per_page`	inteiro	Registros por página (padrão/máx: 200)
`sort_by`	string	Ordenar por: `id`, `Created_Time` ou `Modified_Time`
`sort_order`	string	`asc` ou `desc` (padrão)
`cvid`	longo	ID da visualização personalizada
`page_token`	string	Para paginação com >2000 registros

Exemplo - Listar Leads:

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

Resposta:

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

Exemplo - Listar Contatos:

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

Exemplo - Listar Contas:

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

Exemplo - Listar Negócios:

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

Obter Registro

GET /zoho-crm/crm/v8/{nome_api_modulo}/{id_registro}

Exemplo:

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

Criar Registros

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

{
  "data": [
    {
      "nome_campo_api": "valor"
    }
  ]
}

Campos Obrigatórios por Módulo:

Módulo	Campos Obrigatórios
Leads	`Last_Name`
Contatos	`Last_Name`
Contas	`Account_Name`
Negócios	`Deal_Name`, `Stage`
Tarefas	`Subject`
Chamadas	`Subject`, `Call_Type`, `Call_Start_Time`, `Call_Duration`
Eventos	`Event_Title`, `Start_DateTime`, `End_DateTime`

Exemplo - Criar Lead:

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

Resposta:

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

Exemplo - Criar Contato:

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

Exemplo - Criar Conta:

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

Atualizar Registros

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

{
  "data": [
    {
      "id": "id_registro",
      "nome_campo_api": "valor_atualizado"
    }
  ]
}

Exemplo:

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

Resposta:

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

Excluir Registros

DELETE /zoho-crm/crm/v8/{nome_api_modulo}?ids={id_registro1},{id_registro2}

Parâmetros de Consulta:

Parâmetro	Tipo	Descrição
`ids`	string	IDs de registros separados por vírgula (obrigatório, máx. 100)
`wf_trigger`	booleano	Executar workflows (padrão: true)

Exemplo:

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

Resposta:

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

Pesquisar Registros

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

Parâmetros de Consulta (um obrigatório):

Parâmetro	Tipo	Descrição
`criteria`	string	Critérios de pesquisa (ex.: `(Last_Name:equals:Smith)`)
`email`	string	Pesquisar por endereço de e-mail
`phone`	string	Pesquisar por número de telefone
`word`	string	Pesquisa de texto global
`page`	inteiro	Número da página
`per_page`	inteiro	Registros por página (máx. 200)

Formato de Critérios: ((nome_campo:operador:valor) e/ou (...))

Operadores:

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

Exemplo - Pesquisar por e-mail:

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

Exemplo - Pesquisar por critérios:

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

Resposta:

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

Detalhes da Organização

...

CraftOS-dev/CraftBot

O que é CraftBot?

Perguntar na sua IA favorita

Documentação

Zoho CRM

Início Rápido

URL Base

Autenticação

Obtendo Sua Chave de API

Gerenciamento de Conexão

Listar Conexões

Criar Conexão

Obter Conexão

Excluir Conexão

Especificando Conexão

Referência da API

Módulos

Listar Registros

Obter Registro

Criar Registros

Atualizar Registros

Excluir Registros

Pesquisar Registros

Detalhes da Organização

Individual skills in this repo

CraftOS-dev/CraftBot

CraftOS-dev/CraftBot

Habilidades Relacionadas

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me