Histórico da Página

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/login?redirectUrl=/

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 no Git Lab, nesta url: https://gitlab.wssim.com.br/docs/api/-/tree/master/integration

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;

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 da API de integração. 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:

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.

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, não é necessário enviar o corpo da requisição (body). Ao realizar a requisição, no corpo da resposta será retornado um JSON com as lista de clientes.

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

Artigos relacionados:

Introdução

Como realizar solicitações