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

5

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

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

BANCO DE DADOS

Dados

Dados

Dados

Dados

Dados

CAMADA DE ACESSO A DADOS

API iHUB

API iHUB

API iHUB

API iHUB

API iHUB

WEB SERVICES

WEB SERVICES

WEB SERVICES

WEB SERVICES

WEB SERVICES

WEB SERVICES

CLIENTES

6

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.

7

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.

8

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 String SIM

Atributos retornados

Nome Descrição Tipo

titulo Título do setor (descrição) String

identificadorSetor Código identificador único do setor

/ tópico. String

Exemplo de XML de retorno

HTTP/1.1 200 OK X-UA-Compatible: IE=8 Content-Length: 2076

9

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 String 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>

10

</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 String SIM

Atributos retornados

Nome Descrição Tipo

apresentacaoNegocio Apresentação da Ideia de Negócio String

localizacao Localização da Ideia de Negócio String

11

exigenciaLegal Exigências Legais específicas da

Ideia de Negócio String

estrutura Estrutura Ideia de Negócio String

pessoal Pessoal da Ideia de Negócio String

equipamentos Equipamentos da Ideia de Negócio String

materiaPrima Matérias Primas String

organizacaoProcessoProdutivo Organização do processo produtivo

da Ideia de Negócio String

automacao Automações da Ideia de Negócio String

canaisDistribuicao Canais de Distribuição da Ideia de

Negócio String

Investimentos Informações Fiscais e Tributárias String

capitalGiro Capital de Giro da Ideia de Negócio String

custos Custos da Ideia de Negócio String

diversificacaoAgregacaoValor Diversificação da Agregação de

Valor da Ideia de Negócio String

divulgacao Divulgação da Ideia de Negócio String

informacoesFiscaisTributarias Informações Fiscais da Ideia de

Negócio String

eventos Eventos da Ideia de Negócio String

entidadesGeral Entidades Gerais da Ideia de Negócio String

normasTecnicas Normas Técnicas da Ideia de

Negócio String

glossario Glossário da Ideia de Negócio String

dicasNegocio Dicas da Ideia de Negócio String

caracteristicasEspecificasEmpree

endedor

Características específicas para o

empreendedor da Ideia de Negócio String

bibliografiaComplementar Bibliografia Complementar da Ideia

de Negócio String

tituloIdeia Título da Ideia de Negócio String

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

12

<?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>

13

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 String SIM

{tópico} Tópico da ideia a se obter os

detalhes String SIM

Atributos retornados

Nome Descrição Tipo

conteudo Conteúdo do tópico consultado String

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);

14

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

busca.

String Sim padaria

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

retornará somente a

primeira página do

resultado da busca.

Integer Não 1

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

15

paginaAtual

Número da página atual

que está sendo exibida no

resultado da busca

Inteiro 5

totalItensPorPagina Número total de itens a

serem exibidos por página Inteiro 10

listaIdentificadoresIdei

asNegocio

Lista de Títulos e

Identificadores das Ideias

de Negócio

Lista de objetos listaIdentificadoresIde

iasNegocio

titulo Título da Ideia String titulo

identificadorIdeia Código identificador único

da Ideia de Negócio. String

titulo Título da Ideia String

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>

16

<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. String Não Casa lotérica

assunto

Assunto relacionado aos

documentos a serem

buscados

String Não finanças

autor Autor de uma ideia String Não -

pagina Número da página atual a

ser retornada no resultado Integer Não 1

17

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.

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> <titulo>abelha</titulo> </parametrosbusca>

Atributos retornados

Nome Descrição Tipo Exemplo de dado

totalResultados

Total de resultados

encontrados no resultado

da busca(total geral)

Inteiro 10245

paginaAtual

Número da página atual

que está sendo exibida no

resultado da busca

Inteiro 5

totalItensPorPagina Número total de itens a

serem exibidos por página Inteiro 10

listaIdentificadoresIdei

asNegocio

Lista de Títulos e

Identificadores das Ideias

de Negócio

Lista de objetos listaIdentificadoresIde

iasNegocio

titulo Título da Ideia String titulo

identificadorIdeia Código identificador único

da Ideia de Negócio. String

18

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>