Serviço de callback para API de tarefas
Pensando em lembrar de funcionalidades importantes no sistema e que facilitam a gestão das informações, neste artigo veremos sobre o serviço de callback, que serve para notificar automaticamente um histórico recebido na retaguarda para outro sistema. Isso torna o processo mais ágil, sem a necessidade de fazer requisições de API para consultar se a informação já chegou ou ainda está sendo processada.
Atualmente há duas formas distintas de callback, sendo elas:
. Callback no formato XML;
. Callback no formato JSON.
Qual vem a ser a principal diferença entre estas duas formas de callback?
Enquanto o callback no formato xml necessita da criação de um campo customizável na entidade tarefa que receberá a url de destino e que será disparada a cada tarefa criada e executada que contenha a url disponível no campo, o callback no formato json é totalmente transparente ao center e se configura a cada atividade. Todavia, ambas funcionam baseadas nos mesmos princípios e devem ser solicitadas ao nosso time de Help Desk para que sejam configuradas.
Como configurar e pedir ao time de Help Desk a ativação do serviço de callback?
. XML
Para que funcione adequadamente, deve ser criado um campo customizável alfanumérico na tarefa. Esse campo deve possuir o valor “callback” no identificador alternativo. Dessa forma, ao criar uma tarefa, deve ser informado nesse campo (callback) a URL do seu sistema que irá receber os dados do histórico que estão no uMov.me, conforme exemplo mostrado abaixo:
Após executar as ações citadas acima, entre em contato com nosso time de Help Desk solicitando ativação do callback xml informando qual o ambiente.
. JSON
Para ativar o callback json no ambiente, você precisará fornecer as seguintes informações ao time de Help Desk no momento de solicitação:
. URL (em https);
. Autenticação (opcional);
. Atividade (descrição);
. Ambiente (descrição).
Verificando as notificações de callback
Quando um histórico da tarefa for recebido na retaguarda, com o processo de callback ativo será disparado uma notificação para esta URL informando que há dados na retaguarda a serem processados.
Para acesso ao histórico deve ser feito uma requisição via API solicitando as informações dos históricos recebidos na retaguarda, sendo que a callback envia informações que ajudam na identificação do que deve ser requisitado. Para ver mais sobre requisições de histórico de execução de tarefas, visite o link: https://ajuda.umov.me/kb/article/120334/activityhistory-historico-de-execucao-de-atividades?ticketId=&q= .
O retorno que receberemos será conforme o exemplo listado abaixo:
. XML
<Schedule>
<alternativeIdentifier>ALTERNATIVE TAREFA</alternativeIdentifier>
<activityHistories>
<activityHistory id="ID HISTORICO" />
</activityHistories>
</Schedule>
OBS: Você utiliza este id para buscar execuções pelo activityHistory ou activityHistoryHierarchical
. JSON
{
"historyId": "XXX",
"taskId": "XXXX",
"clientId": "XXX",
"activityId": "XXX"
}
OBS2: O Exemplo do callback JSON, listado acima, é informando todos os campos na automação. A automação irá enviar a tag conforme o preenchimento na tela de automação.
Importante: o sistema somente irá considerar os históricos recebidos após a data e hora de ativação do recurso de callback e para tarefas que possuem uma URL de callback válida. Além disso, ao disparar a requisição do callback, o sistema marca o histórico como já integrado. Dessa forma, a chamada da API de callback é executada uma única vez por histórico. Somente é executada novamente, caso ocorra algum erro na chamada da URL.
Importante: é possível configurar para que o serviço seja disparado somente quando todas as informações da tarefa estiverem disponíveis. Ou seja, caso a execução contenha fotos, a callback só será executada quando todas as fotos estiverem disponíveis. Isso ocorre pois o tempo de sincronismo dos dados e fotos é diferente, porque fotos possuem tamanho maior e demoram mais tempo para finalizar o sincronismo que os dados. Para isso, solicite ao time de Help Desk a configuração de envio após recebimento de todas as fotos ou não. Por padrão, quando realizada a configuração, o callback é enviado quando recebemos os dados da execução, não é esperado as fotos.
Para maiores informações com exemplos de autenticações, acesse o seguinte link: