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

Faça o download do arquivo SDK para começar em seu projeto.

• SDK com dependências
• SDK sem dependências

Os JARs de dependência são:

• hamcrest-all-1.3
• httpclient-4.4.1
• httpcore-4.4.4
• httpmime-4.5.3
• json-20170516
• servlet-api-2.5
• commons-logging-1.1.3
• ZohoOAuthClient

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 Java está disponível como um arquivo JAR. O SDK espera o seguinte do aplicativo cliente.

• O aplicativo cliente deve ser executado pelo menos em Java 7.
• O arquivo jar e os arquivos de configuração necessários devem ser adicionados como um SDK para o projeto de cliente e estar disponíveis no caminho de classe durante a compilação e a execução.
• Durante a inicialização do seu aplicativo, o método ZCRMRestClient.initialize(); deverá ser chamado e invocado com êxito sem nenhuma exceção.

Configurações

Os detalhes do Cliente OAuth devem ser fornecidos ao SDK como um arquivo de propriedade. Crie um arquivo oauth_configuration.properties e coloque-o na pasta "resources", assegurando que "resources/oauth_configuration.properties" esteja disponível no caminho da classe.

O arquivo deve estar no formato a seguir com as seguintes propriedades & seus respectivos valores.

• client_id, client_secret e redirect_uri são as configurações do cliente OAuth obtidas após registrar o cliente Zoho.
• Escopo pode ser um ou vários escopos do Zoho CRM válidos (separados por vírgula). Adicione o escopo Aaaserver.profile.Read aos seus escopos fornecidos. É obrigatório.
• access_type deve ser definido como offline ou online.
• persistence_handler_class é a implementação da interface ZohoPersistenceHandler, que tem métodos de manipulação para armazenar dados OAuth. Exemplo: persistence_handler_class=com.zoho.oauth.clientapp.ZohoOAuthFilePersistence (ou) com.zoho.oauth.clientapp.ZohoOAuthDBPersistence (ou) sua própria classe de manipulador de persistência.
• Se você preferir usar nossa persistência, precisará fornecer as chaves mysql_username e mysql_password para conectividade mysql. Por padrão, mysql_username = "root" e mysql_password = "".

Além das configurações de OAuth acima, o SDK também fornece opções para substituir determinados atributos de solicitação de HTTP. Essas configurações devem ser fornecidas em um arquivo chamado zcrm_configuration.properties, que também deve ser colocado sob a pasta "resources".

A seguir, as configurações suportadas no arquivo zcrm_configuration.properties.

• O valor
• timeOut representa o tempo limite da solicitação em segundos. Deixe o tempo limite em branco se não for necessário.
• O valor
• userAgent fornece um nome opcional para identificação do seu cliente.
• O valor
• minLogLevel representa o nível de registro mínimo para impressões do registrador do SDK. Os valores suportados são: TODOS, TRAÇO, DEPURAÇÃO, INFORMAÇÕES, AVISO, ERRO e DESLIGADO. O nível de registro mínimo padrão é AVISO.
• Se você estiver atendendo a vários usuários, para que o SDK identifique o usuário específico que faz a solicitação, o endereço de e-mail do solicitante deverá ser definido pelo seguinte trecho de código antes de fazer a chamada do método real do SDK.
  ZCRMRestClient.setCurrentUser(currentUserEmailId);
• Em caso de outro usuário único, você pode definir o ID de e-mail do usuário em ZCRMRestClient (como acima) para cada solicitação ou fornecer o ID de e-mail do usuário no arquivo zcrm_configuration.properties com a chave currentUserEmail como uma configuração única.
• accessType (opcional) - tipo de ambiente no CRM
  • Produção - ambiente que tem usuários de pagamento ativo acessando dados de negócios críticos.
  • Desenvolvimento - ambientes onde é possível estender, integrar e desenvolver sem afetar os ambientes de produção.
  • Sandbox - ambientes especificamente usados para testar a funcionalidade do aplicativo antes de implantar a produção ou liberação para clientes.
• domainSuffix (opcional) - Suporte Multi DC.
  • us - www.zohoapis.com
  • ue - www.zohoapis.eu
  • cn - www.zohoapis.com.cn

Persistência OAuth

Após o aplicativo ser autorizado pelo usuário, os tokens de acesso e de atualização OAuth poderão ser usados para subsequentes solicitações de dados do usuário para o Zoho CRM. Portanto, eles precisam de persistência com o aplicativo cliente. 

Para facilitar isso, você deverá escrever uma implementação da interface ZohoPersistenceHandler incorporada, a qual tem os seguintes métodos de retorno. 

• saveOAuthData (tokens ZohoOAuthTokens) – chamado ao buscar tokens de acesso e de atualização da Zoho. 
• deleteOAuthTokens() – chamado antes de salvar os tokens recebidos recentemente. 
• getOAuthTokens() – chamado antes de disparar uma solicitação para buscar os tokens salvos. Esse método deve retornar o objeto ZohoOAuthTokens à biblioteca para processá-lo. 

O nome do pacote (com seu pacote) desta classe de implementação deve ser fornecido como peristence_handler_class em oauth_configuration.properties. Duas implementações do ZohoPersistenceHandler ficam prontamente disponíveis com a biblioteca do cliente. 

