Tempo aproximado para leitura: 00:02:30 min
Dúvida
Como utilizar a API de Integração na prática?
Ambiente
Cross Segmentos - TOTVS CRM Gestão de Clientes - API de Integração - Versão App3
Solução
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, seguindo estas etapas:
1. Execute uma requisição com o método POST para fazer login na aplicação.
1.1. Utilize uma das URL's a seguir segundo a versão do seu CRM Gestão de Clientes:
- Versão APP3: https://totvscrm.app/api/login
2. Passe as informações de login da aplicação abaixo, em formato JSON, para o corpo da requisição (body):
{
"username": "usuario@dominio.com.br",
"password": "minhasenha",
"tenant": "minhaempresa"
}
2.1. Você receberá um retorno 200;
2.2. Lembrando que as requisições efetuadas no método POST só funcionam com o usuário com o perfil de acesso Admin pois somente este perfil tem as liberações para editar dados:
2.3. Caso o registro seja enviado com um usuário com um perfil diferente será retornado a informação status 403 Forbiden independente do jSON estar correto ou não;
2.4. Caso o tópico 2.2. e 2.3. estejam corretos, será retornado um registro chamado JSESSIONID, com o token da sessão, será retornado no cookie.
3. Passe no Header, o cookie com a informação do JSESSIONID:
Importante!
É necessário passar no Cookie para enviar todas as próximas requisições.
4. Encontre os recursos disponíveis da API. Todos os recursos estão disponíveis no Git Lab.
Atenção!
Para saber qual versão do recurso está sendo acessado, é necessário verificar a URL, conforme a imagem abaixo:
Cada recurso estará com a URL da sua versão correspondente. URL da imagen, APP3.
4.2. Vamos utilizar como exemplo o recurso de clientes (Customers).
4.3. Note que, dentro da documentação da API, temos tudo que precisamos (URL, o método HTTP e a extensão da URL):
5. Na documentação da API, encontre os parâmetros que devem ser passados no Header da requisição:
5.1. Observe que os campos acompanhados por * (asterisco), são obrigatórios.
5.2. Integration-Action
Ação a ser realizada na API de integração. São suportadas as seguintes 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;
5.3. Integration-Service
Serviço responsável pela entidade. Como o Customer.
5.4. Integration-Resource
Recurso para requisição. Como o customers-integration.
5.5. Integration-Version
Versão da API de integração. Por exemplo: v1.
5.6. 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 um cliente com a ação create, não é suportado o uso deste header:
6. 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"
}
6.1. Após executar a requisição, você deverá receber um retorno 200, e será retornado no corpo o ID do cliente cadastrado.
7. Liste os clientes com uma requisição GET.
7.1. Caso não tenha realizado a autenticação, repita os passos até o item 3.
7.2. Utilize o método GET na mesma URL, como descrito na documentação:
7.3. Note que é possível utilizar filtros na requisição da API de Integração. Saiba como utilizar filtros na requisição da API de Integração.
7.4. 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:
7.5. Para mais informações sobre outros recursos da API do TOTVS CRM Gestão de Clientes, acesse a documentação da API no Git Lab.
Artigos relacionados:
0 Comentários