Histórico da Página

...

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?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"
    }

...

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/integrationpublicamente 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:

...

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

...

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) deve estar vazio. Ao realizar a requisição, no corpo da resposta será retornado um JSON com as lista listas 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çãoComo realizar solicitações

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