Funções – Tarefas de integração
Como você já deve saber, a atualização para as APIs versão 2.0 desempenhou um papel importante no uso de funções personalizadas, agora chamadas de "Funções". Este guia ajudará você a usar as tarefas de integração de funções que usam as novas APIs.
Introdução
Para começar, a diferença básica entre as versões 1.0 e 2.0 das APIs Zoho é que usa-se Nomes de campo no primeiro e Nomes de API no último.
Para obter os Nomes de API dos módulos:
- Vá para Configuração > Espaço do desenvolvedor > APIs > API do CRM > Nomes de API.
- Os Nomes de API dos módulos são listados na guia Nomes de API.
Para obter os Nomes de API de campos nos módulos:
- Vá para Configuração > Espaço do desenvolvedor > APIs > API do CRM > Nomes de API.
- Clique em um nome de módulo. Por exemplo: Leads
- A guia Nome de API contém os Nomes de API dos campos. Esses campos devem ser usados no código, e NÃO os nomes contidos na guia Rótulo do Campo.
Obter registros
Os registros, contendo informações, podem ser obtidos de vários módulos suportados do CRM. Você pode obter os registros usando a tarefa zoho.crm.getRecords().
Sintaxe: (usando APIs Versão 2.0)
<response>=zoho.crm.getRecords(<module_name>, [<page>],[<perPage>], {<optionalDataMap>}, <connections>);
| Parâmetros | Descrição |
|---|---|
| <response> | A resposta com a LISTA de registros que correspondem aos critérios de busca. |
| <module_name> | O nome do módulo do qual o registro deve ser buscado. Os módulos suportados são: Leads, Negócios, Produtos, Contatos, Campanhas, Fornecedores, Contas, Casos, Cotações, Ordens de venda, Ordens de compra, Faturas e Personalizado. |
| <page> (opcional) | Para obter a lista de registros com base nas páginas. É do tipo de dados NÚMERO. Padrão - 1. |
| <perPage> (opcional) | Usado para obter a lista de registros por página. É do tipo de dados NÚMERO. Padrão - 200. |
| <optionalDataMap> | Usado para obter a lista de registros usando parâmetros diferentes de page e per_page. |
| <connections> | Exibe os conectores associados à função. O tipo de dados é STRING. |
Entrada de amostra:
resp = zoho.crm.getRecords("Leads",1,20,{"converted":"true"});
Nota:
- Na amostra acima, "converted" é um optionalDataMap.
Sintaxe: (usando APIs Versão 1.0)
<response>=zoho.crm._getRecords(<module_name>, [<from_index>],[<to_index>]);
Obter registro por ID
Obter uma lista de registros é muito bom, mas e se você quiser buscar detalhes sobre um registro específico. Você pode usar a tarefa zoho.crm.getRecordById() para obter as informações sobre um registro específico.
Sintaxe: (usando APIs Versão 2.0)
<response>=zoho.crm.getRecordById(<module_name>, <record_ID>, <connections>);
| Parâmetros | Descrição |
|---|---|
| <response> | A resposta que retornou como um MAPA. |
| <module_name> | O nome do módulo do qual o registro deve ser buscado. Os módulos suportados são: Leads, Negócios, Produtos, Contatos, Campanhas, Fornecedores, Contas, Casos, Cotações, Ordens de venda, Ordens de compra, Faturas e Personalizado. |
| <record_ID> | A ID do registro a ser buscado. É do tipo de dados NÚMERO. |
| <connections> | Exibe os conectores associados à função. O tipo de dados é STRING. |
Entrada de amostra:
resp = zoho.crm.getRecordById("Leads", 2938383000000392001);
Sintaxe: (usando APIs Versão 1.0)
<response>=zoho.crm._getRecordById(<module_name>, <record_ID>);
Criar um registro
Configure as funções de forma que os registros sejam criados automaticamente com base em determinadas ações. Por exemplo: você pode acionar a função para criar um registro em tarefas após alterar o status de um lead. A tarefa zoho.crm.create() é usada para criar registros.
Sintaxe: (usando APIs Versão 2.0)
<variable>=zoho.crm.create(<module_name>,{<dataMap>}, {<optionalDataMap>}, <connections>);
| Parâmetros | Descrição |
|---|---|
| <response> | A resposta que é retornada como um MAPA. |
| <module_name> | O nome do módulo do qual o registro deve ser buscado. Os módulos suportados são: Leads, Negócios, Produtos, Contatos, Campanhas, Fornecedores, Contas, Casos, Cotações, Ordens de venda, Ordens de compra, Faturas e Personalizado. |
| <dataMap> | O nome dos campos no módulo que devem ser especificados durante a criação do registro. Por ex.: {"Last_name":"Zoho CRM"} |
| <optionalDataMap> | Representa todos os mapas de dados diferentes de JSON de entrada. |
| <connections> | Exibe os conectores associados à função. O tipo de dados é STRING. |
Entrada de amostra:
data = Map();
data.putAll({"Last_Name":"Bruce Wills", "Company":"Zillum"});
optionalMap = Map();
optionalMap.put("trigger", ["workflow","approval", "blueprint"]); // pass "trigger" as empty [] to not execute workflow
resp = zoho.crm.create("Leads", data, optionalMap);
Resposta da amostra:
{"Modified_Time":"2018-03-26T14:33:01+05:30","Modified_By":{"name":"Ben","id":"2938383000000132011"},"Created_Time":"2018-03-26T14:33:01+05:30","id":"2938383000000389001","Created_By":{"name":"Ben","id":"2938383000000132011"}}
Sintaxe: (usando APIs Versão 1.0)
<variable>=zoho.crm._create(<module_name>,{<field_values>});
Criar registros em massa
Configure as funções de forma que os registros sejam criados automaticamente com base em determinadas ações. Por exemplo: você pode acionar a função para criar vários registros, em contatos, contas, tarefas, negócios etc., após alterar a conversão de um lead em um contato. A tarefa zoho.crm.bulkCreate() é usada para criar registros.
Sintaxe: (usando APIs Versão 2.0)
<variable>=zoho.crm.bulkCreate(<module_name>,[record1, record2]);
| Parâmetros | Descrição |
|---|---|
| <response> | A resposta que é retornada como um MAPA. |
| <module_name> | O nome do módulo do qual o registro deve ser buscado. Os módulos suportados são: Leads, Negócios, Produtos, Contatos, Campanhas, Fornecedores, Contas, Casos, Cotações, Ordens de venda, Ordens de compra, Faturas e Personalizado. |
| [record1, record2] | A LISTA que contém as informações sobre o registros a serem criados. |
Entrada de amostra:
resp = zoho.crm.bulkCreate("Leads", [{"Last_Name":"Deborah"},{"Last_Name":"James"}], {"trigger":["workflow","blueprint","approval"]});
Atualizar um registro
Muitas vezes, há momentos em que você teria que atualizar os registros. Editar as informações existentes, incluir informações adicionais etc. podem ser feitos automaticamente, definindo a tarefa zoho.crm.updateRecord() que atualiza automaticamente um registro com base no cenário programado.
Sintaxe: (usando APIs Versão 2.0)
<response>=zoho.crm.updateRecord(<module_name>, <record_ID>, <dataMap>, {<optionalDataMap>}, <connections>);
| Parâmetros | Descrição |
|---|---|
| <response> | A resposta que é retornada como um MAPA. |
| <module_name> | O nome do módulo do qual o registro deve ser buscado. Os módulos suportados são: Leads, Negócios, Produtos, Contatos, Campanhas, Fornecedores, Contas, Casos, Cotações, Ordens de venda, Ordens de compra, Faturas e Personalizado. |
| <record_ID> | A ID do registro a ser atualizado. É do tipo de dados NÚMERO. |
| <dataMap> | Chave. Pares de valor com informações de registro atualizadas. |
| <optionalDataMap> | Representa todos os mapas de dados diferentes de JSON de entrada. |
| <connections> | Exibe os conectores associados à função. O tipo de dados é STRING. |
Entrada de amostra:
resp = zoho.crm.update("Leads", 2938383000000392001, {"Company":"Zillum Corp"});
Resposta da amostra:
{"Modified_Time":"2018-03-26T15:17:39+05:30","Modified_By":{"name":"Ben","id":"2938383000000132011"},"Created_Time":"2018-03-26T14:39:28+05:30","id":"2938383000000392001","Created_By":{"name":"Ben","id":"2938383000000132011"}}
Sintaxe: (usando APIs Versão 1.0)
<response>=zoho.crm._updateRecord(<module_name>, <record_ID>, <New values as map object>);
Pesquisar um registro
Pesquise registros específicos especificando os critérios para a pesquisa. Os registros pesquisados podem ser usados para executar ações em qualquer lugar. Pesquisar um registro exige que o nome do módulo e os critérios de pesquisa sejam especificados.
Sintaxe: (usando APIs Versão 2.0)
<response>=zoho.crm.searchRecords(<module_name>, <criteria>, [<page>],[<perPage>], <connections>);
| Parâmetros | Descrição |
|---|---|
| <response> | A resposta com a LISTA de registros que correspondem aos critérios de busca. |
| <module_name> | O nome do módulo do qual o registro deve ser buscado. Os módulos suportados são: Leads, Negócios, Produtos, Contatos, Campanhas, Fornecedores, Contas, Casos, Cotações, Ordens de venda, Ordens de compra, Faturas e Personalizado. |
| <criteria> | A declaração condicional para a pesquisa. O formato é o seguinte: (
|
| <page> (opcional) | Para obter a lista de registros com base nas páginas. É do tipo de dados NÚMERO. Padrão - 1. |
| <perPage> (opcional) | Usado para obter a lista de registros por página. É do tipo de dados NÚMERO. Padrão - 200. |
| <connections> (opcional) | Exibe os conectores associados à função. O tipo de dados é STRING. |
Entrada de amostra:
resp = zoho.crm.searchRecords("Leads", "(Company:equals:Zillum)");
Nota:
- Pesquisar registros por PDC não está disponível na Versão 2.0.
- Se uma coluna contiver valores nulos, zoho.crm.searchRecords NÃO irá reportá-los em uma <> declaração.
- A qualquer momento, no máximo 200 registros podem ser buscados.
Sintaxe: (usando APIs Versão 1.0)
<response>=zoho.crm._searchRecords(<module_name>, <criteria>, [<from_index>],[<to_index>]);
Obter registros relacionados
Existem vários componentes do CRM que podem ser usados para armazenar informações sobre um determinado lead ou contato. Por exemplo, um lead pode conter uma lista de notas, alguns negócios, chamadas associadas etc. A pesquisa de uma nota relacionada a um registro específico em um módulo pode ser feita usando a tarefa zoho.crm.getRelatedRecords().
Sintaxe: (usando APIs Versão 2.0)
<response>=zoho.crm.getRelatedRecords(<relation_name>, <parent_module_name>, <record_ID>, [<page>],[<perPage>], <connections>);
| Parâmetros | Descrição |
|---|---|
| <response> | A resposta com a LISTA de registros que correspondem aos critérios de busca. |
| <relation_name> | O nome do módulo (também chamado de submódulo) do qual o registro deve ser buscado. É do tipo de dados STRING. Os módulos suportados são: Notas, Cotações, Produtos, Tarefas, Campanhas, Eventos, Chamadas. |
| <parent_module_name> | O nome do módulo ao qual o submódulo pertence. Por exemplo: "Notas pode pertencer a um módulo pai "Leads". É do tipo de dados STRING. Os módulos suportados são: Leads, Negócios, Produtos, Contatos, Campanhas, Fornecedores, Contas, Casos, Cotações, Ordens de venda, Ordens de compra, Faturas e Personalizado. |
| <record_ID> | A ID do registro do módulo pai que precisa ser buscado. É do tipo de dados NÚMERO. |
| <page> (opcional) | Para obter a lista de registros com base nas páginas. É do tipo de dados NÚMERO. Padrão - 1. |
| <perPage> (opcional) | Usado para obter a lista de registros por página. É do tipo de dados NÚMERO. Padrão - 200. |
| <connections> (opcional) | Exibe os conectores associados à função. O tipo de dados é STRING. |
Nota:
- A qualquer momento, no máximo 200 registros podem ser buscados.
Entrada de amostra:
Para buscar Campanhas relacionadas a um Lead:
resp = zoho.crm.getRelatedRecords("Campaigns", "Leads", 2938383000000392001);
Para buscar Tarefas relacionadas a um Lead:
resp = zoho.crm.getRelatedRecords("Task", "Leads", 2938383000000392001);
Sintaxe: (usando APIs Versão 1.0)
<response>=zoho.crm._getRelatedRecords(<module_name>, <parent_module_name>, <record_ID>, [<from_index>],[<to_index>]);
Atualizar registros relacionados
Existem vários componentes do CRM que podem ser usados para armazenar informações sobre um determinado lead ou contato. Você pode atualizar os registros relacionados a um registro pai usando a tarefa zoho.crm.updateRelatedRecord().
Sintaxe: (usando APIs Versão 2.0)
<response>=zoho.crm.updateRelatedRecords(<relation_name>, <record_ID_1>, <parent_module_name>, <record_ID_2>, {<New values as map object>});
| Parâmetros | Descrição |
|---|---|
| <response> | A resposta com a LISTA de registros que correspondem aos critérios de busca. |
| <relation_name> | O nome do módulo (também chamado de submódulo) do qual o registro deve ser buscado. É do tipo de dados STRING. Os módulos suportados são: Notas, Cotações, Produtos, Tarefas, Campanhas, Eventos, Chamadas, E-mails. |
| <record_ID_1> | A ID do registro que precisa ser atualizado. É do tipo de dados NÚMERO. |
| <parent_module_name> | O nome do módulo ao qual o submódulo pertence. Por exemplo: "Notas pode pertencer a um módulo pai "Leads". É do tipo de dados STRING. Os módulos suportados são: Leads, Negócios, Produtos, Contatos, Campanhas, Fornecedores, Contas, Casos, Cotações, Ordens de venda, Ordens de compra, Faturas e Personalizado. |
| <record_ID_2> | A ID do registro do módulo pai que precisa ser buscado. É do tipo de dados NÚMERO. |
| <Novos valores como objeto de MAPA> | Chave. Pares de valor com informações de registro atualizadas. Por exemplo: {"Last_Name": "Updated Name", "Fax": "555-858-3466"} |
Entrada de amostra:
Para atualizar a quantidade do produto:
resp = zoho.crm._updateRelatedRecords("Products",2938383000000392001, "Leads", 2938383000000392001, {"Product_Quantity":"50"});
Sintaxe: (usando APIs Versão 1.0)
<response>=zoho.crm._updateRelatedRecords(<module_name>, <parent_module_name>, <record_ID>, [<from_index>],[<to_index>]);
Converter lead
A próxima etapa após a aquisição do lead seria negociações, onde bons clientes potenciais podem ser convertidos de leads para contatos. Você pode usar a tarefa zoho.crm.convertLead() para obter a transferência das informações do lead como um registro de contato.
Sintaxe: (usando APIs Versão 2.0)
<response>=zoho.crm.convertLead(<record_ID>, <overwrite>, <notify_lead_owner>, <notify_new_entity_owner>, <account_ID>);
| Parâmetros | Descrição |
|---|---|
| <response> | A resposta que retornou como um MAPA. |
| <record_ID> | A ID do registro a ser buscado. É do tipo de dados NÚMERO. |
| <overwrite> | Usado para sobrescrever os dados se o lead já tiver sido convertido. O tipo de dados é BOOLEANO. Deve ser verdadeiro ou falso. |
| <notify_lead_owner> | Usado para enviar uma notificação ao proprietário do lead após a conversão. O tipo de dados é BOOLEANO. Deve ser verdadeiro ou falso. |
| <notify_new_entity_owner> | Usado para enviar uma notificação ao proprietário da nova entidade (contato) após a conversão. O tipo de dados é BOOLEANO. Deve ser verdadeiro ou falso. |
| <account_ID> (opcional) | A ID do registro a ser buscado. É do tipo de dados NÚMERO. |
Entrada de amostra:
resp = zoho.crm.convertLead(7000000037308, { "overwrite": true, "notify_lead_owner": false, "notify_new_entity_owner": true, "Accounts": "7000000037323", "Deals": { "Deal_Name": "Robert", "Closing_Date": "2016-03-30", "Stage": "Closed Won", "Amount": 56.6 } });