User Tools

Site Tools


br-111-communication


Processo de comunicação

Canais de informações e dispositivos móveis comunicam-se com o webservice de forma assíncrona, por meio de POST.

No caso dos canais de informações, estes também recebem informações do webservice por meio de POST quando o usuário envia uma mensagem para a aplicação a partir de seu dispositivo móvel. Esse tipo de solicitação será detalhada mais adiante (tópico POST de mensagens dos usuários).



POST de solicitação ao webservice

No caso de solicitações de canais de informações e dispositivos móveis ao webservice, o POST inclui 3 variáveis:

  • id: Contém a identificação do requisitante, podendo ser o código de um canal (Channel-ID), código de um dispositivo móvel (Device-ID) ou código de uma interface (Interface-ID), sendo este último para as requisições de registro de novos dispositivos;

  • key: Contém a chave AES temporária criptografada com a chave pública do solicitante e codificada em Base64;

  • frame: Contém o XML de solicitação do requisitante, criptografado com a chave temporária AES e codificado em Base64. O conteúdo desse XML depende do tipo de solicitação que está sendo encaminhada (comando e parâmetros).



XML de solicitação

O conteúdo do XML de solicitação, criptografado e codificado em base64 na variável frame inserida no POST, varia em função do tipo de solicitação que está sendo encaminhada ao webservice.

Dentro do XML de solicitação, duas variáveis (tags) são comuns a todas as solicitações, exceto para registro de novos dispositivos. São elas:

  • cmd: Contém o comando a ser executado pelo webservice;
  • seq: Contém o número de sequência da solicitação.

Os comandos disponíveis para os canais de informações são: smsg e chck. Para os dispositivos móveis, além da solicitação de registro de novos dispositivos, os comandos disponíveis são: ureg, lsub, lkup, icon, schn, uchn, chck, dmsg e resp.

No caso dos dispositivos móveis, a variável stp (stamp da interface), também é comum a todas as solicitações, inclusive para registro de novos dispositivos.

As demais variáveis (tags), variam de acordo com o comando solicitado e correspondem aos parâmetros necessários à sua execução.

A variável seq (sequência da solicitação), corresponde a um número inteiro iniciado em 1 a partir da criação de canal de informações ou após o registro do dispositivo. Depois da solicitação com sequência N, a próxima solicitação deve obrigatoriamente possuir a sequência N + 1.

Os comandos enviados com erro de sequência não são executados pelo webservice, e o código de erro correspondente é retornado para o solicitante (código 6101 para os canais de informações e 7101 para os dispositivos móveis).

As solicitações de registro de novos dispositivos não recebem os erros 7101, pois nesse processo a sequência ainda está sendo criada.



XML de resposta do POST

Em resposta a um POST, o webservice retorna o XML de resposta do POST, que não se confunde com o XML de resposta da solicitação, como descrito a seguir. O XML de resposta do POST inclui 3 variáveis (tags):

<?xml version="1.0" encoding="utf-8"?>
<followzup>
<retcode>código-de-retorno</retcode>
<retframe>xml-de-resposta-da-solicitação</retframe>
<retmd5>md5-de-resposta</retmd5>
</followzup>

Onde:

  • retcode: Código de retorno do comando solicitado representado por 4 dígitos numéricos ou “0” (zero) para as solicitações executadas com sucesso;
  • retframe: Contém o XML de resposta da solicitação, criptografado com a chave temporária AES e codificado em Base64. O conteúdo do XML de resposta da solicitação depende do comando que foi solicitado e a chave AES utilizada em sua criptografia é a mesma utilizada no envio do XML de solicitação;
  • retmd5: Contém o hash MD5 da variável retframe, para que esta possa ser validada pelo requisitante.



XML de resposta da solicitação

Após decriptografada a variável retframe contida no XML de resposta do POST, obtemos o XML de resposta da solicitação, cujo conteúdo depende do tipo de comando solicitado ao webservice. Para obter detalhes do XML de resposta da solicitação, consulte a documentação do comando respectivo.


XML de resposta da solicitação (sequência inválida):

No caso de sequência inválida (código de erro 6101 ou 7101), o sequinte XML de resposta da solicitação é retornado para o solicitante:

<?xml version="1.0" encoding="utf-8"?>
<followzup>
<seq>Last-sequence</seq>
</followzup>

Onde:

  • Last-sequence: Número de sequência utilizado na última solicitação.

Ao receber um erro de sequência (6101 ou 7101), o solicitante deve pegar o valor da última sequência (Last-sequence), somar 1 e re-enviar a solicitação ao webservice.



POST de mensagens dos usuários

Quando o canal de informações possui um endereço válido no atributo Response Message URL em seu cadastro, o APP (dispositivo móvel) apresenta uma caixa de texto na lista de mensagens do canal. Quando o usuário envia uma mensagem por essa caixa de texto, a aplicação recebe um POST do webservice para a URL informada. Esse POST contém a mensagem enviada pelo usuário.

As variáveis contidas no POST estão descritas no tópico Recebendo mensagens de usuários.

No protocolo de comunicação do Followzup, o POST enviado para a aplicação não retorna informações para o webservice.


br-111-communication.txt · Last modified: 2017/03/23 07:39 by admin

Page Tools