Resumo
Este artigo tem por finalidade a anlise e projeto para desenvolvimento de uma API de servios
para disponibilizar um ambiente de marketplace integrado a uma plataforma de e-commerce.
Nesse documento sero demonstrados os conceitos de e-commerce e marketplace, bem como as
tcnicas de integrao para a implementao de uma API de servios. O levantamento dos
requisitos necessrios foi realizado na empresa de e-commerce Magamobi E-Business S/A,
situada na cidade de Rio do Sul-SC, que tem como principal foco de vendas celulares e
smartphones. O resultado uma API completa, analisada e desenhada dentro dos padres e
melhores prticas, com todos os recursos e servios necessrios para a integrao entre lojistas e
marketplace. Utilizando essa abordagem no h necessidade do marketplace desenvolver outras
ferramentas, pois a API contempla todas as funcionalidades.
1. Introduo
A rea de e-commerce vem crescendo constantemente, segundo o E-bit (2015) o ano de 2014
apresentou resultado bastante positivo no comrcio eletrnico brasileiro, tendo superado mais
uma vez a expectativa inicial para o faturamento do setor e registrado crescimento de 24% em
relao a 2013. Comprar pela internet est ficando cada vez mais comum como tambm mostra o
E-bit (2015) ao mencionar que 51,5 milhes de consumidores fizeram compra pela Internet no
ltimo ano, sendo 10,2 milhes de estreantes. Ter uma loja online no mais somente para
grandes empresas, mas cada vez mais pequenas e mdias empresas vm buscando espao nesse
segmento. Nessa busca por espao na internet ter somente uma loja virtual no mais suficiente,
preciso encontrar novos meios de vender, novos canais.
Universidade do Estado de Santa Catarina
Centro de Educao Superior do Alto Vale do Itaja
Nesse contexto surge o termo de marketplace (ou e-marketplace). HUNGRIA (2014) descreve
de maneira simples que os marketplaces nada mais so do que shopping centers virtuais que
renem ofertas de diferentes fornecedores, despontam como uma tendncia entre grandes marcas
do varejo. Acompanhando esse movimento, pequenos e mdios empresrios pegam carona na
visibilidade e capacidade de atrair trfego de empresas como Magazine Luiza, Walmart, Extra,
para expandir suas vendas. O marketplace espao atraente para o consumidor pois ali se
encontra de tudo, diz Pedro Guasti, diretor executivo da E-bit.
Com isso o marketplace se torna uma forma de expandir a visibilidade de seus produtos e
sua marca. H vantagens tanto para a empresa que est disponibilizando como tambm para o
lojista que usa o espao (SEBRAE, 2015). As integraes com o marketplace so feitas via API
(Application Programming Interface) seguindo padres REST, disponibilizadas pelo prprio e-
commerce (B2W - Companhia Digital, 2014; Extra.com.br, 2014; Walmart.com.br, 2014).
Assim como outros grupos de comercio eletrnico, que dispe o recurso de marketplace em
seus sites, o grupo Magamobi E-business S/A, fundado em 2010 e que tem como principal portal
de vendas o site www.cissamagazine.com.br tambm deseja a criao de uma API para
disponibilizar para que outros lojistas venham a vender seus produtos dentro dos sites da
empresa.
O trabalho est organizado da seguinte forma: a primeira parte se destina a reviso de
conceitos tericos referentes a assuntos relevantes ao trabalho, demonstrando conceitos do ramo
de negcio, e-commerce e marketplace. Ainda nessa primeira parte so apresentados os
conceitos tecnolgicos envolvidos para a criao de uma API para marketplace, abordando
definies de REST, ROA, JSON e boas prticas para definio de API. A segunda parte o
desenvolvimento do projeto, descrevendo as solues e os servios necessrios para a API,
baseando-se nas regras e requisitos coletados (disponveis no Apndice A). O detalhamento das
classes utilizadas, com exemplos em JSON esto disponveis no Apndice B.
2. Fundamentao Terica
Neste tpico so apresentados os fundamentos e assuntos utilizados como base para realizao
deste trabalho. Os dois primeiros tpicos so referentes aos conceitos de negcio, nos tpicos
seguintes abordado os conceitos de tecnolgicos baseados principalmente no livro RESTful
Servios Web de RICHARDSON e RUBY (2007).
2.1 E-commerce
2.2 Marketplace
O conceito de marketplace nasceu nos Estados Unidos, com o lanamento do e-Bay, em 1995,
inicialmente um site de leiles, mas que evoluiu para uma plataforma de ofertas de produtos de
diversas marcas. Posteriormente, a Amazon, que comeou como uma loja virtual, formalizou o
conceito quando tornou seus concorrentes parceiros de venda em seu site. (HUNGRIA, 2014)
GIBERTONI (2014) define que marketplace um ambiente do varejo online onde mltiplas
empresas ofertam e comercializam os seus produtos e servios, a transao processada pelo
operador do prprio marketplace e os benefcios atingem a todos. VILHA (2002) descreve como
"uma nova e vantajosa forma de conduzir negcios".
O SEBRAE (2015) relata que o grande diferencial do marketplace ter vantagens para todos
os envolvidos: consumidor, lojista e operador do marketplace.
O pequeno varejista precisa de trfego para sua loja virtual, fator crucial para que ele
consiga vender. Sendo pequeno e pouco conhecido, o marketplace fornece respaldo de
marketing e publicidade e este trfego de potenciais clientes. Isso significa aumento da
visibilidade dos produtos e menor investimento em marketing para alavancar as
vendas.
Para o operador do marketplace, este modelo de negcio impulsiona as suas receitas
atravs do comissionamento recebido pelas vendas; a variedade de produtos ofertados
estimulam a compra; o ticket mdio da loja aumenta; e mais fcil fidelizar os
clientes.
J o consumidor encontra produtos de diversos segmentos em um s local, agregando
valor experincia de compra; tem acesso a preos mais competitivos; pode comprar
em diferentes lojas, pagando pelos produtos em uma nica transao.
O marketplace no redireciona os consumidores ao site de terceiros, e por concentrar toda a
experincia na sua plataforma, o consumidor torna-se um cliente do marketplace, j que com
ele que se relaciona diretamente, mesmo que o lojista terceiro realize a entrega do produto. O
marketplace oferece o canal de vendas, trfego, mdia, e outros servios e, em troca, fica com
uma remunerao paga pelo lojista (que pode ser uma comisso sobre pedidos e/ou uma taxa fixa
mensal). A fonte de renda do marketplace , ento, atrelada venda dos lojistas. (GRANDES,
2013)
No Brasil, o Extra.com.br foi o primeiro e-commerce a adotar o Marketplace em seu modelo
de negcios, criando o nico Shopping Mercado do Brasil (Extra.com.br, 2014). Seus milhares
de visitantes mensais encontram produtos vendidos por lojistas de todo o pas, de diferentes
portes e categorias.
Entender o HTTP e suas partes o primeiro passo para construo de qualquer webservice.
Conforme RICHARDSON e RUBY (2007), O HTTP um protocolo baseado em documentos,
no qual o cliente coloca um documento em um envelope e envia-o para o servidor. O servidor
retorna, colocando um documento de resposta tambm em um envelope e envia-o para o cliente.
O HTTP tem padres rigorosos para a aparncia dos envelopes, mas no cuida muito do que est
dentro.
Partes da solicitao HTTP:
Universidade do Estado de Santa Catarina
Centro de Educao Superior do Alto Vale do Itaja
Mtodo HTTP (que no REST poder ser chamado de verbo HTTP ou ao HTTP)
indica como o cliente espera que o servidor processe este envelope.
Path (nos termos da metfora do envelope, o path o endereo do envelope), tambm
chamado de URI.
Cabealhos da solicitao - so bits de metadados: os pares de chave-valor que agem
como adesivos colocados no envelope.
Corpo da entidade, tambm chamado de documento ou representao.
A resposta HTTP tambm um documento em um envelope. A resposta pode ser dividida em
trs partes:
Cdigo da resposta HTTP: este cdigo numrico informa ao cliente se sua solicitao
foi bem ou insuficiente e como o cliente este envelope e seu contedo.
Cabealhos da resposta: exatamente como os cabealhos da solicitao, so adesivos
informativos colocados no envelope. O mais importante desses adesivos o Content-
Type que fornece o tipo de mdia do corpo da entidade. Ex: text/html, application/xml.
Corpo da entidade e representao.
Todos os servios web usam o HTTP, mas utilizam-no de maneiras diferentes. Uma
solicitao para um servio web REST coloca as informaes do mtodo no mtodo HTTP e as
informaes de escopo na URI.
Roy Fielding, o verdadeiro pai do REST, afirma em sua dissertao de PhD que o REST
"enfatiza a escalabilidade das interaes do componente, a generalidade das interfaces, a
implementao independente de componentes e componentes intermedirios para reduzir a
latncia da interao, forar a segurana e encapsular sistemas legados" (consulte Recursos). A
construo de sistemas RESTful no difcil, e os sistemas so altamente escalveis, enquanto
so fracamente acoplados aos dados subjacentes; eles tambm alavancam perfeitamente o
armazenamento em cache. (GLOVER, 2008)
Universidade do Estado de Santa Catarina
Centro de Educao Superior do Alto Vale do Itaja
Outras boas prticas de uma API REST so descritas por MULLOY (2002),
O princpio nmero um do design RESTful : manter simples as coisas simples.
Mantenha sua URL base simples e intuitiva. Um design simples e intuitivo de sua
URL base faz o uso de sua API fcil.
Use duas URLs de base por recurso. A primeira URL para uma coleo; a segunda
para um elemento especfico na coleo. Ex: /dogs e /dogs/1234.
Mantenha verbos fora de seus URLs de base.
Use MTODOS de HTTP para operar nas colees e elementos. Com nossos dois
recursos (/dogs e /dogs/1234) e os quatro verbos HTTP, temos um conjunto rico de
capacidade que intuitivo para o desenvolvedor.
Use nomes dos recursos no plural. Voc pode escolher substantivos singular ou no
plural para seus nomes de recursos. Voc ver APIs populares usarem ambos. Porm,
tendo em conta que a primeira coisa que a maioria das pessoas provavelmente fazem
com uma API RESTful um GET, ns pensamos que ele l mais facilmente e mais
intuitivo de usar substantivos no plural. Mas, acima de tudo, evitar um modelo misto
em que voc usa singular para alguns recursos, plural para os outros. Ser coerente
permite que os desenvolvedores de prever e adivinhar as chamadas de mtodo como
eles aprendem a trabalhar com sua API.
Resposta parcial: permite dar aos desenvolvedores apenas a informao de que
necessitam.
Paginao: Use limit e offset para tornar mais fcil para os desenvolvedores para
paginar objetos.
Use JSON como padro.
Siga convenes JavaScript para nomear atributos:
o Use a capitalizao medial (aka CamelCase), Ex: tipoContato.
o Use letras maisculas ou minsculas, dependendo do tipo de objeto.
Seguindo as prticas e orientaes desses autores, temos um bom embasamento para a criao
de uma API funcional e intuitiva.
Esta seo dedica-se ao desenvolvimento do trabalho. Iniciada pela coleta de regras de negcio e
requisitos e a separao do resultado em grupos. Logo aps apresentada uma viso geral da
API, onde so mostrados conceitos que vo abranger todos os recursos. Por fim so detalhados
os recursos e seus servios que a API vai disponibilizar, com diagramas das classes de domnio
das representaes de entrada e sada dos mesmos.
Aps o levantamento das regras e requisitos, possvel identificar que o projeto pode ser
dividido em 4 partes:
Gerencial do marketplace: Parte de sistema onde o marketplace ir gerenciar os lojistas ativos,
suas credenciais de acesso e far a avaliao dos anncios enviados e posteriormente a
associao e categorizao do anuncio afim de disponibiliza-lo para venda nos sites do
marketplace. Tambm no gerencial sero feitos o cadastramento dos ciclos de vendas e o
percentual de comisso que o marketplace ir receber por venda.
API: Parte central da integrao, ela ser o meio de integrao entre o lojista e marketplace,
por meio dela o lojista far a gesto de seus anncios e pedidos. A API vai disponibilizar todos
os recursos e funcionalidades necessrios para o lojista. Com base nos passos 1 e 2 descritos por
RICHARDSON e RUBY (2007) e apresentados nesse artigo, podemos separar nossa API em 4
recursos principais: anncios, pedidos, atendimentos e relatrios. Os recursos, e suas operaes,
sero descritos posteriormente.
API lojista: O lojista tambm deve implementar alguns servios para o marketplace invocar.
O servio essencial o de clculo de frete para a venda dos anncios. O outro servio o call-
back das notificaes que o marketplace envia ao lojista, esse servio opcional. Esses servios
tambm devero seguir os padres REST e ROA. A funo do marketplace nessa parte apenas
documentar as representaes de entrada e sada esperadas.
Alteraes no site: So as alteraes necessrias para que os anncios do lojista sejam listados
no site.
O foco do presente documento se concentra na rea de integraes via API.
Nesse tpico ser abordado aspectos comuns a todos os recursos da API que est sendo proposta.
Idioma das representaes e servios: Toda a API (servios, classes de domnio das
representaes de entrada e sada e seus respectivos atributos) foram modelados no idioma
Universidade do Estado de Santa Catarina
Centro de Educao Superior do Alto Vale do Itaja
Conectividade: Quando houver um atributo no objeto que uma referncia a algum outro
recurso, utilizado o objeto Link (Figura 1), contendo o identificador do recurso associado e sua
URI.
Universidade do Estado de Santa Catarina
Centro de Educao Superior do Alto Vale do Itaja
Esse recurso o primeiro passo da integrao, para vender dentro dos sites do marketplace
necessrio o envio/cadastro dos dados do anncio (produto). Esses dados sero avaliados pelo
marketplace e posteriormente, se tudo estiver correto, sero disponibilizados para a venda. Seria
algo como perguntar: marketplace, vende esse produto para mim? Na figura 2, apresentado o
diagrama das classes de domnio utilizadas nesse recurso, so as representaes de entrada dos
servios. Os atributos das classes detalhados, e exemplo da representao JSON, podem ser
encontrados no Apndice B desse documento.
Atualizao do anncio: Esse o servio invocado pelo lojista para atualizar todos os dados
do anncio. Acessvel enquanto o anuncio estiver na fase inicial de cadastro, principalmente para
corrigir informaes cadastrais. Aps o anncio aprovado o servio ir retornar erro 403.
Atualizao de preo do anncio: Esse o servio invocado pelo lojista para atualizar as
informaes de preo do anncio.
Universidade do Estado de Santa Catarina
Centro de Educao Superior do Alto Vale do Itaja
Atualizao de estoque do anncio: Esse o servio invocado pelo lojista para atualizar a
quantidade disponvel para venda do anncio.
Ativao e desativao do anncio: Esse o servio invocado pelo lojista para ativar o
desativar a venda do anncio. Anncios desativados no so apresentados no site do
marketplace.
Embora parea redundante ter 4 servios para atualizao do anuncio, isso necessrio e
comum entre as APIs de marketplace.
Consulta geral de anncios: Esse o servio invocado pelo lojista para consultar a lista dos
seus anncios no marketplace. O servio segue o padro geral de consultas de listagem.
Consulta de anncio: Esse o servio invocado pelo lojista para consultar os dados de um
anncio em especfico, tendo como referncia seu identificador. Caso o recurso no exista ser
retornado erro 404.
Esse recurso o segundo passo da integrao. Aps os anncios estarem a venda no site do
marketplace, necessrio que haja uma simulao do frete a ser pago pelo envio. O clculo de
frete um servio que o lojista deve implementar conforme as orientaes e padronizaes
definidas pelo marketplace. enviado para o lojista as informaes dos itens e quantidades, e o
CEP de destino da mercadoria (objeto FreightPreview). O lojista deve retornar os servios
disponveis de entrega, seus valores e prazo de entrega (objeto FreightPreviewResponse). Na
figura 3, apresentado o diagrama das classes de domnio utilizadas nesse recurso, so as
representaes de entrada e sada do servio. Os atributos das classes detalhados, e exemplo da
representao JSON, podem ser encontrados no Apndice B desse documento.
Caso ocorra algum erro, o lojista deve retornar um cdigo de resposta HTTP de erro, e
retornar na representao um objeto Error, nos mesmos moldes dos servios disponibilizados
pelo marketplace.
Esse recurso o terceiro passo da integrao. Os anncios enviados foram vendidos pelo
marketplace, gerando novos pedidos. E o lojista precisa consulta-los e importa-los para seu
sistema e dar continuidade aos pedidos aprovados (pagos). Num fluxo normal, o pedido passar
pelas seguintes situaes: novo, aprovado (pago), em transporte, entregue. O pedido tambm
pode vir a ser cancelado, caso no seja identificado o pagamento ou haja solicitao de
cancelamento. Na figura 4, apresentado o diagrama das classes de domnio utilizadas nesse
recurso, so as representaes de sada do servio. Os atributos das classes detalhados, e
exemplo da representao JSON, podem ser encontrados no Apndice B desse documento.
Universidade do Estado de Santa Catarina
Centro de Educao Superior do Alto Vale do Itaja
Consulta de pedido: Esse o servio invocado pelo lojista para consultar os dados de um
pedido em especfico, tendo como referncia seu identificador. Caso o recurso no exista ser
retornado erro 404.
Aps ser feita a importao do pedido no sistema do lojista, o mesmo deve dar andamento aos
pedidos aprovados (pagos). O lojista deve manter atualizado no marketplace o andamento do
pedido. Na figura 5, apresentado o diagrama das classes de domnio utilizadas para a
atualizao do status do recurso, so as representaes de entrada do servio. Os atributos das
classes detalhados, e exemplo da representao JSON, podem ser encontrados no Apndice B
desse documento. Os servios disponveis para a atualizao so descritos logo abaixo.
Universidade do Estado de Santa Catarina
Centro de Educao Superior do Alto Vale do Itaja
Atualizao do pedido para em transporte: Esse o servio invocado pelo lojista para
notificar o marketplace da entrega dos itens do pedido a transportadora. Nele sero enviados os
dados de nota fiscal e dados de rastreamento na transportadora. Somente pedidos aprovados
(pagos) podem ser atualizados para em transporte.
Atualizao do pedido para entregue: Esse o servio invocado pelo lojista para notificar o
marketplace da entrega dos itens do pedido ao cliente. Somente pedidos em transporte podem ser
atualizados para entregue.
Cancelamento do pedido: Esse o servio invocado pelo lojista para notificar o marketplace
do cancelamento do pedido. Somente pedidos novos ou aprovados podem ser cancelados.
Consulta geral dos atendimentos: Esse o servio invocado pelo lojista para consultar os
atendimentos do lojista no marketplace. O servio segue o padro geral de consultas de listagem.
Inserir mensagem no atendimento: Esse o servio invocado pelo lojista para inserir uma
mensagem (resposta) no atendimento.
Finalizar atendimento: Esse o servio invocado pelo lojista para encerrar o atendimento.
Aps o atendimento finalizado no mais possvel adicionar mensagens.
Consulta dos repasses financeiros: Esse o servio invocado pelo lojista para consultar os
repasses financeiros feitos pelo marketplace. Cada repasse corresponde a um ciclo de pedidos. O
servio segue o padro geral de consultas de listagem.
Consulta dos movimentos os repasse financeiro: Esse o servio invocado pelo lojista para
consultar o detalhamento das movimentaes que compreendem um repasse financeiro
especfico. O servio segue o padro geral de consultas de listagem.
4. Trabalhos correlatos
Verso 1: Assim como a verso 1 da B2W, apresenta recursos para manipular anncios e os
pedidos. A diferena dessa API em relao verso 1 da B2W o recurso de permitir enviar mais
de um anuncio na mesma requisio POST, mandando vrios itens dentro de um array. Os dados
dessa requisio so compactados no formato GZip. O clculo de frete pode ser feito via planilha
ou por call-back configurado. Existe call-back para notificao das alteraes de status de
anncios e pedidos. A forma de autenticao utilizada prpria e se baseia em um par de chaves
enviado no cabealho de cada requisio. A documentao est disponvel em
https://desenvolvedores.extra.com.br/api-portal/docs/apilojistav1/main/index.html.
Verso 2: Ao contrrio da B2W, a segunda verso da API do Extra foi completamente
redesenhada: alterou-se o mtodo de autenticao para oAuth 2.0 e todas as classes de domnio
dos servios foram remodeladas. Todo o contrato dos servios foi quebrado, necessitando por
parte dos lojistas uma implementao praticamente do zero. As principais melhorias foram
adicionadas a informaes do pedido o site de origem, e o status atual do pedido. Na parte dos
anncios foi disponibilizado o servio de ativao/desativao do anuncio. Outra novidade o
fato de permitir selecionar os atributos retornados nas consultas de listagem. O gerenciamento de
um novo recurso importante foi adicionado: os atendimentos ao cliente, possibilitando consultar
e responder eles via API. A documentao est disponvel em
http://desenvolvedores.cnova.com/api-portal/docs/apilojista/main/index.html.
Walmart: Sua API apresenta diferenas considerveis em relao as outras estudadas. O
gerenciamento do recurso de anncios em geral semelhante aos outros marketplace, existindo
um diferencial que o todos os dados do anuncio podem ser alterados aps a aprovao do
mesmo. O grande diferencial est no recurso de pedidos, enquanto nos outros marketplace a
implementao de call-backs opcional, o Walmart exige a implementao de uma API do
lojista, com um os seguintes servios: clculo de frete, teste de conectividade, criao de pedido,
aprovao de pedido e cancelamento do pedido. Se os servios do lojista estiverem off-line, no
permitido finalizar a venda no site do marketplace. No existe servio de consulta aos dados de
pedidos. possvel enviar e retornar as representaes em formato JSON e XML. A forma de
autenticao utilizada Basic Auth. A documentao est disponvel em
http://adapter.waldev.com.br/.
Mercado Livre: Fundada em 1999, MercadoLivre uma companhia de tecnologia lder em
comrcio eletrnico na Amrica Latina. Por meio de suas principais plataformas
MercadoLivre.com e MercadoPago.com, oferece solues de comrcio eletrnico para que
pessoas e empresas possam comprar, vender, pagar, anunciar e enviar produtos por meio da
Internet. (MERCADO LIVRE, 2015).
Possui uma API bem completa e documentao vasta. Atravs da API possvel acessar
informaes de recursos de usurios, categorias dos anncios, realizar prvias dos valores
cobrados pelo anuncio e venda de um item, responder perguntas de usurios, fazer avaliao
(feedback) de compradores, gerar etiquetas de postagem (quando utilizado o Mercado Envios
como forma de postagem), entre outros. Destaque para a replicao praticamente instantnea de
qualquer alterao feita no anuncio ou pedido via API para a visualizao no site. A forma de
autenticao oAuth 2.0 e necessrio criar apps e definir quais recursos esse ter privilgio. O
usurio ao conectar deve confirmar as permisses que o app ter. A documentao est
disponvel em http://developers.mercadolibre.com/.
Todas os marketplaces acima, disponibilizam uma ferramenta denominada portal do lojista,
onde o lojista pode acompanhar seus itens e pedidos, e acessar algumas informaes que no
esto disponibilizadas na API.
Abaixo vamos realizar 2 comparativos: o primeiro expondo as implementaes dos
marketplace acimas ao padres e melhores prticas descritos no capitulo 2.7 desse artigo (Tabela
22).
Universidade do Estado de Santa Catarina
Centro de Educao Superior do Alto Vale do Itaja
Conforme mostra a tabela 23, a API proposta possui todos os principais recursos em
comparao s outras APIs avaliadas, no necessitando da implementao do portal do lojista. O
recurso de atualizao geral do anncio parcial, pois no permitido alterao geral aps o
anncio estar disponvel para venda no site.
5. Consideraes Finais
outras aplicaes utilizaro, se seus servios seguem um padro conhecido, sua utilizao por
terceiros ser facilitada.
O diferencial da soluo apresentada em relao as solues estudadas o fato de via API, o
lojista poder efetuar todas as operaes no marketplace. Para o lojista, a vantagem que tudo
pode ser integrado a sua plataforma, dentro dela ele anuncia, gerencia os pedidos, os
atendimentos, e pega o extrato para conciliao financeira, no necessitando acessar nenhum
portal do lojista para algumas pequenas operaes. Para o marketplace, a vantagem que o
mesmo no precisa realizar a implementao e manter uma aplicao portal do lojista, o tempo
e recursos gastos para manter essa aplicao podem ser utilizados para desenvolver servios.
Referncias
B2W - Companhia Digital. API Submarino Marketplace. 2014. Disponvel em: <http://api-
marketplace.submarino.com.br/docs/> Acessado em 25 de fevereiro de 2015.
E-BIT. 31 edio WebShoppers: Comrcio eletrnico cresce 24% em 2014 e maior acesso aos
smartphones ajuda a alavancar mobile commerce. 2015. Disponvel em:
<http://www.ebitempresa.com.br/clip.asp?cod_noticia=3958&pi=1/> Acessado em 24 de
fevereiro de 2015.
GOMES, Daniel Adorno. Web Services SOAP em Java: Guia prtico para o desenvolvimento
de web services em Java. So Paulo: Novatec Editora, 2009, 13.
HUNGRIA, Camila. Pegando carona nas grandes marcas. So Paulo. 2014. Disponvel em:
<http://www.dcomercio.com.br/categoria/tecnologia/pegando_carona_nas_grandes_marcas/>
Acessado em 24 de fevereiro de 2015.
Universidade do Estado de Santa Catarina
Centro de Educao Superior do Alto Vale do Itaja
MEIRA Jr., Wagner. [et al.]. Sistemas de Comrcio Eletrnico: Projeto e desenvolvimento. Rio
de Janeiro: Campus, 2002, 1.
MULLOY, Brian. Web API Design - Crafting Interfaces that Developers Love. 2012.
Disponvel em: <https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf/>
Acessado em 24 de fevereiro de 2015.
RICHARDSON, Leonard. RUBY, Sam. RESTful servios Web. Traduo Eveline Vieira e
Patricia Azeredo. Rio de Janeiro: Alta Books, 2007
VERAS, Manoel. Arquitetura de Nuvem: amazon web services (AWS). Rio de Janeiro:
Brasport, 2013, 10.
VILHA, Anapatrcia Morales. E-marketing para bens de consumo durvel. Rio de Janeiro:
Editora FGV, 2002
W3C Escritrio Brasil. Manual dos dados abertos: desenvolvedores. So Paulo: 2001.
Disponvel em: <
http://www.w3c.br/pub/Materiais/PublicacoesW3C/manual_dados_abertos_desenvolvedores_we
b.pdf> Acessado em 23 de fevereiro de 2015.
Regras de Negcio
RN-01 O lojista deve enviar para o marketplace os anncios que deseja vender. Esse anncio
passar por um processo de avaliao manual, e se tudo estiver correto, o mesmo
disponibilizado para venda ao consumidor final no site do marketplace. Caso seja reprovado, os
dados podem ser atualizados pelo lojista para posteriormente serem reavaliados.
Quando houver um parecer sobre a avaliao do anncio o lojista ser notificado.
RN-02 Anncios aprovados passam por um processo de associao/categorizao. Nesse
processo so validados os dados e verificado se j existe um anncio semelhante do
marketplace ou de outro lojista, caso exista, o anncio associado ao existente, se tornando um
novo fornecedor daquele item. Caso no exista anncio semelhante, o anncio categorizado
conforme a estrutura interna do marketplace.
RN-03 Aps o anuncio estar aprovado, permitido ao lojista alterar (sem interveno do
marketplace) as informaes de preo, estoque disponvel e se o anuncio est ativo ou no no
site.
RN-04 O valor do frete e a estimativa de entrega do anncio so de responsabilidade do
lojista.
RN-05 O lojista ser notificado quando ocorrerem novos pedidos (venda do anncio) ou
quando for identificado o pagamento dos mesmos. Aps confirmado o pagamento o lojista
dever iniciar-se o envio da mercadoria para o consumidor.
RN-06 O pedido, em seu fluxo padro, passar pelas seguintes situaes:
Novo -> Aprovado (Pago) -> Em Transporte -> Entregue.
RN-07 O pedido pode vir a ser cancelado por ambas as partes nas situaes iniciais.
O marketplace pode fazer o cancelamento automtico de um pedido novo, caso no seja
identificado o pagamento correspondente ao mesmo aps vencimento. Quando isso ocorrer o
lojista ser notificado.
O lojista pode cancelar o pedido enquanto o mesmo ainda no estiver Em Transporte. Um
motivo comum a falta do produto em estoque, por exemplo. Quando isso ocorrer o
marketplace deve ser notificado.
RN-08 Quando o pedido for enviado a transportadora, o lojista deve notificar o marketplace
que o pedido est Em Transporte, repassando as informaes de nota fiscal e rastreamento da
mercadoria. Somente permitido o registro de transporte para pedidos aprovados (pagos).
RN-09 Quando o pedido for entregue ao consumidor, o lojista deve notificar o marketplace.
Somente permitido o registro de entrega para pedidos em transporte.
RN-10 Os repasses financeiros dos pedidos ao lojista sero feitos periodicamente, obedecendo
o ciclo especificado no contrato entre as empresas. Exemplo:
Pedidos do dia 01 a 15 so pagos no dia 20 do mesmo ms.
Pedidos do dia 16 a 31 so pagos no dia 05 do ms subsequente.
RN-11 O marketplace recebe uma comisso, percentual calculado sobre o valor da venda.
Esse percentual especificado no contrato entre as empresas e pode variar por categoria de
produtos. O valor da comisso descontado no montante do repasse correspondente.
Podem haver negociaes da taxa de comisso diferenciadas para perodos especficos, como
por exemplo: dia das mes.
Universidade do Estado de Santa Catarina
Centro de Educao Superior do Alto Vale do Itaja
RN-12 O lojista deve repassar para o marketplace informaes sobre a empresa, poltica de
entrega e poltica de trocas e devolues. O marketplace deve disponibilizar para o consumidor
essas informaes.
RN-13 Os atendimentos abertos por clientes referentes a anncios e pedidos do lojista sero
encaminhados para o mesmo responder.
Descrio Regras
RF-GER-01 Permitir que o marketplace mantenha as informaes cadastrais do RN-12
lojista. So informaes da manuteno do lojista:
CNPJ
Razo social
Nome fantasia
Logo da empresa
Texto informativo sobre a empresa
Poltica de entrega
Poltica de trocas e devolues
Contatos (nome, telefone e e-mail) para os setores comercial, financeiro e
tecnologia.
Ativo
RF-GER-02 Permitir que o marketplace gere as chaves de acesso do lojista para a
API (para os ambientes de teste e produo).
RF-GER-03 Permitir que o marketplace realize a avaliao dos anncios enviados RN-01
pelo lojista, e realize a aprovao ou recusa do mesmo. RN-02
RF-GER-04 Permitir que o marketplace realize a associao e categorizao dos RN-02
anncios aprovados do lojista.
RF-GER-05 Permitir que o marketplace mantenha os ciclos de pagamento para o RN-10
lojista.
RF-GER-06 Permitir que o marketplace mantenha as taxas de comisso e suas RN-11
respectivas condies de cobrana.
RF-GER-07 Permitir configurar uma URL de call-back do lojista, que ser invoca RN-01
para notifica-lo de alteraes em anncios e pedidos. RN-05
RF-GER-08 Permitir configurar uma URL de call-back para clculo do frete e prazo RN-04
de entrega.
RF-GER-09 Permitir o encerramento do ciclo, apurando os valores a pagar para o
lojista, descontando os valores das comisses.
Descrio Regras
RF-SIT-01 O marketplace deve possuir uma pgina informativa sobre o servio e
que possibilite o cadastro do lojista interessado em anunciar no marketplace.
RF-SIT-02 Disponibilizar os anncios aprovados e com estoque para venda no(s) RN-01
Universidade do Estado de Santa Catarina
Centro de Educao Superior do Alto Vale do Itaja
site(s) do marketplace.
RF-SIT-03 Na listagem dos produtos, caso haja mais de um lojista ofertando,
somente exibido um item. O preo exibido o do lojista com o menor valor.
RF-SIT-04 Na pgina do produto, exibir as trs ofertas de menor valor.
RF-SIT-05 Na pgina do produto, identificar qual o lojista que est ofertando o
anncio. Ex: Vendido e entregue por: Lojista XYZ. Adicionar um link no nome do
lojista para a pgina do lojista.
RF-SIT-06 No site do marketplace, dever haver uma pgina do lojista. Nesse RN-12
local ser exibido todos os anncios que o lojista tem ativos dentro do marketplace.
Nessa pgina os clientes tero acesso as informaes de descrio da empresa, poltica
de entrega e poltica de troca e devolues.
RF-SIT-07 No caso do pedido, ao ser finalizado, possuir itens de diferentes lojistas,
para cada lojista ser gerado um pedido interno contendo somente seus anncios. Para
a visualizao do cliente continua sendo um nico pedido.
Requisitos API
Descrio Regras
RF-API-01 Todo acesso a API deve ser autenticado utilizando os tokens
disponibilizados ao lojista. A autenticao se dar utilizando o padro Basic-Auth.
RF-API-02 Consultas de listagem devem possuir limites de registros e uma forma de
pagin-los em requisies diferentes.
(GET /orders?_limit=X&_offset=Y)
RF-API-03 Disponibilizar um servio para o envio de anncio (produto). RN-01
(POST /item)
As informaes necessrias para o cadastro do anncio so:
Identificador (nico e que servir de referncia para consultas e alteraes do
item em questo)
Marca
Nome
Descrio (podendo conter formatao HTML)
Categoria
Lista de imagens (sendo obrigatrio pelo menos 1 imagem)
Lista de vdeos [opcional]
EAN
Quantidade disponvel para a venda
Preo (preo de) [opcional]
Preo de venda (preo por)
Dimenses (altura, largura, comprimento) [opcional]
Peso
Ativo
RF-API-04 Disponibilizar um servio de consulta geral dos anncios.
(GET /items)
RF-API-05 Disponibilizar um servio de consulta de um anncio especfico.
(GET /items/ID)
RF-API-06 Disponibilizar um servio de atualizao de dados cadastrais do anncio, RN-01
acessvel somente antes do anncio ser Aprovado.
(PUT /items/ID)
Universidade do Estado de Santa Catarina
Centro de Educao Superior do Alto Vale do Itaja
Exemplo:
{
"id": 3330,
"rel": "item",
"href": "\/items\/3330"
}
Exemplo:
{
"list": [],
"totalRows": 0,
"offset": 0,
"limit": 50
}
Exemplo:
{
"code": 400,
"message": "Propriedade \"title\" vazia ou nao encontrada no objeto Item",
"httpCode": 400
}
Exemplo:
{
"eventDate": "2015-05-06T13:40:55-03:00",
"resource": {
"id": 3330,
Universidade do Estado de Santa Catarina
Centro de Educao Superior do Alto Vale do Itaja
"rel": "item",
"href": "\/items\/3330"
},
"resourceStatus": "approved"
}
Exemplo:
{
"zipcode": 89186000,
"items": [
{
"item": {
"id": 3330,
"rel": "item",
"href": "\/items\/3330"
},
"quantity": 1
}
]
}
Exemplo:
{
"zipcode": 89186000,
"items": [
{
"itemId": 3330,
"quantity": 1
}
],
"shippingServices": [
{
"id": "PAC",
"name": "Correios - PAC",
"price": 15,
"estimatedDeliveryDate": "2015-05-28"
},
{
Universidade do Estado de Santa Catarina
Centro de Educao Superior do Alto Vale do Itaja
"id": "Sedex",
"name": "Correios - Sedex",
"price": 23.5,
"estimatedDeliveryDate": "2015-05-22"
}
]
}
Item - Anncio
Propriedade Tipo Requerido Descrio
id integer Sim Identificador (nico e que servir de referncia
para consultas e alteraes do item em questo).
brand string Sim Marca.
title string Sim Ttulo.
description string Sim Descrio detalhada. Pode conter tags de
formatao HTML.
category string Sim Categoria.
images array[string] Sim Lista de URLs das imagens. obrigatrio pelo
menos uma.
videos array[string] No Lista de URLs de vdeos.
ean string No EAN.
availableQuantity integer Sim Quantidade disponvel para venda.
price Price Sim Preo.
dimensions Dimensions No Dimenses.
weight double Sim Peso (gramas).
active boolean Sim Ativo.
Exemplo:
{
"id": 3330,
"brand": "Motorola",
"title": "Smartphone Motorola Novo Moto G Colors Dual XT1069 Desbloqueado Preto",
"description": "Um smartphone incr\u00edvel n\u00e3o deve ser um privil\u00e9gio. Deve ser
uma escolha. O Moto G oferece uma tela HD brilhante de 5 polegadas, uma bateria que dura o dia
todo, o mais recente sistema operacional Android e velocidade quad core \u2014 tudo isso por um
pre\u00e7o surpreendente. <br\/>\nTela HD de 5\" e som est\u00e9reo. <br\/>\nCom a tela mais
n\u00edtida da categoria e som est\u00e9reo, suas fotos, m\u00fasicas e v\u00eddeos t\u00eam a
melhor defini\u00e7\u00e3o. <br\/>\nSeus momentos em alta defini\u00e7\u00e3o. <br\/>\nToque em
qualquer lugar da tela para tirar uma foto, capture imagens panor\u00e2micas ou grave um
v\u00eddeo em HD. O novo Moto G oferece a voc\u00ea uma c\u00e2mera traseira de 8 MP que captura
v\u00eddeo de 720p em at\u00e9 30 fps, al\u00e9m de uma segunda c\u00e2mera frontal de 2 MP para
lindas selfies.",
"category": "Smartphones -> Motorola",
"images": [
"https:\/\/d2yd0u3irqwx65.cloudfront.net\/img\/2014\/11\/produto\/3500\/19\/large\/novo-
moto-g-colors-dual.jpg",
"https:\/\/d2yd0u3irqwx65.cloudfront.net\/img\/2015\/01\/produto\/7405\/19\/large\/motorola-moto-
g-colors-xt1069.jpg",
"https:\/\/d2yd0u3irqwx65.cloudfront.net\/img\/2014\/11\/produto\/3502\/19\/large\/tela-
novo-moto-g-colors.jpg",
"https:\/\/d2yd0u3irqwx65.cloudfront.net\/img\/2014\/11\/produto\/3503\/19\/large\/tela-
novo-moto-g-colors-dual.jpg",
Universidade do Estado de Santa Catarina
Centro de Educao Superior do Alto Vale do Itaja
"https:\/\/d2yd0u3irqwx65.cloudfront.net\/img\/2014\/11\/produto\/3499\/19\/large\/motorola-moto-
g-colors-lateral.jpg"
],
"videos": [
"https:\/\/www.youtube.com\/watch?v=dnxTRCNqk7s"
],
"ean": "7892597336555",
"availableQuantity": 35,
"price": {
"default": 899.99,
"sale": 749.99
},
"dimensions": {
"length": 1.09,
"width": 7.07,
"height": 14.15
},
"weight": 149,
"active": true
}
ItemResponse - Anncio
Propriedade Tipo Requerido Descrio
id integer Sim Identificador (nico e que servir de referncia para
consultas e alteraes do item em questo).
brand string Sim Marca.
title string Sim Ttulo.
description string Sim Descrio detalhada. Pode conter tags de formatao
HTML.
category string Sim Categoria.
images array[string] Sim Lista de URLs das imagens. obrigatrio pelo menos
uma.
videos array[string] No Lista de URLs de vdeos.
ean string No EAN.
availableQuantity integer Sim Quantidade disponvel para venda.
price Price Sim Preo.
dimensions Dimensions No Dimenses.
weight double Sim Peso (gramas).
active boolean Sim Ativo.
status string Sim Status. (pending, approved, rejected, selling).
statusDescription string No Observao sobre o status.
Stock - Estoque
Propriedade Tipo Requerido Descrio
availableQuantity integer Sim Quantidade disponvel para venda.
Active - Ativo
Propriedade Tipo Requerido Descrio
active boolean Sim Ativo.
Order - Pedido
Propriedade Tipo Requerido Descrio
id integer Sim Identificador.
siteId string Sim Nmero do pedido para o cliente.
store string Sim Loja do marketplace.
dateCreated string Sim Data/hora de criao. Formato:
YYYY-MM-DDThh:mm:ss.TZD.
status string Sim Status. (new, approved, shipped,
delivered, canceled).
client Client Sim Cliente.
items array[OrderItem] Sim Itens do Pedido.
shippingAddress ShippingAddress Sim Endereo de entrega.
estimatedDeliveryDate string Sim Data estimada de entrega.
shippingService string Sim Identificador da opo de envio.
freight double Sim Valor de frete.
totalAmount double Sim Valor total.
lastUpdate string Sim Data/hora ltima atualizao.
Formato: YYYY-MM-
DDThh:mm:ss.TZD.
Exemplo:
{
"id": 1350522,
"siteId": "0011505005868",
"store": "CissaMagazine",
"dateCreated": "2015-05-06T11:30:42-03:00",
"status": "approved",
"client": {
"documentNumber": "000.000.000-00",
"name": "Maicon Sasse",
"phones": [
{
"number": "(47) 9898-9999",
"type": "cellphone"
},
{
"number": "(47) 3521-0000",
"type": "business"
}
]
},
"items": [
Universidade do Estado de Santa Catarina
Centro de Educao Superior do Alto Vale do Itaja
{
"item": {
"id": 3330,
"rel": "item",
"href": "\/items\/3330"
},
"quantity": 1,
"price": 899.99
}
],
"shippingAddress": {
"addressType": "residential",
"receiverName": "Maicon Sasse",
"receiverPhone": null,
"street": "Rua Ernesto Jensen",
"number": "SN",
"additionalInfo": "Casa Amarela",
"neighborhood": "Fundos Aurora",
"city": "Aurora",
"zipcode": 89186000,
"reference": "Prox. MD Moveis",
"state": "SC",
"country": "BR"
},
"estimatedDeliveryDate": "2015-05-28",
"shippingService": "PAC",
"freight": 15,
"totalAmount": 914.99,
"lastUpdate": "2015-05-06T13:40:55-03:00"
}
Carrier - Transportadora
Propriedade Tipo Requerido Descrio
documentNumber string Sim CNPJ.
name string Sim Nome.
Exemplo:
{
"items": [
{
"itemId": 3330,
"quantity": 1
}
],
"eventDate": "2015-05-08T09:42:20-03:00",
"carrier": {
"documentNumber": "34.028.316\/0001-03",
Universidade do Estado de Santa Catarina
Centro de Educao Superior do Alto Vale do Itaja
"name": "Correios"
},
"trackingNumber": "PI275554091BR",
"invoice": {
"number": "321861",
"line": "1",
"issueDate": "2015-05-08T08:40:12-03:00",
"accessKey": "42150212687276000179550010003218611174804266"
}
}
Exemplo:
{
"items": [
{
"itemId": 3330,
"quantity": 1
}
],
"eventDate": "2015-05-25T13:02:17-03:00"
}
Exemplo:
{
"items": [
{
"itemId": 3330,
"quantity": 1
}
],
"eventDate": "2015-05-08T09:42:20-03:00",
"reason": "Solicita\u00e7\u00e3o do cliente"
}
Exemplo:
{
"id": 3510024,
"dateCreated": "2015-05-28T10:02:12-03:00",
"type": "D\u00favidas",
"subject": "Acess\u00f3rios para o moto G2",
"status": "pending",
"client": {
"documentNumber": "000.000.000-00",
"name": "Maicon Sasse",
"phones": [
{
"number": "(47) 9898-9999",
"type": "cellphone"
},
{
"number": "(47) 3521-0000",
"type": "business"
}
]
},
"order": null,
"store": "CissaMagazine",
"messages": [
{
"id": 351002401,
"dateCreated": "2015-05-28T10:02:12-03:00",
"userName": "Maicon Sasse",
"message": "Tem previs\u00e3o de chegada da flip shell original para o moto G 2 na
cor preta?"
}
],
"lastUpdate": "2015-05-28T10:02:12-03:00"
}
Exemplo:
{
"date": "2015-05-08",
"type": "credit",
"order": {
"id": 1350522,
"rel": "orders",
"href": "\/orders\/1350522"
},
"value": 914.99
}
Exemplo:
{
"id": 3510,
"startDate": "2015-05-01",
"finishDate": "2015-05-15",
"paymentDate": "2015-05-25",
"creditAmount": 914.99,
"debitAmount": 109.79,
"totalAmount": 805.2
}