Como utilizar na prática

CONTEÚDO

1. Visão Geral

2. Exemplo de utilização

   1. Execute uma requisição com o método POST para fazer login na aplicação

   2. Passe as informações de login da aplicação abaixo, em formato JSON, para o corpo da requisição (body)

   3. Passe no Header o cookie com a informação do JSESSIONID

   4. Encontre os recursos disponíveis da API

   5. Na documentação da API, encontre os parâmetros que devem ser passados no Header da requisição

   6. Informe os dados no corpo da requisição (body) em formato JSON, das informações do cliente que deve ser cadastradas

   7. Liste os clientes com uma requisição GET

01. VISÃO GERAL

Para elucidar o funcionamento da API de Integração, vamos mostrar passo a passo como cadastrar
um cliente, levando em conta um usuário fictício.

02. EXEMPLO DE UTILIZAÇÃO

Para cadastrar um cliente (utilizar a API de Integração na prática), siga estas etapas:

a. Execute uma requisição com o método POST para fazer login na aplicação:

Utilize esta URL: https://totvscrm.app/api/login

b. Passe as informações de login da aplicação abaixo, em formato JSON, para o corpo da requisição (body)

    {
         "username": "[email protected]",

         "password": "minhasenha",

         "tenant": "minhaempresa"
    }

                Você receberá um retorno "200".

Um registro chamado JSESSIONID, com o token da sessão, será retornado no cookie.

c. Passe no Header o cookie com a informação do JSESSIONID

É necessário passar no Cookie para enviar todas as próximas requisições.

d. Encontre os recursos disponíveis da API

Todos os recursos estão disponíveis publicamente para consultas neste endereço.

Vamos utilizar como exemplo o recurso de clientes (customers). Note que, dentro da documentação da API, temos tudo que precisamos (URL, o método HTTP e a extensão da URL):

e. Na documentação da API, encontre os parâmetros que devem ser passados no Header da requisição

Note que os acompanhados por "*", são obrigatórios;

Integration-Action: ação a ser realizada na API de integração. São suportadas as ações:

• create: ação para criação de novo registro no CRM;

• update: ação para atualização parcial do registro presente no CRM;

• upsert: possui dois comportamentos, podendo atuar como atualização ou inserção. O que determina o comportamento é o conteúdo informado no header Integration-Filter. Se o registro informado já existir no CRM, é realizada uma atualização completa do registro presente no CRM, substituindo todo o conteúdo presente no CRM pelo conteúdo enviado na requisição. Se o ID não estiver presente no CRM, é feita uma inserção do conteúdo enviado na requisição;

• delete: ação para remoção do registro presente no CRM. Esta ação estará disponível apenas para algumas entidades do CRM devido às dependências de objetos internos; 

Integration-Service: serviço responsável pela entidade. Por exemplo: customer;

Integration-Resource: recurso para requisição. Por exemplo: customers-integration;

Integration-Version: versão do contrato da API de integração. Deve ser utilizado a versão mais recente disponível de cada API para ter acesso à atributos personalizados. Por exemplo: v1;

Integration-Filter: usado nas ações de update e upsert como identificador do registro a ser atualizado ou quando a consulta realizada for um GET, atua como filtro de registros, sendo suportado o formato RestQuery para a filtragem. Para o exemplo de criação de cliente com a ação create, não é suportado o uso deste header:

Integration-Response: define o nível de resposta. Existem dois níveis de retorno de requisição:

• full: Expõe todo o objeto do CRM que foi inserido ou modificado. A exposição é o retorno de um GET neste registro após as modificações.
• minimum: Expõe apenas a informação do ID do objeto, data de criação e data de atulização do registro recém inserido ou modificado.

Caso não seja informado o header Integration-Response na requisição, o retorno será equivalente ao nível minimum.

f. Informe os dados no corpo da requisição (body) em formato JSON, das informações do cliente que deve ser cadastradas

{
	"active": true,

    "name": "Minha empresa Ltda",

    "tradingName": "Minha empresa e cia",

    "code": "00001"
}

Após executar a requisição, você deverá receber um retorno ‘200’, e será retornado no corpo o ID do cliente cadastrado no CRM.

g. Liste os clientes com uma requisição GET

Caso não tenha realizado a autenticação, repita os passos até o item 3.

Utilize o método GET na mesma URL, como descrito na documentação.

Note que é possível utilizar filtros na requisição da API de Integração. Saiba mais sobre filtros na requisição da API de Integração.

Para listar os clientes, o corpo da requisição (body) deve estar vazio. Ao realizar a requisição, no corpo da resposta será retornado um JSON com as listas de clientes.

Para mais informações sobre outros recursos da API do TOTVS CRM, acesse a documentação da API.

Artigos relacionados:

Introdução

Formato, métodos e retorno das requisições