API iSCORE

De Wiki iScore
Ir para: navegação, pesquisa
Métodos API
Listar Metas Listar Unidades de Medida por Identificador Configurações Globais
Listar Metas pelo ID do Indicador Listar Objetivos Estratégicos por Scorecard
Adicionar Metas Listar Perspectivas por Scorecard
Adicionar Metas usando cURL Listar Unidades Organizacionais por Token
Buscar Indicador pelo ID Listar Scorecards por Unidade Organizacional
Listar TODOS Indicadores de uma Unidade Organizacional Listar TODAS Iniciativas Estratégicas de uma Unidade Organizacional
Lista Geral por Unidade Organizacional com parâmetro Lista Geral por Unidade Organizacional sem parâmetro



Índice

Descrição

A API (Application Programming Interface) é uma forma que o usuário tem de interagir com o sistema iScore, permitindo a integração do mesmo com outras aplicações de sua organização. Através da API do iScore é possível listar todas as metas de uma determinada Unidade Organizacional, bem como listar as metas por indicador. É possível também realizar backup e acessar os dados dos indicadores no Excel que podem gerar relatórios e gráficos; assim como, alimentar automaticamente as metas dos indicadores utilizando dados existentes em uma base de dados da organização. A API do iScore é uma ferramenta bastante poderosa que potencializa o uso do sistema e suas integrações.


URL do Serviço

A URL para utilizar a API é http://api.iscore.com.br/v1 . Essa URL é referente a primeira versão e qualquer alteração realizada na API terá uma nova versão criada, passando a URL para http://api.iscore.com.br/v2. As versões vão sendo atualizadas à medida que alterações forem feitas na API. Assim, todas as versões serão disponibilizadas para que o usuário escolha a versão ideal para trabalhar.


Autenticação

A utilização da API é sempre através de um usuário existente no IScore. Não há nenhum usuário API especial. As permissões da API dependem de autorização dada ao usuário no Iscore. Cada usuário possui um token que irá identicá-lo no sistema. O token deve ser protegido para que terceiros não o utilize. Caso seja necessário, um novo token pode ser gerado clicando no botão “Gerar Token” no cadastro do usuário IScore.


Limites de Requisições

Por padrão, todas as contas têm um limite de requisições de 500 solicitações por hora e 8400 solicitações por dia. Quando o cliente excede o limite da taxa receberá um código de resposta HTTP 403 e as mensagens: "Ultrapassou o limite de requests por hora" e “Ultrapassou o limite de requests por dia”.


XML e JSon

XML

Com a XML (Extensible Markup Language) é possível criar os próprios conjuntos de elementos de marcação. Ela busca descrever o conteúdo de um documento, e não como ele deve ser exibido. Com essas marcações, é possível estruturar os dados, que em seguida podem ser facilmente recuperados e utilizados de diversas maneiras.


JSon

Com o Json (JavaScript Object Notation) é possível ter uma estrutura de dados em JavaScript. O Json pode substituir o XML e com a ele a estrutura de dados fica mais simples de trabalhar, sem contar que a execução de um script lendo dados em Json é mais rápido do que ler um conteúdo em XML.


Formatos de Representação - XML

Abaixo segue uma representação de documento XML para listar metas, chamado metas.xml que armazena, de forma estruturada os dados referentes a algumas metas.

 <?xml version="1.0" encoding="UTF-8" ?>        
 <metas>
     <meta>
             <indicador_id>16</indicador_id>
             <mes>2</mes>
             <ano>2012</ano>
             <realizado>5</realizado>
             <previsto>5</previsto>
     </meta>
     
     <meta>
             <indicador_id>83</indicador_id>
             <mes>2</mes>
             <ano>2012</ano>
             <realizado>1,000</realizado>
             <previsto>1,000</previsto>
     </meta>
 </metas>


Formatos de Representação - JSon

Abaixo segue uma representação de documento Json para listar metas, chamado metas.json que armazena, de forma estruturada os dados referentes a algumas metas.

[
  {
      Meta: {
          id: 13,
          previsto: "54645.6600",
          realizado: "0.0000",
          mes: 1,
          ano: 2011
      }
  },
  {
      Meta: {
          id: 14,
          previsto: "1515.5500",
          realizado: "0.0000",
          mes: 2,
          ano: 2011
      }
  }
]


Erros

Abaixo segue uma lista de códigos de erros das requisições.


Códigos de Erro das requisições
Código de Status HTTP Descrição
200 OK - Requisição atendida com sucesso
401 Unauthorized - Credencial de Autenticação inválida/incorreta
403 Forbidden - Requisição correta porém recusada pelo servidor (Ex: exedeu limites contratados/requisição)
404 Not Found - URI inválido ou recurso não existente (ex: id do indicador não existe)
406 Not Acceptable - Formato de requisição inválido
500 Internal Server Error - Problema no serviço. Necessário chamar o suporte
502 Bad Gateway - Servidor indisponível ou em atualização
503 Service Unavailable - Servidor indisponível por sobrecarga. Tentar novamente após algum tempo













Os modelos de retorno de mensagem de erro do Iscore API são:


XML

<errors>
  <status>401</status>
  <error>Token Inválido</error>
  <request>/batman/ED/iniciativasEstrategicas.xml</request>
</errors>


JSON

{
 errors: {
  status: 401,
  error: "Token Inválido",
  request: "/batman/ED/iniciativasEstrategicas.json"
 }
}
Ferramentas pessoais
Espaços nominais

Variantes
Ações
Navegação
Ferramentas