API

O Sistema de Apoio à Comunicação Integrada – SACI oferece uma interface de programação de aplicações (Application Programming Interface – API) voltada para a publicação de matérias. Com isso, é possível que a a publicação de uma matéria seja realizada não por um operador (usuário humano) mas sim pelo próprio SACI em outros sistemas, tais como gerenciadores de conteúdo (Content Management System – CMS), aplicativos móveis etc.

A principal vantagem em se adotar a publicação via API é tornar desnecessária a cópia, geralmente tediosa, de conteúdo preparado dentro do SACI para sistemas de terceiros, como por exemplo sites institucionais.

Em seguida serão detalhados os passos para se usar a API de publicação do SACI. Como exemplo serão utilizados códigos Javascript em uma página Web de teste, porém isso poderá ser facilmente adaptado pelo leitor para permitir a integração do SACI com qualquer CMS ou aplicativo.

Pré-requisitos

  • SACI 4.2 (ou superior) instalado e funcionando corretamente. Ao longo do tutorial será assumida a URL de exemplo http://saci.instituicao.br
  • Um produto jornalístico com base em um dos gabaritos: Joomla, Drupal ou Plone

Identificando um produto no SACI

Todo conteúdo publicável a partir do SACI é chamado de “matéria”. Semelhante a matérias de jornal ou revista, toda matéria no SACI está relacionada a um produto jornalístico, como por exemplo um boletim de e-mail, um site ou uma rede social.

É necessário descobrir qual a identificação do produto com o qual queremos integrar nosso site de exemplo. Para isso:

  1. Acesse a área interna do SACI (forneça seu e-mail e sua senha);
  2. Na lateral esquerda, acesse o menu “Unidades”;
  3. Selecione a unidade em que seu produto está cadastrado
  4. Na parte superior direita da página, clique na opção “Produtos”
  5. Selecione o produto que você deseja integrar ao site de exemplo
  6. Observe a barra de endereço (URL) do seu navegador. Ela deverá ter um conteúdo parecido com http://saci.instituicao.br/produto?id=P . Neste caso, o “P” é o número do produto que queremos testar.

Obtendo as matérias prontas para publicação

O primeiro serviço disponível na API de publicação do SACI é o de listagem das matérias prontas para publicação. Para testar esse serviço vamos criar uma página HTML simples (index.html) e adicionar o código Javascript necessário. Para fins de clareza adotaremos a biblioteca jQuery, porém qualquer biblioteca que permita o uso de chamadas AJAX usando JSON pode ser usada.

O exemplo abaixo recupera a lista de matérias do produto P que estão prontas para publicação e exibe o resultado no console do navegador:

    $.ajax({
        url:"http://saci.instituicao.br/listar_materias",
        type:'GET',
        async: true,                    
        dataType:'jsonp',   
        jsonpCallback: "callback", 
        contentType: "application/json",
        data:{produto: P}, 
        success: function(response) { 
            $.each(response, function(key, value) { 
                materia=value.id; 
                console.log(“id:” + value.id
                    +"\ntítulo:"+value.titulo
                    +"\ndestaque:"+value.destaque 
                    +"\ndestaque_imagem: "+value.destaque_imagem
                    +"\ndata_inicio: "+value.inicio+"\ndata_fim: "+value.fim 
                    +"\ntexto: "+value.texto);
                $.each(value.classificacoes, function(key,value){ 
                    console.log("-"+value.id);            
                    $.each(value.subclassificacoes, function(key,value){ 
                        console.log("--"+value.descricao);              
                    }); 
                });                            
            }); 
        }, 
        error: function(xHr,textStatus,error) { 
            console.log(textStatus); 
            console.log(error); 
        } 
    });

