O SDK Python para APIs Zoho CRM fornece pacote para APIs Zoho CRM. Portanto, a chamada de uma API do Zoho CRM do aplicativo Python cliente é apenas uma chamada de método.

O SDK Python oferece suporte à autenticação de um único usuário e também de vários usuários.

Registro um cliente Zoho

Como as APIs do Zoho CRM são autenticadas com os padrões OAuth2, você deve registrar seu aplicativo cliente com o Zoho. Para registrar seu aplicativo:

1. Visite esta página https://accounts.zoho.com/developerconsole.
2. Clique em "Adicionar ID de Cliente".
3. Insira o Nome do Cliente, o Domínio do Cliente e a URI de Redirecionamento.
4. Selecione o Tipo de Cliente como "Baseado na Web".
5. Clique em "Criar"
6. Seu aplicativo será criado e exibido agora.
7. O ID do Cliente e o Segredo do Cliente podem ser encontrados clicando em Opções → Editar.
   (Opções é o ícone de reticências no canto direito).

Configuração

O SDK Python pode ser instalado por meio de "pip". Pip é uma ferramenta para gerenciamento de dependência em Python. O SDK espera o seguinte do aplicativo cliente

• O aplicativo cliente deve ter Python 2.7 e posteriores.
  • https://www.python.org/downloads/
• O aplicativo cliente deve ter solicitações python sendo instaladas
  • http://docs.python-requests.org/en/master/user/install/
• O SDK Python deve ser instalado por meio de pip.
• O método ZCRMRestClient.initialize() deve ser chamado na inicialização do aplicativo
• MySQL deve estar em execução na mesma máquina que serve na porta padrão 3306.
  • O nome do banco deve ser "zohooauth".
  • Deve haver uma tabela "oauthtokens" com as colunas "identificador de usuário"(varchar(100)), "accesstoken"(varchar(100)), "refreshtoken"(varchar(100)), "expirytime"(bigint).

Se token_persistence_path for fornecido no arquivo oauth_configuration.properties, a persistência ocorrerá apenas no arquivo. Nesse caso, não há nenhuma necessidade de MySQL.

Crie um arquivo vazio com o nome zcrm_oauthtokens.txt no token_persistence_path mencionado.

Instalação do SDK por meio de pip

Instalar Pip (se não instalado)

Consulte o documento a seguir para instalar pip

Instalar SDK

Veja como instalar o SDK Python

• Execute o comando a seguir:

  pip install zcrmsdk

O SDK Python será instalado, e um pacote com o nome "zcrmsdk" será criado no diretório de instalação de python (por exemplo, "/Library/Python/2.7/site-packages").

Atualiza o SDK

• Execute este comando para atualizar o SDK Python para a versão mais recente.

  pip install --upgrade zcrmsdk

Configurações

Os detalhes do Cliente OAuth devem ser fornecidos ao SDK como um arquivo de propriedade. No SDK, incluímos um arquivo de configuração (oauth_configuration.properties). Insira os respectivos valores nesse arquivo. Você pode encontrar esse arquivo em "zcrmsdk/resources".

Preencha os valores para as seguintes chaves sozinhas.

Com base em seu domínio (EU,CN), altere o valor de accounts_url. Valor padrão definido como domínio US.

• client_id, client_secret e redirect_uri são as configurações do cliente OAuth obtidas após registrar o cliente Zoho.
• access_type deve ser definido como offline apenas porque o cliente OAuth não é suportado pelo SDK Python agora.
• token_persistence_path é o caminho para armazenar os tokens OAuth relacionados no arquivo. Se isso estiver definido, não haverá nenhuma necessidade de banco de dados para persistência. A persistência acontece no arquivo somente.

Inclua o caminho absoluto em configuration.properties para a chave "applicationLogFilePath" para armazenar os registros. Você pode encontrar esse arquivo em "zcrmsdk/resources". Esse arquivo deve registrar as exceções durante o uso do SDK Python.

Preencha o valor para a seguinte chave sozinha. Se o caminho do log não for fornecido, os logs não serão armazenados, mas você poderá vê-los no console

