User Tools

Site Tools


br-030-api-usage


Utilizando a API do canal

As APIs servem para auxiliar o desenvolvedor da aplicação no processo de comunicação com o webservice Followzup e no processo de decriptografia das mensagens enviadas pelos usuários, e devem ser obtidas por download no site do Followzup.

Dentro da API existe uma classe identificada por “FZUP_xxxxxxxxxxxx”, onde “xxxxxxxxxxxx” corresponde ao Channel-ID do canal.

A classe possui 3 métodos:

constructor Método utilizado na instanciação do objeto a ser referenciado.
decrypt Método utilizado para decriptar as mensagens provenientes dos dispositivos móveis dos usuários.
submit Método para submeter solicitações ao webservice Followzup, podendo ser usado para enviar mensagens (comando smsg) ou verificar usuários (comando chck).



Método constructor

As aplicações devem instanciar um objeto para cada canal utilizado. Ao ser instanciado, o objeto inicializa as variáveis contendo a identificação do canal (Channel-ID), a chave criptográfica e o número de sequência das solicitações. O objeto deve ser instanciado conforme exemplos abaixo:

PHP
include ("fzup_cXXXXXXXXXXX.php");
$object = new fzup_cXXXXXXXXXXX;
JAVA
import mylib.fzup_cXXXXXXXXXXX;
fzup_cXXXXXXXXXXX object = new fzup_cXXXXXXXXXXX();
RUBY
require 'fzup_cXXXXXXXXXXX'
object = fzup_cXXXXXXXXXXX.new
PERL
use fzup_cXXXXXXXXXXX;
my $object = new fzup_cXXXXXXXXXXX();
PYTHON
from fzup_cXXXXXXXXXXX import fzup_cXXXXXXXXXXX
object = fzup_cXXXXXXXXXXX()
C# .NET
fzup_cXXXXXXXXXXX object = new fzup_cXXXXXXXXXXX();
fzup_param parameters = new fzup_param();
fzup_result result = new fzup_result();



Método decrypt

O método decrypt serve para decriptografar mensagens enviadas pelos usuários a partir de seus dispositivos móveis.

Veja como utilizar esse método no tópico “Recebendo mensagens de usuários”.



Método submit

Para enviar mensagens e verificar usuários, as aplicações devem o método submit, o qual recebe parâmetros informados por meio de um array de strings, onde cada elemento da array contém o nome do parâmetro e o valor, separados pelo sinal de igual. O retorno desse método também corresponde a um array de strings. O formato geral de chamada do método é o seguinte:

PHP
$result = $object -> submit ( array (
"FZUP_COMMAND = xxxx",
"FZUP_LASTSEQ = 9999",
"FZUP_PARAM_X = ...",
"FZUP_PARAM_Y = ...",
"FZUP_PARAM_Z = ..." ) );
JAVA
String[] result = object.submit ( new String[] {
"FZUP_COMMAND = xxxx",
"FZUP_LASTSEQ = 9999",
"FZUP_PARAM_X = ...",
"FZUP_PARAM_Y = ...",
"FZUP_PARAM_Z = ..." } );
RUBY
result = object.submit ( 
"FZUP_COMMAND" => "xxxx",
"FZUP_LASTSEQ" => "9999",
"FZUP_PARAM_X" => "...",
"FZUP_PARAM_Y" => "...",
"FZUP_PARAM_Z" => "..." )
PERL
my $result = $object->submit ( 
"FZUP_COMMAND = xxxx",
"FZUP_LASTSEQ = 9999",
"FZUP_PARAM_X = ...",
"FZUP_PARAM_Y = ...",
"FZUP_PARAM_Z = ..." );
PYTHON
result = object.submit([ 
"FZUP_COMMAND = xxxx",
"FZUP_LASTSEQ = 9999",
"FZUP_PARAM_X = ...",
"FZUP_PARAM_Y = ...",
"FZUP_PARAM_Z = ..."])
C# .NET
parameters.FZUP_COMMAND = "xxxx";
parameters.FZUP_LASTSEQ = 9999;
parameters.X = "...";
parameters.Y = "...";
parameters.Z = "...";
result = object.submit(parameters);

