Leia antes:
../conectores.md(mapa de estados) efichas.md(índice das fichas).
What it is#
Reads deals, contacts, accounts and leads from Zoho CRM API v6 and loads them into the Bronze layer.
Supported ingestion modes:
- Nós buscamos — Nós buscamos os dados na sua fonte.
What it's for#
Bring Zoho CRM data into your datalake and make it available to the Bronze/Silver/Gold layers, BI models and the natural-language question wizard.
When to use / when not to use#
Use when you need to consolidate this source into the datalake on a scheduled basis, with isolation per workspace.
Remember that the first run with a real credential is followed by our team before the connector is fully released.
Plan and permissions#
- Plan: core product (connectors are part of all plans; the limit is the number of sources in the plan).
- Access: requires an active workspace — with the subscription overdue, suspended or canceled, runs are blocked.
- Shutdown: ingestion runs can be temporarily turned off (maintenance or incident). When that happens, the UI indicates the feature is unavailable at the moment.
Prerequisites#
- A Zoho CRM account with access to the data you want to ingest.
- In the Zoho API Console (api-console.zoho.com), create a Self Client, generate a code with the ZohoCRM.modules.READ scope and exchange it for a refresh token (POST /oauth/v2/token with grant_type=authorization_code). Provide the Client ID, Client Secret, the refresh token and your account data center (the same as the URL you use the CRM on).
Credentials#
Authentication method: OAuth 2.0 (client id/secret + refresh token). All secrets are encrypted (AES-256-GCM) and are never shown again. If authorization expires, just reconnect — the source and history are preserved.
Sensitive fields. They are encrypted (AES-256-GCM) and never remain in the config of the connection, in the pipeline definition, in exports or in the DAG. By default the encrypted value is stored in the database; moving the credential of this connection to the external credential vault is an explicit choice made per connection after saving — see ../../administracao/credenciais-e-rotacao.md.
- Client Secret (
clientSecret) - Refresh token (
refreshToken) — Refresh token obtained when exchanging the Self Client code. Zoho does not rotate it; if it is revoked, reconnect — there is no need to recreate the source.
Secrets are never re-shown and are redacted in all error/log output (raw token, URL-encoded and in JSON).
Form fields#
| Campo | Rótulo | Tipo | Obrigatório | Observação |
|---|---|---|---|---|
dominioApi | Data center | seleção | não | padrão: www.zohoapis.com; opções: www.zohoapis.com / www.zohoapis.eu / www.zohoapis.in / www.zohoapis.com.au; Contas brasileiras normalmente ficam no data center dos Estados Unidos. |
clientId | Client ID | texto | sim | Client ID do Self Client criado no Zoho API Console (começa com 1000.). |
clientSecret 🔒 | Client Secret | senha/segredo | sim | segredo (cifrado; cofre externo opcional) |
refreshToken 🔒 | Refresh token | senha/segredo | sim | segredo (cifrado; cofre externo opcional); Refresh token obtido ao trocar o código do Self Client. O Zoho não o rotaciona; se for revogado, reconecte — não é preciso recriar a fonte. |
Step-by-step#
- No menu Dados → Conexões, use Nova conexão.
- Escolha Zoho CRM no catálogo.
- Preencha os campos do formulário (veja a tabela acima).
- Use Testar conexão. The result is shown broken down into Conectividade, Autenticação and Listagem/leitura — each with OK, Failed, Not applicable or Not tested. A capability with no test of its own for this connector shows as Not applicable, and Not applicable never counts as success.
- Use Salvar conexão. Salvar NÃO inicia ingestão nenhuma.
- No cartão da conexão, use Montar extração (ou vá em Orquestração → Pipelines e use Conectar fonte). O pipeline aponta para a conexão salva — a credencial não é copiada.
- Na revisão, Publicar (agenda desligada) cria a versão 1 sem executar nada. Depois, Ativar agenda e Executar agora são ações separadas.
Example — connection test#
Example configuration (all values are fictitious; secrets are masked):
# Exemplo sintético (valores fictícios — não são credenciais reais)
dominioApi = www.zohoapis.com
clientId = exemplo-client-id-ficticio
clientSecret = •••••• (cifrado — nunca exibido)
refreshToken = •••••• (cifrado — nunca exibido)Expected result#
The Testar conexão returns the list of discovered tables/resources. After the first load, rows appear in the Bronze layer of your workspace, ready for the pipeline.
Limits and costs#
- Pagination: hard cap per run (default 10,000 pages / 5,000,000 rows); anti-loop guard.
- SaaS load: default
batchSize5,000,maxRows200,000 per resource. - Estimated volume: ~0.4 GB/month (catalog estimate, not measurement).
- Cost: the extraction itself is not charged by the platform; the Bronze load consumes datalake processing (billable).
Security#
- Scope per workspace: each customer reads and writes only to their own datalake (
<prefix>_bronze/_silver/_gold); there is never leakage between workspaces. - Encrypted secrets: sensitive material is encrypted with AES-256-GCM before being persisted. The external credential vault is optional and enabled per connection; without it, the encrypted value is stored in the database. Changing the value here does NOT revoke the credential at the source.
- Redaction: all error/log output is passed through secret redaction (raw, URL-encoded and in JSON).
- Production does not fake: a path that would hit mocks triggers the production guard (explicit failure instead of simulating success).
Common errors#
- Credential refused (401/403) — the provider rejected the credential: expired, revoked or lacking the required permission. Reconnect the source (the source and history are preserved; do not recreate the source).
- Rate limit (429) — the provider asked to wait. The extraction respects
Retry-Afterand retries; if it repeats, wait and reduce the schedule frequency. - Resource not found — check the resource identifier (account, object, report) and the granted permissions.
- Pagination cursor stuck — extraction stops when the API cursor does not advance (anti-loop guard). If it happens in consecutive runs, open a support ticket specifying the connector and the resource.
- Empty records path — the response arrived without records where expected. Check the selected resource and filters (period, account, status) before assuming there is no data.
Troubleshooting#
- Use Testar conexão to isolate credential/network issues before scheduling.
- Monitor runs in connector observability (error rate, p50/p95, freshness).
- A schema change at the source is signaled by schema drift (new column = info; removed column/type changed = attention).
Related#
../conectores.md— catálogo de conectores por estado../ingestao-incremental-backfill.md— full, incremental by watermark, backfill and checkpoint../pipeline-medalhao.md— camadas Bronze/Silver/Gold e qualidade../agendamento-retry-dlq.md— agendamento, retry/backoff e DLQ../custo-limites-seguranca.md— custo, tetos e segurança por workspace
Last review: 2026-10-04. Card automatically generated from the product connectors catalog.