Manual API Sebrae

Transcrição

Manual API Sebrae

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
Dados
Dados
Dados
Dados
Dados
CAMADA DE ACESSO A DADOS
API iHUB
WEB SERVICES
CLIENTES
WEB SERVICES
API iHUB
WEB SERVICES
API iHUB
WEB SERVICES
API iHUB
WEB SERVICES
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.).
Atributos de entrada
Nome
descTitulo
Descrição
Descrição total ou parcial do título
da Ideia de Negócio
Tipo
Obrigatório
String
SIM
String
SIM
Código ou APP ID que identifica
identificadorAplicativo
quem está chamando o serviço.
(Aplicativo do desenvolvedor que
utiliza o serviço)
Atributos retornados
Nome
listaIdentificadoresIdeiasNegocio
titulo
identificadorIdeia
Descrição
Lista de Títulos e Identificadores
das Ideias de Negócios
Título da Ideia de Negócio
Código identificador único da
Ideia.
Tipo
Lista de objetos
String
String
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.).
Nome
titulo
identificadorSetor
Título
Descrição
Tipo
Obrigatório
do setor (descrição)
String
SIM
String
SIM
Código identificador único do setor
/ tópico.
Nome
titulo
identificadorSetor
Título
Descrição
Tipo
do setor (descrição)
String
/ tópico.
String
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.
Nome
Descrição
Tipo
Obrigatório
identificadorSetor
Identificador do setor
String
SIM
String
SIM
utiliza o serviço)
Nome
Descrição
das Ideias
Tipo
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
Nome
Descrição
Tipo
Obrigatório
assunto
Assunto a ser consultado
String
SIM
String
SIM
utiliza o serviço)
Nome
Descrição
Tipo
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.
Nome
Descrição
Tipo
Obrigatório
identificadorIdeia
Identificador da Ideia de Negócio
String
SIM
String
SIM
q u e m está chamando o serviço.
(Aplicativo d o desenvolvedor que
utiliza o serviço)
Nome
Descrição
Tipo
apresentacaoNegocio
Apresentação da Ideia de Negócio
String
localizacao
Localização da Ideia de Negócio
String
exigenciaLegal
Exigências Legais específicas da
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
automacao
canaisDistribuicao
Organização do processo produtivo
Automações da Ideia de Negócio
Canais de Distribuição da Ideia de
Negócio
String
String
String
Investim entos
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
divulgacao
informacoesFiscaisTributarias
eventos
Diversificação da Agregação de Valor
Divulgação da Ideia de Negócio
Informações Fiscais da Ideia de
Negócio
Eventos da Ideia de Negócio
String
String
String
String
12
entidadesGeral
normasTecnicas
Entidades Gerais da Ideia de Negócio
String
Normas Técnicas da Ideia de
String
Negócio
glossario
Glossário da Ideia de Negócio
String
dicasNegocio
Dicas da Ideia de Negócio
String
caracteristicasEspecificasEmpree
Características específicas para o
endedor
empreendedor da Ideia de Negócio
bibliografiaComplementar
tituloIdeia
String
Bibliografia Complementar da Ideia
String
de Negócio
String
5.1.6 Obter Detalhes Tópico
Webmethod: obterTopicoDaIdeia
Retorna os detalhes dos tópicos a partir do identificador da Ideia de Negócio.
Nome
Descrição
Tipo
Obrigatório
identificadorDaIdeia
String
SIM
String
SIM
Enum
SIM
utiliza o serviço)
topico
Tópico da Ideia de Negócio a se
obter os detalhes
Nome
Descrição
Tipo
conteudo
Conteúdo do tópico consultado
String
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
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
{nome}
Descrição
Descrição total ou parcial do título
Tipo
Obrigatório
String
SIM
Nome
titulo
identificadorIdeia
Descrição
das Ideias de Negócio
Título da Ideia
Código identificador único da
Ideia de N egócio.
Tipo
Lista de objetos
String
String
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
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
Tipo
Obrigatório
{nome}
Descrição total ou parcial do setor
String
SIM
Nome
Descrição
Tipo
titulo
Título do setor (descrição)
String
identificadorSetor
String
/ 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.
Nome
Descrição
Tipo
Obrigatório
{identificadorsetor}
Identificador do setor
String
SIM
Nome
Descrição
das Ideias de Negocio
Tipo
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.
Nome
Descrição
Tipo
Obrigatório
{assunto}
Assunto a ser consultado
String
SIM
Nome
listaIdeiasNegocio
Descrição
Tipo
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.
Nome
Descrição
Tipo
Obrigatório
{identificadorIdeia}
String
SIM
Nome
Descrição
Tipo
apresentacaoNegocio
Apresentação da Ideia de Negócio
String
localizacao
Localização da Ideia de Negócio
String
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
automacao
canaisDistribuicao
Organização do processo produtivo
Automações da Ideia de Negócio
Canais de Distribuição da Ideia de
Negócio
String
String
String
Investim entos
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
divulgacao
informacoesFiscaisTributarias
eventos
Diversificação da Agregação
de
Valor da Ideia de Negócio
Divulgação da Ideia de Negócio
Informações Fiscais da Ideia de
Negócio
Eventos da Ideia de Negócio
String
String
String
String
17
entidadesGeral
normasTecnicas
Entidades Gerais da Ideia de Negócio
String
Normas Técnicas da Ideia de
String
Negócio
glossario
Glossário da Ideia de Negócio
String
dicasNegocio
Dicas da Ideia de Negócio
String
caracteristicasEspecificasEmpree
Características específicas para o
endedor
empreendedor da Ideia de Negócio
bibliografiaComplementar
tituloIdeia
String
Bibliografia Complementar da Ideia
String
de Negócio
String
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.
Nome
Descrição
Tipo
Obrigatório
{identificadorDaIdeia}
String
SIM
String
SIM
{tópico}
Tópico da ideia a se obter os
detalhes
Nome
Descrição
Tipo
conteudo
Conteúdo do tópico consultado
String
18

Manual API Sebrae

Transcrição

Documentos relacionados

programação

¢¡¤£¦¥ §¢¨¦©

Arquivos de Textos no C - Básico

Изтегляне - Alagoas em Dados e Informações

Perl para Bioinformá+ca

Nova aba

Francisco Souza @franciscosouza

Técnico em Tecnologia da Informação - Concursos

Polimorfismo

curso php prático

Apêndice B - Java Noroeste

Isipag Documentation

Classe Correntista FormataData usando Calendar

API de Integração