API SEBRAE Versão 1.2 Brasília 2016
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 10/12/2016 1.3 Criação de métodos de busca e depreciação de outros 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 REST... 7 4 IDEIAS DE NEGÓCIO... 8 4.1 REST... 8 4.1.1 Consultar Setor de Ideias de Negócios... 8 4.1.2 Consultar Ideias de Negócios por setor... 9 4.1.3 Obter Ideia de Negocio... 10 4.1.4 Obter Detalhes Tópico... 13 4.1.5 Busca simples de Ideias de Negócios... 13 4.1.6 Busca avançada de ideias de Negócio... 16
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 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
4 IDEIAS DE NEGÓCIO 4.1 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. 4.1.1 Consultar Setor de Ideias de Negócios Tipo: GET Path: /rest/ideiasv2/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.). Atributos de entrada Nome Descrição Tipo Obrigatório {nome} Descrição total ou parcial do setor SIM Atributos retornados Nome Descrição Tipo titulo Título do setor (descrição) identificadorsetor Código identificador único do setor / tópico. Exemplo de XML de retorno HTTP/1.1 200 OK X-UA-Compatible: IE=8 Content-Length: 2076 8
Content-Type: application/xml; charset=utf-8 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <ideiasetores> <setor> <identificadorsetor>10</identificadorsetor> <titulo>apicultura</titulo> <descricao></descricao> </setor> <setor> <identificadorsetor>12</identificadorsetor> <titulo>ovinocaprinocultura</titulo> <descricao></descricao> </setor> </ideiasetores> 4.1.2 Consultar Ideias de Negócios por setor Tipo: GET Path: /rest/ideias/ideiav2/ideia/setor/{identificadorsetor} Consulta que retorna Ideias de Negócio a partir da identificação do setor da Ideia de Negócio. Atributos de entrada Nome Descrição Tipo Obrigatório {identificadorsetor} Identificador do setor SIM Atributos retornados Nome Descrição Tipo listaidentificadoresideiasnegocio Lista de Títulos e Identificadores das Ideias de Negocio Lista de objetos Exemplo de XML de retorno HTTP/1.1 200 OK X-UA-Compatible: IE=8 Content-Length: 2076 Content-Type: application/xml; charset=utf-8 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <ideiasidentificadores> <ideiaidentificador> <identificadorideia>00c868170e0d9ed183257d69004753f7</identificadorideia> <titulo>agência de turismo de impacto social</titulo> 9
</ideiaidentificador> <ideiaidentificador> <identificadorideia>76b940ed20947abd832579980068d247</identificadorideia> <titulo>agência de turismo receptivo</titulo> </ideiaidentificador> <ideiaidentificador> <identificadorideia>3ccd900b8ceec4e2832579c30051de7e</identificadorideia> <titulo>empresa de turismo naútico</titulo> </ideiaidentificador> <ideiaidentificador> <identificadorideia>07fd337b0807b3a2832579f80068cb17</identificadorideia> <titulo>hotel de uma estrela</titulo> </ideiaidentificador> <ideiaidentificador> <identificadorideia>7fc3cb51a25ba904832579d60052d6b8</identificadorideia> <titulo>hotel fazenda</titulo> </ideiaidentificador> <ideiaidentificador> <identificadorideia>aa7e659a11d92349832579d6004ae458</identificadorideia> <titulo>pousada</titulo> </ideiaidentificador> </ideiasidentificadores> 4.1.3 Obter Ideia de Negocio Tipo: GET Path: /rest/ideiasv2/{identificadorideia} Consulta que retorna o conteúdo (capítulos) total ou parcial de uma Ideia de Negócio, a partir do identificador da Ideia. Atributos de entrada Nome Descrição Tipo Obrigatório {identificadorideia} Identificador da Ideia de Negócio SIM Atributos retornados Nome Descrição Tipo apresentacaonegocio Apresentação da Ideia de Negócio localizacao Localização da Ideia de Negócio 10
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 Investimentos 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 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 Exemplo de XML de retorno HTTP/1.1 200 OK X-UA-Compatible: IE=8 Content-Length: 2076 Content-Type: application/xml; charset=utf-8 11
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <ideia> <identificadorideia>76b940ed20947abd832579980068d247</identificadorideia> <titulo>agência de turismo receptivo</titulo> <autor>paulo César Borges de Sousa</autor> <apresentacao>aviso: Antes de conhecer este negócio, vale ressaltar que os tópicos a seguir não fazem parte de um Plano de Negócio e sim do perfil do ambiente no qual o empreendedor irá vislumbrar uma oportunidade de negócio como a descrita a seguir. O objetivo de todos os tópicos a seguir é desmistificar e dar uma visão geral de como um negócio se posiciona no mercado. Quais as variáveis que mais afetam este tipo de negócio? Como se comportam essas variáveis de mercado? Como levantar as informações necessárias para se tomar a iniciativa de O turismo receptivo é o serviço destinado a atender as expectativas das pessoas que adquiriram o produto turístico ou que viajam a negócios e precisam de apoio em seus deslocamentos. Corresponde à oferta turística, já que se trata da localidade receptora e seus respectivos atrativos, bens e serviços a serem oferecidos aos turistas lá presentes, bem como apresentar opções de atuarem no chamado turismo de Para que o segmento de turismo receptivo de uma cidade ou região se desenvolva, devem existir alguns fatores de atração de visitantes, tais como recursos naturais, históricos e culturais, facilidade de acesso, promoção turística, infraestrutura básica e complementar, condições favoráveis de vida da população local; posicionamento geográfico adequado e centros de Outro objetivo é criar facilidades de locomoção dos turistas nativos entre as fronteiras estaduais, além de oferecer preços convidativos nas atrações e em cidades do circuito Além disso, o desenvolvimento dos negócios de turismo em uma região estimula o crescimento das empresas que atuam em toda a indústria turística hotelaria, gastronomia, agências de viagens, parques temáticos, aviação, transporte rodoviário, entre outros segmentos. Mais informações podem ser obtidas por meio da elaboração de um plano de negócios.</apresentacao> <localizacao>a localização representa uma decisão muito importante para uma empresa de locação de equipamentos. Embora na maioria das vezes o atendimento seja realizado em local indicado pelo cliente, a empresa deve ter um pequeno escritório para a recepção de clientes e discussão de propostas e orçamentos. Alguns detalhes devem ser observados na escolha do imóvel: O imóvel atende às necessidades operacionais referentes à localização, capacidade de instalação do negócio, possibilidade de expansão, características da vizinhança e disponibilidade dos serviços de água, luz, esgoto, telefone e internet? O ponto é de fácil acesso, possui estacionamento para veículos, local para carga e descarga de mercadorias e conta com serviços de transporte coletivo nas redondezas? O local está sujeito a inundações ou próximo a zonas de risco? O imóvel está legalizado e regularizado junto aos órgãos públicos municipais?... </ideia> 12
4.1.4 Obter Detalhes Tópico Tipo: GET Path: /rest/ideiasv2/{identificadorideia}/topico/{topico} Retorna os detalhes dos tópicos a partir do identificador da Ideia de Negócio. Atributos de entrada Nome Descrição Tipo Obrigatório {identificadordaideia} Identificador da Ideia de Negócio SIM {tópico} Tópico da ideia a se obter os detalhes SIM Atributos retornados Nome Descrição Tipo conteudo Conteúdo do tópico consultado Exemplo de XML de retorno HTTP/1.1 200 OK X-UA-Compatible: IE=8 Content-Length: 2076 Content-Type: application/xml; charset=utf-8 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <topico> <identificador>76b940ed20947abd832579980068d247</identificador> <conteudo>agência de turismo receptivo</conteudo> <topico>titulo</topico> </topico> 4.1.5 Busca simples de Ideias de Negócios Tipo: POST Path: /rest/ideiasv2/buscasimples Exemplo de requisição: /rest/ideiasv2/buscasimples?pagina=0&itensporpagina=10 Método que busca ideias de negócios à partir de uma palavra-chave. QueryParams: pagina: determina o número da página atual a ser retornada na busca(paginação de resultados); 13
itensporpagina: determina a quantidade de itens que devem ser retornados por página no resultado da busca. Atributos de entrada Nome Descrição Tipo Obrigatório Exemplo de dado palavrachave Palavra-chave a ser utilizada como critério da Sim padaria busca. pagina Número da página atual a ser retornada no resultado da busca. Se não for informado um valor para este atributo, o método Integer Não 1 retornará somente a primeira página do resultado da busca. itensporpagina Define a quantidade de itens que devem ser retornados por página no resultado da busca. Caso não seja informado um valor para este atributo, o método retornará automaticamente 20 resultados por página. Integer Não 10 Exemplo de XML de entrada <parametrosbusca> <palavrachave>abelha</palavrachave> </parametrosbusca> Atributos retornados Nome Descrição Tipo Exemplo de dado totalresultados Total de resultados encontrados no resultado da busca(total geral) Inteiro 10245 14
paginaatual totalitensporpagina listaidentificadoresidei asnegocio Número da página atual que está sendo exibida no resultado da busca Número total de itens a serem exibidos por página Lista de Títulos e Identificadores das Ideias de Negócio Inteiro 5 Inteiro 10 Lista de objetos listaidentificadoreside iasnegocio titulo Título da Ideia titulo identificadorideia Código identificador único da Ideia de Negócio. titulo Título da Ideia Exemplo de XML de retorno HTTP/1.1 200 OK X-UA-Compatible: IE=8 Content-Length: 2076 Content-Type: application/xml; charset=utf-8 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <resultadobusca> <totalresultados>7</totalresultados> <paginaatual>0</paginaatual> <totalitensporpagina>10</totalitensporpagina> <docs> <doc> <identificadorideia>c218f7151ce3fefb832580a6005b1708</identificadorideia> <titulo>criação de abelhas</titulo> </doc> <doc> <identificadorideia>bfd1b05e1b9ec43183257d04007500f5</identificadorideia> <titulo>cultivo de flores</titulo> </doc> <doc> <identificadorideia>62f699fb8677c4b383257d4300521be6</identificadorideia> <titulo>fábrica de doces e geléias</titulo> </doc> <doc> <identificadorideia>91845c92913778d9832579f800695151</identificadorideia> <titulo>fábrica de velas</titulo> </doc> <doc> <identificadorideia>7e148907e3dbd6b583257a1a004bc6c5</identificadorideia> <titulo>lanchonete</titulo> </doc> 15
<doc> <identificadorideia>6dd8559848589720832579c300695434</identificadorideia> <titulo>merenda escolar</titulo> </doc> <doc> <identificadorideia>55ff1dc59cd43a858325801e004ec595</identificadorideia> <titulo>produção de mel</titulo> </doc> </docs> </resultadobusca> 4.1.6 Busca avançada de ideias de Negócio Tipo: POST Path: /rest/ideiasv2/buscaavancada Exemplo de requisição: /rest/ideiasv2/buscaavancada?pagina=0&itensporpagina=10 Método que busca ideias de negócio à partir um ou mais atributos pré-determinados. É importante ressaltar que de todos os atributos utilizados para a busca, nenhum é obrigatório, mas, é obrigatório o preenchimento de pelo menos um dos atributos. QueryParams: pagina: determina o número da página atual a ser retornada na busca(paginação de resultados); itensporpagina: determina a quantidade de itens que devem ser retornados por página no resultado da busca. Atributos de entrada Nome Descrição Tipo Obrigatório Exemplo de dado titulo Título do documento a ser buscado. Não Casa lotérica assunto Assunto relacionado aos documentos a serem Não finanças buscados autor Autor de uma ideia Não - pagina Número da página atual a ser retornada no resultado Integer Não 1 16
itensporpagina da busca. Se não for informado um valor para este atributo, o método retornará somente a primeira página do resultado da busca. Define a quantidade de itens que devem ser retornados por página no resultado da busca. Caso não seja informado um valor para este atributo, o método retornará automaticamente 20 resultados por página. Integer Não 10 Exemplo de XML de entrada <parametrosbusca> <titulo>abelha</titulo> </parametrosbusca> Atributos retornados Nome Descrição Tipo Exemplo de dado totalresultados paginaatual totalitensporpagina listaidentificadoresidei asnegocio Total de resultados encontrados no resultado da busca(total geral) Número da página atual que está sendo exibida no resultado da busca Número total de itens a serem exibidos por página Lista de Títulos e Identificadores das Ideias de Negócio Inteiro 10245 Inteiro 5 Inteiro 10 Lista de objetos listaidentificadoreside iasnegocio titulo Título da Ideia titulo identificadorideia Código identificador único da Ideia de Negócio. 17
Exemplo de XML de retorno HTTP/1.1 200 OK X-UA-Compatible: IE=8 Content-Length: 2076 Content-Type: application/xml; charset=utf-8 <?xml version="1.0" encoding="utf-8" standalone="yes"?> <resultadobusca> <totalresultados>1</totalresultados> <paginaatual>0</paginaatual> <totalitensporpagina>10</totalitensporpagina> <docs> <doc> <identificadorideia>c218f7151ce3fefb832580a6005b1708</identificadorideia> <titulo>criação de abelhas</titulo> </doc> </docs> </resultadobusca> 18