Em termos mais técnicos, a lista é retornada no formato JSONP, com cada item da lista representando uma matéria completa. Cada matéria possui o formato (em pseudo-código):

    Integer id //identificador
    String titulo //título
    String texto //texto completo
    String destaque_imagem //URL completa da imagem de destaque (pode ser nula)
    DestaqueCoordenadas destaque_coordenadas //coordenadas de corte da imagem de destaque
    List<Anexo> anexos //lista dos anexos
    Date inicio //data de início da publicação (pode ser nula)
    Date fim //data de vencimento da publicação (pode ser nula)
    List<Classificacao> classificacoes //lista das classificações da matéria
    Boolean destaque //se a matéria deve ter destaque na página inicial do site

A estrutura “coordenadas de destaque” possui o formato:

    Integer x1 //coordenada X do ponto superior-esquerdo (pixels)
    Integer y1 //coordenada Y do ponto superior-esquerdo (pixels)
    Integer x2 //coordenada X do ponto inferior-direito (pixels)
    Integer y2 //coordenada Y do ponto inferior-direito (pixels)

A estrutura “anexo” possui o formato:

    String arquivo //URL completa do anexo
    String legenda //legenda descrevendo o anexo (pode ser vazio) 

A estrutura “classificação” possui o formato:

    Integer id //identificador
    String descricao //descrição (seu nome)
    List<Subclassificacao> subclassificacoes //lista de subclassificações  

Finalmente, o formato de uma subclassificação é:

    Integer id; //identificador
    String descricao; //dscrição (seu nome)  

Vale notar que aquelas matérias que ainda não foram redigidas, editadas ou revisadas, ou ainda aquelas que já foram publicadas, não serão incluídas nesta lista.

Marcando uma matéria como publicada

Uma vez obtida a lista de matérias prontas para publicação, nossa aplicação de teste simplesmente imprimiu o conteúdo das matérias no console do navegador. Porém, uma aplicação real faria algo muito mais significativo. Um CMS, por exemplo, poderia converter cada matéria em um “post” em um site institucional. Já um aplicativo móvel poderia gerar um efeito sonoro alertando o usuário de que uma nova notícia está pronta.

Uma vez que uma ação tenha sido tomada, é necessário acessar o segundo serviço disponível na API de publicação do SACI, que é o de publicação de matéria. Apenas uma matéria por vez pode ser marcada como “publicada”, dificultando assim a ocorrência de acidentes.

O exemplo abaixo marca a matéria de identificador M como publicada:

    $.ajax({ 
        url:"http://localhost:8080/saci/publicar_materias", 
        type:'POST', 
        async: true,                    
        dataType:'jsonp', 
        jsonpCallback: "callback", 
        contentType: "application/json", 
        data:{materia: M}, 
        success: function() { 
      console.log("materia "+M+" publicada com sucesso"); 
        }, 
        error: function(xHr,textStatus,error) { 
      console.log(textStatus); 
      console.log(error); 
        } 
    });

Diferente do primeiro serviço (de listagem), este método não retorna informações significativas. Porém, é imprescindível que ele seja invocado, uma vez para cada matéria publicada, do contrário essas mesmas matérias continuarão a constar na lista de matérias disponíveis.

Casos especiais

Em geral o serviço para listagem de matérias lista apenas aquelas prontas para publicação, porém atenção especial deve ser dada a um caso particular: matérias que já foram publicadas mas que sofreram atualizações, voltando assim a constar como prontas para publicação. Esse comportamento é comum em casos de errata, complementação de texto etc, e cabe ao consumidor do serviço decidir como proceder.

Em casos onde o sistema consumidor seja um CMS (por exemplo, Drupal), é aconselhável:

  • Selecionar o identificador da matéria sendo listada
  • Procurar o post que foi gerado a partir dessa matéria (isso implifica que os posts precisem de um novo atributo para que se possa recuperar a matéria de origem)
  • Atualizar o post com o novo texto
  • Adicionar ao post uma nota de rodapé ou informar a data de atualização
  • Marcar a matéria como publicada

    Porém, cada caso deve ser tratado a parte, já que estão envolvidas variáveis como o modelo de negócio do consumidor do serviço, o tipo do seu sistema (ex: CMS, aplicativo) etc.