Os parâmetros variam de acordo com o comando a ser executado, sendo 2 deles comuns a todas a solicitações, são eles: FZUP_COMMAND e FZUP_LASTSEQ, descritos a seguir.


Parâmetro FZUP_COMMAND

O parâmetro FZUP_COMMAND contém o nome da função solicitada ao webservice. Para enviar mensagens esse parâmetro deve conter a literal smsg e para verificar usuários esse parâmetro deve conter a literal chck.


Parâmetro FZUP_LASTSEQ

Toda solicitação enviada ao webservice Followzup possui um número de sequência iniciando em 1 (um) a partir da criação ou renovação das chaves assimétricas do canal.

Depois de encaminhada uma solicitação com um determinado número de sequência N, a API retorna para a aplicação a última sequência utilizada (N + 1), que deve ser informada pela aplicação na próxima solicitação.

Caso a aplicação encaminhe uma solicitação com uma última sequência errada, o webservice simplesmente descarta a solicitação e retorna o código de erro 6101, junto com o valor da última sequência utilizada.

Ao receber o parâmetro FZUP_LASTSEQ da aplicação, a API soma “1” a esse parâmetro e encaminha a solicitação ao webservice. No caso de retorno do erro 6101, a API extrai o valor da última sequência na resposta do webservice, soma “1” a esse valor e reencaminha a solicitação. O valor da última sequência utilizada é mantida no objeto instanciado para ser usado nas próximas solicitações.

O parâmetro FZUP_LASTSEQ é opcional, pois a API guarda o valor de sequência da última solicitação no objeto instanciado, a menos que o objeto tenha sido descartado pelo ambiente.



Retorno do método submit

O método submit retorna um array de strings com 3 elementos, contendo:

Código de retorno Código de retorno da solicitação, sendo o valor “0” (zero) para as solicitações executadas com sucesso e o valor “NNNN” contendo o código de erro da execução. O código 6101 não é retornado para a aplicação, pois é tratado pela API.
Número de sequência Valor inteiro contendo o número de sequência utilizado na última solicitação.
XML de resposta da solicitação String contendo o XML de resposta da solicitação, cujo conteúdo depende do tipo de comando solicitado (smsg ou chck).

Exceto o código de retorno 6101, que é tratado pela API, os demais códigos de retorno devem ser tratados pela aplicação. Os códigos de retorno dependem do que foi solicitado.

É importante que o número de sequência utilizado na última solicitação seja armazenado na base de dados da aplicação, para o caso do objeto instanciado ter sido descartado pelo ambiente. Dessa forma, a última sequência poderá ser informada para a API na próxima solicitação e evitar que a API receba códigos de erro 6101, forçando o reenvio de solicitações e aumentando o tempo de resposta das solicitações.



Exemplo de uso

Nesse exemplo, o administrador de um website deseja receber uma mensagem de alerta em seu celular, toda vez que alguém faz contato pela página “Fale Conosco” de seu website. No quadro abaixo, o formulário HTML contido no script contact.php, que usaremos como exemplo.

contact.php...

echo '<form method="post" action="/gocontact.php">
         <input type="text" name="contact_name"><br>
         <input type="text" name="contact_email"><br>
         <textarea name="contact_text"></textarea><br>
         <input type="submit" value="Submit">
      </form>';


A seguir, as linhas de comando inseridas na rotina de tratamento do formulário de contato, para enviar a mensagem de alerta ao administrador do website.

gocontact.php...

include ("fzup_xxxxxxxxxxxx.php");
$obj = new fzup_xxxxxxxxxxxx;

$name  = $_POST['contact_name'];
$email = $_POST['contact_email'];
$text  = $_POST['contact_text'];

$alert = "Message from $name ($email): $text";

$res = $obj -> submit ( array ( "FZUP_COMMAND = smsg",
                                "FZUP_USER    = admin@website.com",
                                "FZUP_MSGTEXT = $alert" ) );


br-030-api-usage.txt · Last modified: 2017/11/24 06:51 by admin

Page Tools