Para fazer chamadas de API para a conta de sandbox, altere o valor da seguinte chave para true. Por padrão, o valor é false.

Caso seu aplicativo precise apenas de uma autenticação de usuário único, você precisará definir o usuário do ID de e-mail no arquivo configurations.properties conforme descrito abaixo.

Para trabalhar com a autenticação de vários usuários, você precisa definir o usuário EmailId no encadeamento atual como um atributo.

Você pode usar o acima para autenticação de usuário único também, mas é recomendado prosseguir com a configuração do ID de e-mail no arquivo configuration.properties.

Se você não definir o e-mail do usuário no encadeamento atual, o SDK o esperará do arquivo configuration.properties. Se o e-mail do usuário não estiver definido em nenhum desses dois, o SDK Python lançará uma exceção.

Inicialização

O aplicativo estará pronto para ser inicializado após a definição do arquivo de configuração OAuth.

Geração de concessão autoautorizada e de token de atualização

Para aplicativos de autocliente, o token de concessão autoautorizada deve ser gerado no Zoho Developer Console (https://accounts.zoho.com/developerconsole)

1. Visite https://accounts.zoho.com/developerconsole
2. Clique em Opções → Autocliente do cliente o qual você deseja autorizar.
3. Insira um ou mais escopos válidos do Zoho CRM (separados por vírgula) que deseja autorizar no campo "Escopo" e escolha a hora de expiração. Forneça o escopo "aaaserver.profile.READ" em conjunto com os escopos do Zoho CRM.
4. Copie o token de concessão para backup.
5. Gere refresh_token a partir do token de concessão criando uma solicitação POST com o URL abaixo

   https://accounts.zoho.com/oauth/v2/token?code={grant_token}&redirect_uri={redirect_uri}&client_id={client_id}&client_secret={client_secret}&grant_type=authorization_code

6. Copie o token de atualização para backup.

Observe que o token de concessão gerado é válido apenas pelo tempo estipulado durante a geração. Portanto, os tokens de acesso e de atualização devem ser gerados durante esse período.

Geração de token de acesso

O token de acesso pode ser gerado pelo token de concessão ou token de atualização. Qualquer um dos dois métodos a seguir é suficiente.

Geração de tokens de acesso a partir do token de concessão

O seguinte trecho de código deve ser executado a partir da classe principal para se obter o token de acesso.

Cole o token de concessão gerado no literal da string mencionada. Este é um processo único.

Geração de tokens de acesso a partir do token de atualização

O seguinte trecho de código deve ser executado a partir da classe principal para se obter o token de acesso.

Cole o token de atualização gerado no literal da string mencionada. Este é um processo único.

Após a execução bem-sucedida do trecho de código acima, os tokens de acesso e de atualização gerados persistirão de acordo com a classe do manipulador de persistência.

Uma vez que os tokens OAuth persistiram, chamadas de API subsequentes usarão os tokens de acesso e de atualização persistentes. O SDK Python cuidará da atualização do token de acesso usando o token de atualização como e quando necessário.

Inicialização de aplicativo

O SDK Python exigirá a seguinte linha de código chamada sempre que o aplicativo cliente for iniciado.

Quando o SDK tiver sido inicializado pela linha acima, você poderá usar quaisquer APIs do SDK para obter resultados adequados.

Uso do SDK

Adicione a linha abaixo aos arquivos Python do aplicativo cliente onde você gostaria de usar o SDK Python.

Com isso, você pode acessar todas as funcionalidades do SDK Python.

Hierarquia de classes

Todas as entidades do Zoho CRM são modeladas como módulos tendo classes, métodos e variáveis de instância aplicáveis a essa entidade específica. ZCRMRestClient é a classe básica do SDK Python. ZCRMRestClient tem métodos para obter instâncias de várias outras entidades do Zoho CRM. Ela está no módulo RestClient.

As relações de classe e a hierarquia do SDK segue a hierarquia da entidade dentro do Zoho CRM. A hierarquia de classe de várias entidades do Zoho CRM é mostrada abaixo:

Conforme aparece na hierarquia, cada classe de entidade terá variáveis de instância para buscar suas próprias propriedades e buscar dados de suas entidades filhas imediatas por uma chamada da API.

Por exemplo: um módulo do objeto do Zoho CRM (ZCRMModule) terá variáveis de instância para obter propriedades de um módulo como nome de exibição, ID de módulo etc. E também terá variáveis de instância para buscar todos os objetos filhos (como ZCRMLayout).

Instanciar objeto

Nem sempre é eficaz seguir a hierarquia de classe completa desde o topo para buscar dados de uma entidade em algum nível inferior, pois isso pode envolver chamadas de API em cada nível. Para lidar com isso, cada classe de entidade terá um método get_instance() para obter seu próprio objeto fictício e variáveis de instância para obter os objetos fictícios de suas entidades filhas.

Observe que o método get_instance() não tem nenhuma de suas propriedades preenchidas, pois não dispara uma chamada de API. Isso retorna apenas um objeto fictício que deve ser usado somente para acessar os métodos não estáticos da classe.

Resumindo,

• ZCRMRestClient.get_module("Contatos") deve retornar o módulo Contatos real, que tem todas as propriedades do módulo Contatos preenchidas por uma chamada de API
• ZCRMRestClient.get_module_instance("Contatos") retornará um objeto ZCRMModule fictício que se refere ao módulo Contatos, não preenchido com propriedades, pois isso não faz uma chamada de API.

Portanto, para obter registros de um módulo, você não precisa iniciar desde o ZCRMRestClient. Em vez disso, você pode obter uma instância com ZCRMModule.get_instance() e depois chamar seu método não estático get_records() pela instância criada. Isso evitaria a chamada de API, que teria sido acionada para preencher o objeto ZCRMModule.

Acesso a propriedades do registro

Como as propriedades do registro são dinâmicas entre os módulos, temos apenas os campos comuns (como created_time, created_by, proprietário etc.) como propriedades padrão do ZCRMRecord. Todas as outras propriedades de registro estão disponíveis como um dicionário no objeto ZCRMRecord.

Para acessar os valores de campo individuais de um registro, use os métodos getter e setter disponíveis. As chaves do dicionário de propriedades de registro são nomes de API dos campos do módulo. Os nomes de API de todos os módulos estão disponíveis em Configuração → Extensões & APIs → APIs → API do CRM → Nomes de API.

Para obter um valor de campo, use record.get_field_value(field_api_name). Para definir um valor de campo, use record.set_field_value(field_api_name,new_value). Ao definir um valor de campo, verifique se o valor definido tem o mesmo tipo de dados do campo ao qual ele será definido.

Manipulação da resposta

APIResponse e BulkAPIResponse são objetos no pacote para respostas dos APIs do Zoho CRM. Todos os métodos que chamam API devem retornar um desses dois objetos.

DownloadFile e downloadPhoto retorna FileAPIResponse em vez de APIResponse.

Um método que busca uma única entidade deve retornar o objeto APIResponse, enquanto uma lista de buscas de métodos deve retornar o objeto BulkAPIResponse.

Use a variável de instância "data" para obter os dados da entidade sozinhos pelos objetos no pacote de resposta. APIResponse.data retornará um único objeto de entidade do Zoho CRM, enquanto BulkAPIResponse.data retornará uma lista de objetos de entidade do Zoho CRM.

Além de dados, esses objetos em pacote de resposta têm as seguintes propriedades:

1. response_headers – contagem de API restantes para o dia/janela presente e tempo passado para a redefinição da janela presente.
2. info – quaisquer outras informações, se fornecidas pela API, além dos dados reais.
3. bulk_entity_response (lista de instâncias EntityResponse) – status de entidades individuais em uma API de lote. Por exemplo, nos registros de uma entrada, a API pode falhar parcialmente devido a alguns registros. Esse array fornece o status de criação de registros individuais.

Exceções

Todos os comportamentos inesperados, como falhas em respostas da API e anomalias do SDK, são manipulados pelo SDK Python e lançados como uma única exceção – ZCRMException. Portanto, basta capturar essa exceção sozinha no código de aplicativo do cliente.

As classes e suas variáveis de instância