SDK PHP para Zoho CRM

SDK PHP é um pacote para APIs do Zoho CRM. Portanto, a chamada de uma API do Zoho CRM do aplicativo PHP cliente é apenas uma chamada de função. Ele 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 PHP pode ser instalado por meio de "composer". Composer é uma ferramenta para gerenciamento de dependência em PHP. O SDK espera o seguinte do aplicativo cliente.

• O aplicativo cliente deve ter PHP 5.6 ou posterior com a extensão curlativada.
• O SDK PHP deve ser instalado no aplicativo cliente por meio do Composer.
• A função ZCRMRestClient::initialize() deve ser chamada 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 "useridentifier"(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 PHP por meio do Composer

Instalar o Composer (se não estiver instalado)

Executar este comando para instalar o Composer

Para tornar o Composer acessível globalmente, siga as instruções no link abaixo

Instalar PHP SDK

Veja como você instalar o SDK

1. Navegue até o espaço de trabalho do aplicativo cliente
2. Execute o comando a seguir:

   composer require zohocrm/php-sdk

3. Portanto, o SDK PHP será instalado, e um pacote chamado "vendor" será criado na área de trabalho do aplicativo cliente.

Configurações

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

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

• Somente as chaves exibidas acima devem ser preenchidas.
• 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 PHP agora.
• persistence_handler_class é a implementação do ZohoOAuthPersistenceInterface, isto é, ZohoOAuthPersistenceHandler.
• 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.

Crie um arquivo denominado "ZCRMClientLibrary.log" na máquina do aplicativo cliente e mencione o caminho absoluto do arquivo criado em configuration.properties para a chave "applicationLogFilePath". Você pode encontrar esse arquivo em "vendor/zohocrm/php-sdk/src/resources". Esse arquivo deve registrar as exceções ocorridas durante o uso do SDK PHP.

Preencha somente a seguinte chave

Para fazer chamadas de API para a conta de sandbox, altere o valor da seguinte chave para true no arquivo configurations.properties . 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 EmailId 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 na super variável global "$_SERVER" conforme determinado abaixo:

Você pode usar a variável $_SERVER para autenticação de usuário único, 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 como uma variável global super, 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 PHP 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 uma 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 um 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 do token 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 os tokens de acesso e atualização. Cole o token de concessão copiado no literal da string mencionada abaixo. Este é um processo único.

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 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.

Geração do token 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 os tokens de acesso e atualização. Cole o token de atualização gerado no literal da string mencionada abaixo. Este é um processo único.

Após a execução bem-sucedida do trecho de código acima, o token de acesso gerado e o token de atualização fornecido 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 PHP 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 PHP exigirá a seguinte linha de código chamada sempre que o aplicativo cliente for iniciado.

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

Uso do SDK PHP

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

Por meio dessa linha, você pode acessar todas as funcionalidades do SDK PHP.

Hierarquia de classes

Todas as entidades do Zoho CRM são modeladas como classes tendo propriedades e funções aplicáveis a essa entidade específica. ZCRMRestClient é a classe básica do SDK PHP. ZCRMRestClient tem funções 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:

ZCRMRestClient
     -ZCRMOrganization
          -ZCRMUser
               -ZCRMUserTheme
               -ZCRMUserCustomizeInfo
         -ZCRMRole
         -ZCRMProfile
              -ZCRMPermission
              -ZCRMProfileSection
                   -ZCRMProfileCategory
        -ZCRMModule
             -ZCRMLayout
                  -ZCRMSection
                       -ZCRMField
                       -ZCRMPickListValue
                       -ZCRMLookupField
                  -ZCRMLeadConvertMapping
                       -ZCRMLeadConvertMappingField
             -ZCRMCustomView
                  -ZCRMCustomViewCategory
                  -ZCRMCustomViewCriteria
             -ZCRMRelatedListProperties
                  -ZCRMModuleRelatedList
             -ZCRMRecord
             -ZCRMNote
             -ZCRMAttachment
             -ZCRMInventoryLineItem
                  -ZCRMTax
             -ZCRMEventParticipant
             -ZCRMPriceBookPricing
             -ZCRMModuleRelation
             -ZCRMJunctionRecord
             -ZCRMTrashRecord

Cada classe de entidade 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á uma função getInstance() para obter seu próprio objeto fictício e funções para obter os objetos fictícios de suas entidades filhas.

Observe que a função getInstance() 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 funções não estáticas 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, não é preciso iniciar usando ZCRMRestClient. Em vez disso, você pode obter uma instância ZCRMModule com ZCRMModule::getInstance() e chamar sua função não estática getRecords() 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 módulos, somente campos como createdTime, createBy, proprietário etc., são fornecidos como propriedades 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 as funções 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 campos 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 obter um valor de campo, use $record → setFieldValue($fieldAPIName, $newValue);
  Ao definir um valor de campo, verifique se o valor definido tem o mesmo tipo de dados do campo para o qual ele será definido.

Manipulação da resposta

APIResponse e BulkAPIResponse são objetos do pacote para respostas das APIs do Zoho CRM. Todos as API que chamam funções devem retornar um desses dois objetos.

• DownloadFile e downloadPhoto retorna FileAPIResponse em vez de APIResponse.
• Uma função que busca uma entidade única retornará um APIResponse, e uma função que busca uma lista de entidades retornará um objeto BulkAPIResponse.
• Use a função getData() para obter os dados da entidade sozinhos dos objetos do pacote de resposta. APIResponse → getData() retornará um único objeto de entidade do Zoho CRM, enquanto BulkAPIResponse → getData() 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. Array de EntityResponse(s) – 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 PHP, 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.