User Tools

Site Tools


br-120-api-dev


Desenvolvimento de novas APIs

Esse capítulo descreve o protocolo de comunicação entre APIs e o webservice Followzup, para ser usado como referência no desenvolvimento de novas APIs.

Qualquer que seja a linguagem utilizada, ela deve dispôr das bibliotecas de criptografia AES e RSA compatíveis com PHP, utilizado no desenvolvimento do webservice que atende as solicitações dos canais de informações. As APIs atuais podem ser usadas como referência.



Estrutura da API

Para que a API possa ser disponibilizada para download no site do Followzup, esta deverá obedecer o padrão das APIs já existentes, a saber:

  • O nome do fonte da API deverá ser fzup.EXT, onde EXT corresponde à extensão do arquivo de acordo com a linguagem utilizada.
  • O código fonte deverá conter as literais do quadro abaixo, as quais serão identificadas e substituídas pelo Followzup na execução do download. Essas literais correspondem às constantes que identificam os atributos de cada canal. São elas:
      #idchannel# ... Literal a ser substituída pelo Channel-ID;
      #pubkey64# .... Literal a ser substituída pela chave pública RSA (formato base64)
      #pubkeymod# ... Literal a ser substituída pela chave pública RSA (componente module)
      #pubkeypux# ... Literal a ser substituída pela chave pública RSA (componente index)
  • A API deverá implementar uma classe, que será instanciada pela aplicação e deverá conter os métodos constructor, decrypt e submit.
  • Os métodos deverão receber parâmetros da aplicação na forma de array de strings, onde em cada elemento da array haverá o nome do parâmetro e o respectivo valor, separados pelo sinal de igual.
  • O objeto instanciado deverá manter (enquanto instanciado), o último número de sequência utilizado na solicitação ao webservice, suprindo assim o sequenciamento das solicitações para o caso da aplicação não fornecer a sequência.
  • O método decrypt deverá retornar um string.
  • O método submit deverá retornar um array de strings e tratar o código de retorno 6101 (erro de sequência).



Comunicação com o webservice

Toda comunicação com o webservice intermediada pela API é realizada por meio de POST. No caso das solicitações de canais de informações, a URL de destino do POST é “http://followzup.com/wschannel”.

A API deverá definir as seguintes variáveis POST:

id Código de identificação do canal solicitante, sem criptografia (Channel-ID)
key Chave AES (temporária), criptografada com a chave pública do canal e codificada em Base64 / URL Encode.
frame String criptografado com a chave AES (temporária), contendo o XML de solicitação (comando, número de sequência da solicitação e parâmetros), e codificado em Base64 / URL Encode.



XML de resposta do POST

Após o processamento da solicitação contida no POST, o webservice retorna o seguinte XML para o solicitante:

<?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:

  • código-de-retorno: String não criptografado, contendo o valor “0” (zero) para as solicitações executadas com sucesso, ou o código de erro correspondente, composto por 4 dígitos numéricos.
  • xml-de-resposta-da-solicitação: String criptografado com a mesma chave AES utilizada no envio da solicitação (chave temporária), e codificado em Base64. O conteúdo do XML depende do que foi solicitado.
  • md5-de-resposta: String contendo o hash md5 do campo acima.



Sequência da solicitação

O XML de solicitação enviado ao webservice contém os parâmetros necessários para executar o comando desejado. Esse XML é construído pela API a partir dos parâmetros fornecidos pela aplicação.

Além do comando a ser executado e dos parâmetros necessários para sua execução, o XML de solicitação deve incluir a sequência da solicitação, que corresponde a um número inteiro iniciado em 1 a partir da criação do canal ou da renovação da chave RSA. Após a solicitação com sequência N, a próxima solicitação deve obrigatoriamente possuir a sequência N + 1.

IMPORTANTE: O número de sequência da solicitação incluido nesse XML não deve ser confundido com o número de sequência fornecido pela aplicação para a API, pois este corresponde à última sequência utilizada. O número de sequência fornecido pela aplicação deve ser adicionado em 1 antes de ser inserido no XML de solicitação. Caso a aplicação não forneça a última sequência utilizada (parâmetro opcional), a API deve buscar a última sequência no objeto instanciado.


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

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



Resposta da API para a aplicação

Ao finalizar sua execução, a API retorna um array de 3 posições para aplicação, são elas:

  • array[0]: Contém o código de retorno da solicitação;

  • array[1]: Contém o número de sequência utilizado na solicitação;

  • array[2]: Contém o XML de resposta da solicitação.

Com exceção do código de retorno 6101, tratado pela própria API, os demais erros são sempre retornados para a aplicação.



Comandos disponíveis

Abaixo, os comandos disponíveis para envio de solicitações de canais de informações:

  • SMSG: Enviar mensagens;
  • CHCK: Verificar usuários.


br-120-api-dev.txt · Last modified: 2017/05/08 09:54 by admin

Page Tools