Você pode usar imediatamente qualquer uma das duas implementações de amostra fornecidas com a biblioteca – ZohoOAuthFilePersistence ou ZohoOAuthDBPersistence. 

ZohoOAuthDBPersistence usa um banco de dados MySQL persistence. Para usá-lo, assegure-se do seguinte.  

• MySQL deve estar em execução na mesma máquina que serve na porta padrão 3306. 
• O nome do banco de dados deve ser "zohooauth". 
• Deve haver uma tabela "oauthtokens" com as colunas "useridentifier" (varchar), "accesstoken" (varchar), "refreshtoken" (varchar) e "expirytime" (bigint).  

ZohoOAuthFilePersistence usa um arquivo local para gravar e ler os dados dos tokens OAuth. O caminho completo do arquivo que deve ser usado pela biblioteca para gravar e ler os dados dos tokens devem ser especificados no arquivo oauth_configuration.properties como o valor da propriedade "toauth_tokens_file_path". (por exemplo,  oauth_tokens_file_path=/user-path/src/resources/oauthtokens.properties). 

Inicialização

O aplicativo está pronto para ser inicializado depois de definir o arquivo de configuração OAuth e a classe do manipulador de persistência OAuth para seu aplicativo.

Geração de tokens de concessão

Para um único usuário:

O console do desenvolvedor tem uma opção para gerar token de concessão para um usuário diretamente. Essa opção pode ser útil quando o aplicativo deve usar apenas as credenciais de um único usuário do CRM para todas as suas operações ou para seus testes de desenvolvimento.

1. Faça login na conta de usuário.
2. Visite https://accounts.zoho.com/developerconsole.
3. Clique na opção Opções → Autocliente do cliente ao qual deseja autorizar.
4. 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.
5. Copie o token de concessão exibido na tela.

Para vários usuários:

Para vários usuários, é uma responsabilidade do aplicativo cliente gerar o token de concessão dos usuários quem tentam fazer login. A IU do aplicativo deve ter uma opção "Login com Zoho" para abrir o URL do token de concessão da Zoho, o qual solicitará as credenciais de login do usuário na Zoho.

Após o login bem-sucedido do usuário, o token de concessão será enviado como um parâmetro para o URL de redirecionamento registrado.

Geração de tokens de acesso e de atualização

Após a obtenção do token de concessão, o seguinte trecho de código deverá ser executado a partir da classe principal para se obter os tokens de acesso e atualização. Cole o token de concessão copiado no literal da string mencionada.

Observe que o trecho de código acima é válido apenas uma vez por token de concessão. Após a execução bem-sucedida, 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 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 requer que a seguinte linha de código seja chamada sempre que o aplicativo for iniciado.

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

Hierarquia de classes

Todas as entidades do Zoho CRM são modeladas como classes com membros e métodos aplicáveis a essa entidade específica. ZCRMRestClient é a classe básica do SDK. ZCRMRestClient tem métodos para obter instâncias de várias outras entidades do Zoho CRM.

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:

Cada entidade de classe tem funções para buscar suas próprias propriedades e buscar dados de suas entidades-filho imediatas por uma chamada da API.

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

Objeto da instância

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 um dos níveis. Para lidar com isso, cada classe de entidade terá um método getInstance() para obter seu próprio objeto fictício e métodos para obter os objetos fictícios de suas entidades filhas.

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

Resumindo,

• ZCRMRestClient.getModule("Contatos") deve retornar o módulo Contatos real, que tem todas as propriedades do módulo Contatos preenchidas por uma chamada de API.
• ZCRMRestClient.getModuleInstance("Contatos") deve retornar um objeto ZCRMModule fictício que faria referência ao módulo Contatos sem qualquer propriedade preenchida, pois 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 ZCRMModule com ZCRMModule.getInstance() e chamar seu método não estático getRecords() pela instância criada. Isso evitaria a chamada de API, que, de outro modo, 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 createdTime, createdBy, proprietário etc.) como membros padrão do ZCRMRecord. Todas as outras propriedades de registro estão disponíveis como um mapa 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 mapa 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 → Marketplace → APIs → API do CRM → Nomes de API.

• Para obter um valor de campo, use record.getFieldValue(fieldAPIName);
• Para definir um valor de campo, use record.setFieldValue(fieldAPIName, newValue);
  Ao definir um valor de campo, verifique se o valor definido é do tipo de dados apt 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.

• Uma entidade de busca de método deve retornar o objeto APIResponse, enquanto uma lista de buscas de métodos deve retornar o objeto BulkAPIResponse.
• Use o método getData() para obter os dados da entidade sozinhos dos objetos do pacote de resposta. APIResponse.getData() deve retornar um único objeto de entidade do Zoho CRM, enquanto BulkAPIResponse.getData() deve 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. ResponseHeaders – contagem de API restantes para o dia/janela presente e tempo passado para a redefinição da janela presente.
2. ResponseInfo – quaisquer outras informações, se fornecidas pela API, além dos dados reais.
3. Lista<EntityResponse> - status de entidades individuais em uma API de lote. Por exemplo: uma API de registros de inserção 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 e passados como uma única exceção – ZCRMException. Portanto, basta capturar essa exceção sozinha no código de aplicativo do cliente.