API SEBRAE Versão 1.1 Brasília 2015
Manual API SEBRAE HISTÓRICO DE VERSÕES Data Versão Descrição Autor 20/04/2015 1.0 Criação Via Appia Informática 08/07/2015 1.1 Melhorias Via Appia Informática
SUMÁRIO 1 INTRODUÇÃO... 5 2 SERVIÇOS... 5 2.1 FORMATOS DE ENTREGA... 6 2.2 AUTENTICAÇÃO... 6 3 SOAP... 7 4 REST... 7 5 IDEIAS DE NEGÓCIO... 8 5.1 SOAP... 8 5.1.1 Consultar Ideias de Negócios por Título... 8 5.1.2 Consultar Setor de Ideias de Negócios... 9 5.1.3 Consultar Ideias de Negócios por setor... 10 5.1.4 Consultar Ideias de Negócios por assunto... 10 5.1.5 Obter Ideia de Negocio... 12 5.1.6 Obter Detalhes Tópico... 13 5.2 REST... 14 5.2.1 Consultar Ideias de Negócios por Título... 14 5.2.2 Consultar Setor de Ideias de Negócios... 15 5.2.3 Consultar Ideias de Negócios por setor... 15 5.2.4 Consultar Ideias de Negócios por assunto... 16 5.2.5 Obter Ideia de Negocio... 17 5.2.6 Obter Detalhes Tópico... 18
1 INTRODUÇÃO Este documento tem a finalidade de descrever os serviços disponíveis na API do SEBRAE, possibilitando orientar o desenvolvimento de novas soluções utilizando as várias bases de dados existentes no sistema SEBRAE. Atualmente a API disponibiliza os serviços identificados para o sistema Ideias de Negócios através de Serviços WEB (WEB Services). A troca de dados ocorre em formato XML e o fato desse modelo ser baseado em tecnologias padrão é o maior benefício. Figura 1 - Visão Geral da Arquitetura da Solução BANCO DE DADOS CAMADA DE ACESSO A DADOS WEB SERVICES CLIENTES Dados API ihub WEB SERVICES Dados API ihub WEB SERVICES Dados API ihub WEB SERVICES Dados API ihub WEB SERVICES Dados API ihub WEB SERVICES Fonte: Produção própria 2 SERVIÇOS Uma arquitetura que utiliza serviços tem a finalidade de garantir a reutilização das regras de negócio encapsulando-as em serviços distintos. Os serviços aqui descritos objetivam disponibilizar os conteúdos das bases de conhecimento do SEBRAE de maneira mais simples e centralizada. Além disto, graças a obrigatoriedade da identificação dos usuários/aplicativos que consomem os serviços disponibilizados na API, através do módulo de gerenciamento da API, seus gestores podem acompanhar informações sobre acessos aos métodos 5
por determinado usuário/aplicativo bem como gerar relatórios estatísticos sobre as informações mais e menos acessadas por determinado usuário/aplicativo. 2.1 Formatos de Entrega Devido a necessidade de facilidade para acesso às informações do Barramento da API através de vários tipos de plataforma tais como Plataformas Mobile (IOS Apple, Google Android, Microsoft Windows Phone e outros sistemas (B2B), optou-se por fazer com que o barramento seja responsável pela transformação dos dados em vários formatos. As informações são entregues em serviços (endpoints) distintos listados abaixo: REST - JSON Javascript Object Notation; REST - XML extensible Markup language; WSDL/SOAP Webservice Descriptor Language Simple Object Access Protocol. 2.2 Autenticação Para garantir uma maior segurança das informações disponibilizadas na API, bem como identificar os usuários e aplicativos que utilizam cada um dos serviços, todas as requisições aos métodos das API necessitam de identificação através de login, senha e identificação do aplicativo que está originando o acesso (token de autenticação). Os tokens de autenticação são fornecidos pelo gestor da API, sempre que solicitado. É importante ressaltar que tanto para requisições SOAP quanto REST, é necessário que o login e a senha sejam criptografados em BASE64. O algoritmo Base64 é amplamente conhecido pela internet. Trata-se de um algoritmo utilizado principalmente para converter dados binários em código alfanumérico. Para mais informações a respeito, sugerimos a leitura das informações no site http://tools.ietf.org/html/rfc989, mais especificamente na seção 4.3. 6
3 SOAP Em requisições SOAP, o login e senha devem ser enviados através do Header da requisição utilizando a tag Authorization. O valor da tag completo (login e senha) deverá ser criptografado em Base64, obedecendo o seguinte padrão de construção: Base64({#usuário}:{#senha}) Considerando o usuário alexandre e a senha alexandre, o cabeçalho passaria a ter o valor a seguir: Authorization: YWxleGFuZHJlOmFsZXhhbmRyZQ== Nos métodos de cada requisição SOAP, terá um item obrigatório que é a identificação do aplicativo, que também é usada para validar a requisição identificando o aplicativo que está originando o acesso ao método em questão. 4 REST Os serviços disponibilizados em REST, utilizam autenticação do tipo HTTP Basic, do qual consiste em passar no Header HTTP Authorization obedecendo o seguinte algoritmo: Basic Base64({#usuário}:{#senha}) Assim como nas requisições SOAP, também é necessário informar o aplicativo que está originando o acesso. Para isto, no header é necessário acrescentar a identificação do aplicativo que está realizando a solicitação do serviço. A tag a ser incluída no Header da requisição HTTP será AppId. Como valor deve ser informada a identificação do aplicativo no sistema da API do Sebrae. 7
5 IDEIAS DE NEGÓCIO 5.1 SOAP 5.1.1 Consultar Ideias de Negócios por Título Webmethod: consultarideiasportitulo Consulta que retorna as Ideias de Negócio a partir de uma descrição total ou parcial do título da Ideia de Negócio. O filtro é sempre realizado tomando-se por base o título do início para o fim da palavra. Exemplo: se como parâmetro de entrada da consulta for informado o fragmento ad", então, serão retornadas todas as Ideias de Negócios cujos títulos iniciam com o fragmento ad (adega, adestramento de cães, administração de condomínios, etc.). desctitulo Descrição total ou parcial do título da Ideia de Negócio Código ou APP ID que identifica identificadoraplicativo quem está chamando o serviço. (Aplicativo do desenvolvedor que utiliza o serviço) listaidentificadoresideiasnegocio Lista de Títulos e Identificadores das Ideias de Negócios Lista de objetos titulo Título da Ideia de Negócio identificadorideia Código identificador único da Ideia. 8
5.1.2 Consultar Setor de Ideias de Negócios Webmethod: consultarsetordeideias Consulta que retorna setores de Ideias de Negócio a partir de uma descrição total ou parcial do título do setor. O filtro é sempre realizado tomando-se por base o título do início para o fim da palavra. Exemplo: se como parâmetro de entrada da consulta for informado o fragmento a", então, serão retornados todos os setores cujos títulos se iniciam com o fragmento a" (Agroenergia, Apicultura, Aqüicultura e Pesca, Artesanato, etc.). titulo Título do setor (descrição) identificadorsetor Código identificador único do setor / tópico. titulo Título do setor (descrição) identificadorsetor Código identificador único do setor / tópico. 9
5.1.3 Consultar Ideias de Negócios por setor Webmethod: consultarideiasporsetor Consulta que retorna Ideias de Negócio a partir da identificação do setor da Ideia de Negócio. identificadorsetor Identificador do setor Código ou APP ID que identifica identificadoraplicativo quem está chamando o serviço. (Aplicativo do desenvolvedor que utiliza o serviço) Lista de Títulos e Identificadores listaidentificadoresideiasnegocio das Ideias Lista de objetos 5.1.4 Consultar Ideias de Negócios por assunto Webmethod: consultarideiasporassunto Consulta que retorna Ideias de Negócios a partir de uma descrição total ou parcial do assunto. Importante sublinhar que no presente contexto, assunto se refere as palavras-chave ou indexadores de cada Ideia de Negócio e não ao setor em que determinada Ideia de Negócio foi classificada. Apenas a título de informação, é importante ressaltar que na base de dados do Ideias de Negócios, os campos (metadados) setor e assunto são distintos e, portanto, não se confundem. O filtro é sempre realizado tomando-se por base o título do início para o fim da palavra. Exemplo: se como parâmetro de entrada da consulta for informado o fragmento sal, então serão retornadas todas as ideias de negócios cujos assuntos se iniciam com o fragmento sal" (salão, salão de beleza, etc.). Observação: Nesta pesquisa somente serão retornados o título e a identificação das Ideias cujos assuntos atendem ao parâmetro de entrada informado. O conteúdo da ideia (capítulos) será retornado no método obterideiadenegocio. 10
assunto Assunto a ser consultado Código ou APP ID que identifica identificadoraplicativo quem está chamando o serviço. (Aplicativo do desenvolvedor que utiliza o serviço) listaidentificadoresideiasnegocio Lista de Títulos e Identificadores das Ideias de Negócios Lista de objetos 11
5.1.5 Obter Ideia de Negocio Webmethod: obterideiadenegocio Consulta que retorna o conteúdo (capítulos), total ou parcial de uma Ideia de Negócio a partir da identificação da Ideia de Negócio. identificadorideia Identificador da Ideia de Negócio Código ou APP ID que identifica identificadoraplicativo quem está chamando o serviço. (Aplicativo do desenvolvedor que utiliza o serviço) apresentacaonegocio Apresentação da Ideia de Negócio localizacao Localização da Ideia de Negócio exigencialegal Exigências Legais específicas da Ideia de Negócio pessoal Pessoal da Ideia de Negócio equipamentos Equipamentos da Ideia de Negócio materiaprima Matérias Primas organizacaoprocessoprodutivo Organização do processo produtivo da Ideia de Negócio automacao Automações da Ideia de Negócio canaisdistribuicao Canais de Distribuição da Ideia de Negócio Investim entos Informações Fiscais e Tributárias capitalgiro Capital de Giro da Ideia de Negócio custos Custos da Ideia de Negócio diversificacaoagregacaovalor Diversificação da Agregação de Valor da Ideia de Negócio divulgacao Divulgação da Ideia de Negócio informacoesfiscaistributarias Informações Fiscais da Ideia de Negócio eventos Eventos da Ideia de Negócio 12
entidadesgeral Entidades Gerais da Ideia de Negócio normastecnicas Normas Técnicas da Ideia de Negócio glossario Glossário da Ideia de Negócio dicasnegocio Dicas da Ideia de Negócio caracteristicasespecificasempree endedor bibliografiacomplementar Características específicas para o empreendedor da Ideia de Negócio Bibliografia Complementar da Ideia de Negócio tituloideia Título da Ideia de Negócio 5.1.6 Obter Detalhes Tópico Webmethod: obtertopicodaideia Retorna os detalhes dos tópicos a partir do identificador da Ideia de Negócio. identificadordaideia Identificador da Ideia de Negócio Código ou APP ID que identifica identificadoraplicativo quem está chamando o serviço. (Aplicativo do desenvolvedor que utiliza o serviço) topico Tópico da Ideia de Negócio a se obter os detalhes Enum conteudo Conteúdo do tópico consultado 13
5.2 REST Para as requisições REST, no Header da requisição HTTP deverão ser especificados dois atributos: Accept e Content-Type. Para o retorno e envio do conteúdo em JSON deverão ser informados: application/json; charset=utf-8, e para o retorno e envio de dados em XML: application/xml; charset=utf-8. Desta forma a API retornará o conteúdo de acordo com o que for solicitado na requisição. Isto garante ao desenvolvedor a flexibilidade de alterar somente o Header, sem maiores alterações no desenvolvimento da comunicação com a API. 5.2.1 Consultar Ideias de Negócios por Título Tipo: GET Path: /rest/ideias/titulo/{nome} Consulta que retorna Ideias de Negócio a partir de uma descrição total ou parcial do título da Ideia de Negócio. O filtro é sempre realizado tomando-se por base o título do início para o fim da palavra. Exemplo: se como parâmetro de entrada da consulta for informado o fragmento ad", então, serão retornadas todas as ideias de negócios cujos títulos iniciam com o fragmento ad (adega, adestramento de cães, administração de condomínios, etc.). {nome} Descrição total ou parcial do título da Ideia de Negócio listaidentificadoresideiasnegocio Lista de Títulos e Identificadores das Ideias de Negócio Lista de objetos titulo Título da Ideia identificadorideia Código identificador único da Ideia de Negócio. 14
5.2.2 Consultar Setor de Ideias de Negócios Tipo: GET Path: /rest/ideias/setor/{nome} Consulta que retorna setores de Ideias de Negócio a partir de uma descrição total ou parcial do título do setor. O filtro é sempre realizado tomando-se por base o título do início para o fim da palavra. Exemplo: se como parâmetro de entrada da consulta for informado o fragmento a", então, serão retornados todos os setores cujos títulos se iniciam com o fragmento a" (Agroenergia, Apicultura, Aquicultura e Pesca, Artesanato, etc.). {nome} Descrição total ou parcial do setor titulo Título do setor (descrição) identificadorsetor Código identificador único do setor / tópico. 5.2.3 Consultar Ideias de Negócios por setor Tipo: GET Path: /rest/ideias/ideia/setor/{identificadorsetor} Consulta que retorna Ideias de Negócio a partir da identificação do setor da Ideia de Negócio. {identificadorsetor} Identificador do setor listaidentificadoresideiasnegocio Lista de Títulos e Identificadores das Ideias de Negocio Lista de objetos 15
5.2.4 Consultar Ideias de Negócios por assunto Tipo: GET Path: /rest/ideias/ideia/assunto/{assunto} Consulta que retorna Ideias de Negócio a partir de uma descrição total ou parcial do assunto. Importante sublinhar que, no presente contexto, assunto se refere as palavras-chave indexadores de cada Ideia de Negócio não ao setor em que determinada Ideia de Negócio foi classificada. É importante ressaltar que, na base de dados das Ideias de Negócios, os campos (metadados) de setor e assunto são distintos e, portanto, não se confundem. O filtro é sempre realizado tomando-se por base o título do início para o fim da palavra. Exemplo: se como parâmetro de entrada da consulta for informado o fragmento sal, então, serão retornadas todas as ideias de negócios cujos títulos do assunto se iniciam com o fragmento sal" (salão, salão de beleza, etc.). Observação: Nesta pesquisa somente serão retornados o título e a identificação das Ideias de Negócio cujos assuntos atendem ao parâmetro de entrada informado. O conteúdo (capítulos) da Ideia será retornado no método Obter Ideia de Negócio. {assunto} Assunto a ser consultado listaideiasnegocio Lista de Títulos e Identificadores das Ideias de Negócios Lista de objetos 16
5.2.5 Obter Ideia de Negocio Tipo: GET Path: /rest/ideias/{identificadorideia} Consulta que retorna o conteúdo (capítulos) total ou parcial de uma Ideia de Negócio, a partir do identificador da Ideia. {identificadorideia} Identificador da Ideia de Negócio apresentacaonegocio Apresentação da Ideia de Negócio localizacao Localização da Ideia de Negócio exigencialegal Exigências Legais específicas da Ideia de Negócio estrutura Estrutura Ideia de Negócio pessoal Pessoal da Ideia de Negócio equipamentos Equipamentos da Ideia de Negócio materiaprima Matérias Primas organizacaoprocessoprodutivo Organização do processo produtivo da Ideia de Negócio automacao Automações da Ideia de Negócio canaisdistribuicao Canais de Distribuição da Ideia de Negócio Investim entos Informações Fiscais e Tributárias capitalgiro Capital de Giro da Ideia de Negócio custos Custos da Ideia de Negócio diversificacaoagregacaovalor Diversificação da Agregação Valor da Ideia de Negócio de divulgacao Divulgação da Ideia de Negócio informacoesfiscaistributarias Informações Fiscais da Ideia de Negócio eventos Eventos da Ideia de Negócio 17
entidadesgeral Entidades Gerais da Ideia de Negócio normastecnicas Normas Técnicas da Ideia de Negócio glossario Glossário da Ideia de Negócio dicasnegocio Dicas da Ideia de Negócio caracteristicasespecificasempree endedor bibliografiacomplementar Características específicas para o empreendedor da Ideia de Negócio Bibliografia Complementar da Ideia de Negócio tituloideia Título da Ideia de Negócio 5.2.6 Obter Detalhes Tópico Tipo: GET Path: /rest/ideias/{identificadorideia}/topico/{topico} Retorna os detalhes dos tópicos a partir do identificador da Ideia de Negócio. {identificadordaideia} Identificador da Ideia de Negócio {tópico} Tópico da ideia a se obter os detalhes conteudo Conteúdo do tópico consultado 18