Funcionamento do callback

Ao cadastrar um serviço no Avisa BR, é possível adicionar uma URL (Uniform Resource Locator - endereço virtual) de callback para os envios de e-mail. Essa URL é uma URL da aplicação que utiliza o Avisa BR para envio de mensagens.

A URL especificada pelo cliente pode ser qualquer uma no domínio dos sistemas do cliente, desde que seja capaz de receber a requisição REST (Representational State Transfer - protocolo de definição de serviços) com o POST (verbo HTTP - Hypertext Transfer Protocol - protocolo da internet) com o conteúdo JSON (JavaScript Object Notation - texto baseado em Javascript) especificado e tratar.

Por exemplo, a URL poderia ser:

https://www.minhaprefeitura.meuestado.gov.br/integracoes/avisa/mensagem/visualizacao

O exemplo é meramente ilustrativo, e o cliente tem total liberdade para adotar o padrão que deseje na definição do endereço HTTPS (Hypertext Transfer Protocol Secure) da URL.

Peça apoio a uma pessoa da área técnica de desenvolvimento de sistemas da sua instituição para definição da URL de callback, uma vez que o cadastro dela depende de uma implementação prévia de um web service REST para recebimento das requisições originadas do Avisa BR. A definição da URL de callback não é meramente um cadastro, envolve o trabalho prévio de implementação e testes do web service pela área de desenvolvimento de sistemas do cliente. O Serviço pode ser cadastrado no Avisa BR sem URL de callback, e alterado posteriormente para inclusão da URL quando o trabalho de implementação e testes estiver concluído.

Para acompanhamento dos envios realizados pela plataforma não é necessária a definição de uma URL de callback. Se você não sabe se precisa de uma URL de callback, provavelmente você não precisa de uma.

No cadastro de template de e-mail no formato HTML para o serviço com uma URL de callback cadastrada, é possível indicar que o template inclui confirmação de visualização de mensagem. Deve-se subentender que a visualização de mensagem não significa que o receptor a leu.

Após uma mensagem de e-mail ser visualizada pelo destinatário, o Avisa BR envia uma requisição POST (retorno de confirmação) para o endereço URL, cadastrada no serviço. Essa requisição POST possui um conteúdo JSON, com os dados de identificação da mensagem, data/hora de envio e data/hora de visualização, conforme o exemplo a seguir:

Exemplo de conteúdo do POST do callback

{
"idMensagem":"edc42d85-1cb0-4913-bfe1-8e98299e63ae",
"dataHoraCriacao":"19/12/2022 18:08:31",
"dataHoraVisualizacao":"19/12/2022 18:08:57"
}