Mktplace

Universidade do Estado de Santa Catarina
Centro de Educao Superior do Alto Vale do Itaja
PROJETANDO UMA API DE SERVIOS PARA

DISPONIBILIZAO DE UM MARKETPLACE
Maicon Sasse, Osmar de Oliveira Braz Junior
Ps-Graduao em Engenharia de Software - PGES
Centro de Educao Superior do Alto Vale do Itaja - CEAVI
Universidade do Estado de Santa Catarina - UDESC
maicon_sasse@yahoo.com.br, osmar.oliveira.braz@gmail.com
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.
Palavras-chave: API. E-commerce. Marketplace.
DESIGNING AN API SERVICES TO PROVIDE A

MARKETPLACE
Abstract
This article focuses at the analysis and design to develop an API services to provide an
integrated marketplace environment to an e-commerce platform. In this document will be
demonstrated concepts off e-commerce and marketplace, as well as integration techniques for
implementing a API services. The survey was carried out of the requirements in e-commerce
company Magamobi E-Business S/A, in the city of Rio do Sul-SC, whose main focus of mobile
phones and smartphones sales. The result is a complete API, analyzed and designed with the
patterns and best practices, containing the resources and services necessary for integration
between sellers and marketplace. Using this approach there is no need of the marketplace
develop other tools, because the API includes all the features.
Keywords: API. E-commerce. Marketplace.
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.
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
O e-commerce, que em portugus significa comrcio eletrnico, uma modalidade de comrcio

que realiza suas transaes financeiras por meio de dispositivos e plataformas eletrnicas, como
computadores e celulares. Um exemplo deste tipo de comrcio comprar ou vender produtos em
lojas virtuais (E-Commerce News, 2015).
Segundo WHINSTON, CHOI, & STAHL (2007) o e-commerce refere-se utilizao de
meios eletrnicos e tecnologias para conduzir o comrcio (compra, venda, transferncia ou troca
de produtos, servios, e / ou de informao). Conforme TREPPER (2000), em sua forma mais
pura, o termo e-commerce designa qualquer transao comercial que ocorra via processos
digitais em uma rede. No entanto, na verdade o e-commerce muito mais do que a mera troca de
produtos e servios por dinheiro pela internet. uma tecnologia capacitadora que permite s
empresas aumentar a preciso e eficincia do processamento das transaes do negcio. O e-
commerce tambm um meio que possibilita a troca de informaes entre a empresa e seus
clientes e fornecedores, beneficiando todos os envolvidos.
MEIRA Jr. (2002) descreve que o comrcio eletrnico considerado uma atividade
fundamental para o desenvolvimento do setor produtivo pois possibilita a ampliao e a
diversificao dos mercados consumidores. FURGERI (2001), comenta que as empresas
encontram um novo canal de vendas ao consumidor e descreve que desde o surgimento do

comercio eletrnico as empresas esto sempre a acompanhando esse novo mercado interativo,
fascinadas pela facilidade de se comunicar com o consumidor, coletando, armazenando e
recuperando suas preferncias pessoais de forma automtica e on-line.
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.
2.3 HTTP: Documentos em envelopes
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:
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.
2.4 REST: Representational State Transfer
Para GLOVER (2008), REST uma forma de pensar, e no um protocolo ou um padro. um

estilo de se projetar aplicativos da Web fracamente acoplados que contam com recursos
nomeados em forma de Localizador Uniforme de Recursos (URL), Identificador Uniforme de
Recursos (URI) e Nome de Recurso Uniforme (URN), por exemplo e no com mensagens.
Engenhosamente, o REST transporta a infraestrutura j validada e bem-sucedida da Web
HTTP. Ou seja, o REST alavanca aspectos do protocolo HTTP como pedidos GET e POST.
Esses pedidos so perfeitamente mapeados para necessidades de aplicativo de negcios padro,
como create read, update, and delete (CRUD). RICHARDSON e RUBY (2007), afirmam que
REST no uma arquitetura: um conjunto de critrios de desenvolvimento. Esse autor, alm
das operaes padro CRUD, adiciona duas novas operaes: headers e options. O mapeamento
de funes da aplicao REST mostrado na tabela abaixo.
Tarefa do Aplicativo Mtodo HTTP Descrio
Create POST Criar um novo recurso.

Read GET Recuperar a representao de um recurso.
Update PUT Modificar um recurso existente.
Delete DELETE Apagar um recurso existente.
Headers HEAD Recuperar uma representao com metadados apenas.
Options OPTIONS Verificar quais mtodos HTTP um determinado recurso suporta
Tabela 1 Mapeamento CRUD/HTTP. Adaptado de GLOVER, 2008 e RICHARDSON e RUBY, 2007.
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)
2.5 JSON: JavaScript Object Notation
O JSON (JavaScript Object Notation) um formato de serializao para estruturas de dados em

geral. muito mais leve e legvel que o documento XML equivalente, por isso recomendado
na maioria dos casos em que feito o transporte de estruturas de dados serializados. O JSON
uma maneira simples e independente de linguagem de formatar as estruturas de dados da
linguagem de programao (nmeros, arrays, etc.) como strings. (RICHARDSON; RUBY, 2007)
2.6 ROA: Resource-Oriented Architecture
RICHARDSON e RUBY (2007), propem a Arquitetura Orientada a Recursos (ROA), uma

arquitetura concreta para o desenvolvimento de sistemas para a Web seguindo o estilo
arquitetnico REST. A arquitetura ROA se apresenta como um conjunto de regras e boas
prticas para a implementao de servios que utilizam todo o potencial oferecido pela Web.
A ROA um modo de transformar um problema em um servio web REST: uma organizao
de URIs, HTTP e XML que funciona como o resto da web e que os programadores gostaro de
usar. RICHARDSON e RUBY (2007) definem a ROA em quatro conceitos e quatro
propriedades, vamos aos conceitos:
Recurso: Geralmente, um recurso algo que pode ser armazenado em um computador e
representado por um fluxo de bits: um documento, uma linha em um banco de dados ou o
resultado da execuo de um algoritmo.
Tudo na Web (pginas, imagens, entre outras coisas) so a essncia de um recurso. O fato de
o REST contar com recursos nomeados em vez de mensagens facilita o fraco acoplamento no
design do aplicativo, pois isso limita a exposio da tecnologia subjacente. (GLOVER, 2008)
Identificadores de Recursos (URI): Um recurso tem que ter pelo menos uma URI. A URI o
nome e o endereo de um recurso. Um recurso e sua URI devem ter uma correspondncia clara.
Ex: /software/realease/latest. As URIs devem ter uma estrutura e devem variar de modo
previsveis.
Representaes: A representao fala sobre o estado do recurso. A principal finalidade de
qualquer representao enviar o estado do recurso. O estado do recurso praticamente
qualquer informao sobre o recurso subjacente. Os formatos de representao mais comuns so
o XML e o JSON.
As quatro propriedades da ROA so:
Endereamento: diz que toda parte interessante da informao que o servidor pode fornecer
deve ser exibida como um recurso e dada em sua prpria URI.
Falta de estado: A falta de estado significa que toda solicitao HTTP ocorre em um
isolamento completo. Quando um cliente faz uma solicitao HTTP, inclui todas as informaes
necessrias para o servidor satisfazer-lhe. O servidor nunca conta com as informaes das
solicitaes anteriores.
Conectividade: a propriedade que permite que um cliente navegue por entre os recursos da
aplicao atravs de enlaces hipermdia embutidos nas representaes, ou seja documentos que
contm no apenas dados, mas links para outros recursos.
Interface uniforme: Em toda web, existem apenas algumas coisas bsicas que voc pode fazer
em um recurso. O HTTP fornece quatro mtodos bsicos para as quatro operaes mais comuns:
Recuperar a representao de um recurso: HTTP GET;
Criar um novo recurso: HTTP PUT para uma nova URI ou HTTP POST para uma
URI existente;
Modificar um recurso existente: HTTP PUT para uma URI existente;
Apagar um recurso existente: HTTP DELETE;
Recuperar uma representao com metadados apenas: HTTP HEAD;
Verificar quais mtodos HTTP um determinado recurso suporta: HTTP OPTIONS.
2.7 Melhores Prticas para REST e ROA
RICHARDSON e RUBY (2007) propem, em um capitulo especfico, algumas boas prticas

para a implementao correta de servios REST utilizando os conceitos de ROA. Eles descrevem
os seguintes passos como sendo uma boa prtica:
1. Descubra o conjunto de dados.
2. Divida o conjunto de dados em recursos.
Para cada tipo de recurso
3. Nomeie os recursos com URIs.
4. Exponha um subconjunto da interface uniforme.
5. Projete a(s) representaes aceitas pelo cliente.
6. Projete a(s) representaes fornecidas ao cliente.
7. Integre esse recurso aos recursos existentes, usando links hipermdia e formulrios.
8. Considere o caminho tpico dos eventos: o que deve acontecer?
9. Considere as condies de erro: o que pode dar errado?
Algo que relevante ressaltar, que nesse capitulo, os autores retomam os conceitos e
propriedades da ROA, j descritos anteriormente por eles, o que a princpio numa primeira
leitura pode parecer redundncia, porem o motivo justamente ressaltar a importncia dos
mesmos para uma boa implementao.
Outras dicas descritas por eles que merecem destaque so:
Representao de sada: Use os cdigos de status HTTP para informar como o cliente deve
considerar o documento que voc est servindo. Se houver erro, voc deve definir o cdigo de
status para indicar uma condio de erro apropriada, possivelmente 400 (Bad Request). Do
contrrio, o cliente poder tratar sua mensagem de erro como uma representao do recurso que
ele requisitou.
O cdigo de status diz para que serve o documento. J o cabealho de resposta Content-Type
diz que formato est o documento. Sem esse cabealho, seus clientes no sabero como analisar
ou tratar os documentos servidos por voc.
Estabelecendo verses para os servios: Se essa a regra for mudada, alguns clientes escritos
por voc quebraram. Em situaes desse tipo, o servio deve permitir um perodo de transio no
qual recursos antigos funcionem lado a lado com os novos. A forma mais simples de fazer isto
consiste em incorporar as informaes de verso, tornando-a a primeira varivel do path:
/v1/resource versus /v2/resource.
Mesmo um servio bem encadeado pode precisar de novas verses. s vezes, reescrever um
servio altera o significado das representaes e todos os clientes quebram, mesmo os que
compreendiam as deixas semnticas anteriores. Em caso de dvida, estabelea verses para seus
servios.
Compactao: Representaes textuais podem ser compactadas a uma frao de seu tamanho.
Uma biblioteca cliente para o HTTP pode requisitar uma verso compactada de sua
representao, e em seguida, descompacta-la de forma transparente para seu usurio. Junto com
a requisio HTTP o cliente envia um cabealho Accept-Encoding, que diz os tipos de
algoritmos de compactao compreendidos pelo cliente. Se o servidor compreender o Accept-
Encoding, ele poder compactar a representao antes de servi-la. O servidor envia o mesmo
Content-Type que enviaria se a representao no estivesse compactada. E tambm envia o
cabealho Content-Encoding para informar ao cliente que o documento foi compactado. Essa
tcnica pode economizar muita largura de banda com pouqussimo custo em termos de
complexidade adicional.
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.
3. Projetando a API de servios para marketplace
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.
3.1 Coleta das Regras de Negcios e Requisitos
Uma compreenso completa dos requisitos de software fundamental para um bem-sucedido

desenvolvimento de software. A tarefa de anlise de requisitos um processo de descoberta,
refinamento, modelagem e especificao (PRESSMAN, 1995). O levantamento das regras e
requisitos necessrios para o desenvolvimento do ambiente de marketplace 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. Atualmente a empresa utiliza o
ambiente de marketplace do grupo B2W - Companhia Digital (Americanas, Submarino e
Shoptime), CNOVA Comrcio Eletrnico S.A. (Extra, Casas Bahia, Ponto Frio), Walmart e
Mercado Livre. Utilizando esses marketplaces a empresa teve um crescente aumento na
visibilidade de seus produtos, consequentemente aumentando as vendas. A tabela 2 mostra a
representatividade dos pedidos vindo de marketplace no total de pedidos geral por trimestre.
Ano Trimestre Total geral de pedidos Total de origem marketplace Percentual

2014 1 49.183 5.344 10,866 %
2014 2 66.349 20.913 31,52 %
2014 3 103.026 45.008 43,686 %
2014 4 111.799 49.877 44,613 %
2015 1 91.316 45.931 50,299 %
2015 2 (parcial) 93.341 43.471 46,572 %
Tabela 2 Representatividade pedidos de marketplace. Fonte: Magamobi. (Acervo do Autor).
Para o levantamento foram realizadas conversas com os responsveis comerciais e com o

grupo de TI da empresa. As solues de marketplace utilizadas pela empresa tambm foram
fontes de pesquisa. O resultado completo da coleta de regras e requisitos est no Apndice A
desse documento.
A empresa pretende ainda em 2015 lanar seu marketplace prprio, visando expandir seu
portflio de produtos e suas vendas, realizando novas parcerias comerciais. Outro fator
importante o fato que a disponibilizao desse recurso agregar valor a plataforma de e-
commerce da empresa, que h pretenso de futuramente ser comercializada. Alm disso a
empresa tem pretenses de expanso para outros pases como mostra a viso da empresa: "Ser a
maior e melhor operao de varejo online, especializada em celulares e smartphones da Amrica
Latina, atuando tambm com solues em e-commerce, presente em mais de 5 pases e com
receita bruta anual superior a R$ 1 bilho at 31/12/2020" (Magamobi, 2015).
3.2 Projetando a API
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.
3.3 API Viso geral
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
ingls, atendendo as pretenses de expanso para o exterior da empresa envolvida na pesquisa.

Essa uma prtica comum (todas as quatro APIs analisadas de marketplace que a empresa utiliza
tambm seguem esse padro) pois o idioma ingls considerado a lngua universal.
Autenticao: Algo extremamente importante ao construir uma API definir de qual forma
ser feita a autenticao do usurio. Para esse projeto foi escolhido o padro de autenticao
bsica (Basic Auth), por ser simples e eficaz, alm de ser bem conhecido entre a comunidade de
desenvolvedores. Para garantir a segurana no trfego de informaes entre lojista de
marketplace, todas as requisies efetuadas a API devem ser autenticadas. Para isso o lojista
dever utilizar as chaves de acesso (tokens) fornecidas pelo marketplace e envia-los utilizando o
padro Basic Auth. RICHARDSON e RUBY (2007), descrevem que a autenticao bsica
consiste em um simples conjunto desafio/resposta. Se voc tentar acessar um recurso protegido
por autenticao bsica e no fornecer as credenciais adequadas, vai receber um desafio e ter
que repetir a requisio. O servidor desafia a repetir minha requisio com as credenciais
corretas. Para responder a um desafio da autenticao bsica, o cliente precisa de um nome de
usurio e senha. Uma vez que o cliente tenha as informaes, o nome de usurio e a senha so
combinados em uma nica string e codificados por meio da codificao base64. Essa string de
caracteres aparentemente aleatria o valor do cabealho Authorization. O Servidor decodifica
essa string e compara com a lista de usurios e senhas. Se eles forem iguais, a resposta continua
sendo processada. Se no, a requisio falha e cdigo de resposta o 401 (Unauthorized / No
Autorizado).
Erros: Quando houver erro na requisio a API, o cdigo de resposta HTTP ir identificar o
mesmo. Esses cdigos de erro podem ser classificados em dois grupos, erros da parte do lojista
(representados pela famlia de cdigo 400), e os erros internos do servidor da aplicao
(representados pela famlia de cdigo 500). Nesses casos a representao de sada do servio ser
um objeto Error (Figura 1). Os erros mais comuns por parte do cliente so: atributos obrigatrios
no preenchidos, identificador duplicado (no caso de servios de criao) e consulta a recursos
inexistentes.
Consultas de listagem: Existem servios de consulta que retornam uma lista de recursos. Para
evitar uma representao de sada muito grande, necessrio paginar os registros. O conceito o
mesmo utilizado em banco de dados. Isso feito enviando os parmetros _limit (quantidade de
registros por pagina) e _offset (posio inicial da consulta), por exemplo _limit=30&_offset=60
trar 30 registros a partir da posio 60. O retorno dessas consultas um objeto List (Figura 1),
contendo nele os registros obtidos na consulta. No objeto List existe um atributo totalRows que
indica o total geral de registros. Existe o recurso de resposta parcial, enviando o parmetro
_attributes, por exemplo enviado _attributes=id,name, somente esses atributos estaro
disponveis nos registros listados na consulta. O parmetro de ordenao dos registros _sort, e
as possveis formas de ordenao so definidas pelo servio em especfico.
Figura 1 Diagrama de classes comuns da API (Acervo do Autor).
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.
3.4 Recurso: anncios (/items)
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.
Figura 2 Diagrama de classes do recurso anncios (Acervo do Autor).
Os servios disponveis para o recurso de anncios so os seguintes:

Cadastro do anncio: Esse o servio invocado pelo lojista para enviar os dados dos anncios
que deseja vender no marketplace, possvel fazer o envio de mais de um anncio por vez, pois
o servio aceita uma lista de anncios.
Mtodo HTTP POST

URI /items
Representao de entrada Array de objetos Item
Cdigo de resposta HTTP de sucesso 201
Representao de sada de sucesso Nenhum
Tabela 3 Especificao do servio POST /items (Acervo do Autor).
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.
Mtodo HTTP PUT

URI /items/{ID}
Representao de entrada Objeto Item
Tabela 4 Especificao do servio PUT /items/{ID} (Acervo do Autor).
Atualizao de preo do anncio: Esse o servio invocado pelo lojista para atualizar as
informaes de preo do anncio.
Mtodo HTTP PUT

URI /items/{ID}/price
Representao de entrada Objeto Price
Tabela 5 Especificao do servio PUT /items/{ID}/price (Acervo do Autor).
Atualizao de estoque do anncio: Esse o servio invocado pelo lojista para atualizar a
quantidade disponvel para venda do anncio.
Mtodo HTTP PUT

URI /items/{ID}/stock
Representao de entrada Objeto Stock
Tabela 6 Especificao do servio PUT /items/{ID}/stock (Acervo do Autor).
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.
Mtodo HTTP PUT

URI /items/{ID}/status
Representao de entrada Objeto Active
Tabela 7 Especificao do servio PUT /items/{ID}/status (Acervo do Autor).
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.
Mtodo HTTP GET

URI /items/
Parmetros de filtro brand, title, active, status
Parmetros de ordenao id (padro), title
Representao de entrada Nenhum
Representao de sada de sucesso Objeto List, contendo um array de ItemResponse
Tabela 8 Especificao do servio GET /items (Acervo do Autor).
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.
Mtodo HTTP GET

URI /items/{ID}
Representao de sada de sucesso Objeto ItemResponse
Tabela 9 Especificao do servio GET /items/{ID} (Acervo do Autor).
3.5 Calculo do frete API lojista
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.
Figura 3 Diagrama de classes do clculo de frete API Lojista (Acervo do Autor).
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.
Mtodo HTTP POST

URI /orders/freightPreview
Representao de entrada Objeto FreightPreview
Representao de sada de sucesso Objeto FreightPreviewResponse
Tabela 10 Especificao do servio de clculo de frete API lojista (Acervo do Autor).
3.6 Recurso: pedidos (/orders)
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.
Figura 4 Diagrama classes do recurso pedidos (Acervo do Autor).
Os servios disponveis para o recurso de pedidos so os seguintes:

Consulta geral de pedidos: Esse o servio invocado pelo lojista para consultar a lista dos
seus pedidos no marketplace. Em regra geral, o lojista deve fazer a consulta de dos pedidos
novos e aprovados algumas vezes durante o dia, afim de identificar pedidos novos ou
aprovaes. O servio segue o padro geral de consultas de listagem.
Mtodo HTTP GET

URI /orders
Parmetros de filtro dateCreated, status, itemId
Parmetros de ordenao id (padro)
Representao de sada de sucesso Objeto List, contendo um array de Order
Tabela 11 Especificao do servio GET /orders (Acervo do Autor).
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.
Mtodo HTTP GET

URI /orders/{ID}
Representao de sada de sucesso Objeto Order
Tabela 12 Especificao do servio GET /orders/{ID} (Acervo do Autor).
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.
Figura 5 Diagrama classes do recurso pedidos atualizao de status (Acervo do Autor).
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.
Mtodo HTTP PUT

URI /orders/{ID}/shipped
Representao de entrada Objeto Shipping
Tabela 13 Especificao do servio PUT /orders/{ID}/shipped (Acervo do Autor).
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.
Mtodo HTTP PUT

URI /orders/{ID}/delivered
Representao de entrada Objeto Delivery
Tabela 14 Especificao do servio PUT /orders/{ID}/delivered (Acervo do Autor).
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.
Mtodo HTTP PUT

URI /orders/{ID}/canceled
Representao de entrada Objeto Canceled
Tabela 15 Especificao do servio PUT /orders/{ID}/canceled (Acervo do Autor).
3.7 Recurso: atendimentos (/tickets)
Esse recurso se refere a atendimento ao cliente. Assim como os pedidos, os atendimentos so

abertos no site do marketplace, e se forem relacionados a um anuncio ou pedido do lojista, o
lojista deve responder esse atendimento. Na figura 6, apresentado o diagrama das classes de
domnio utilizadas no 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.
Figura 6 Diagrama classes do recurso atendimentos (Acervo do Autor).
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.
Mtodo HTTP GET

URI /tickets
Parmetros de filtro dateCreated, status, lastUpdate
Parmetros de ordenao id (padro), lastUpdate
Representao de sada de sucesso Objeto List, contendo um array de Ticket
Tabela 16 Especificao do servio GET /tickets (Acervo do Autor).
Inserir mensagem no atendimento: Esse o servio invocado pelo lojista para inserir uma
mensagem (resposta) no atendimento.
Mtodo HTTP POST

URI /tickets/{ID}/messages
Representao de entrada Objeto Message
Tabela 17 Especificao do servio PUT /tickets/{ID}/messages (Acervo do Autor).
Finalizar atendimento: Esse o servio invocado pelo lojista para encerrar o atendimento.
Aps o atendimento finalizado no mais possvel adicionar mensagens.
Mtodo HTTP PUT

URI /tickets/{ID}/finalize
Representao de entrada Objeto Message (opcional)
Tabela 18 Especificao do servio PUT /tickets/{ID}/finalize (Acervo do Autor).
3.8 Recurso: relatrios (/reports)
Esse recurso se refere a relatrios e extratos. A princpio est planejado a implementao de 2

servios, ambos relacionados ao repasse financeiro ao lojista. Na figura 7, apresentado o
diagrama das classes de domnio utilizadas no 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. Os servios so descritos logo a seguir.
Figura 7 Diagrama classes do recurso relatrios (Acervo do Autor).
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.
Mtodo HTTP GET

URI /reports/transfers
Representao de sada de sucesso Objeto List, contendo um array de Transfer
Tabela 19 Especificao do servio GET /reports/transfers (Acervo do Autor).
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.
Mtodo HTTP GET

URI /reports/transfers/{ID}/transaction
Representao de sada de sucesso Objeto List, contendo um array de Transaction
Tabela 20 Especificao do servio GET /reports/transfers/{id} (Acervo do Autor).
3.9 Call-back de notificaes API lojista
Esse recurso se refere a notificaes de eventos ocorridos no marketplace. Sua implementao

pelo lojista opcional, porem recomendada. Na figura 8, apresentado o diagrama das classes
de domnio utilizada para a notificao, a representao de entrada do servio. Os atributos das
classes detalhados, e exemplo da representao JSON, podem ser encontrados no Apndice B
desse documento.
Figura 8 Diagrama classe da notificao (Acervo do Autor).

Os eventos notificados para o lojista so:

Anncio aprovado
Anncio recusado
Pedido includo
Pedido aprovado
Pedido cancelado
Atendimento includo
Atendimento alterado (nova mensagem includa)
Atendimento encerrado
Mtodo HTTP POST

URI /notification
Representao de entrada Objeto Notification
Tabela 21 Especificao do servio de notificao API lojista (Acervo do Autor).
4. Trabalhos correlatos
O primeiro trabalho correlato intitulado Relacionamentos no varejo eletrnico: Um estudo de

caso sobre o marketplace e seus parceiros (GRANDES, 2005). Neste trabalho focado no
relacionamento comercial entre lojista e marketplace, tendo como base um estudo de caso no
marketplace da Nova Pontocom (atual CNova) - Extra.com.br e oito lojistas parceiros.
Na rea de APIs em funcionamento em ambiente real podemos listas as das seguintes
empresas:
B2W: O grupo surgiu em 1999 com a criao dos sites Americanas.com e Submarino, em
2005 a empresa adquiriu o Shoptime. Em outubro de 2013 lanou o servio de marketplace no
site Submarino, em junho de 2014 disponibilizou o servio no site Americanas.com e em janeiro
de 2015 no site Shoptime. Possui 2 verses da API:
Verso 1: apresentava os recursos bsicos necessrios para integrao: para o recurso de
anncios so disponibilizados os servios de envio, atualizao de preo, atualizao de estoque,
atualizao de status e consulta individual e listagem. Para o recurso de pedidos
disponibilizado a consulta individual e listagem e as opes de atualizao do status do pedido
para nota fiscal emitida, em transporte e entregue. Nessa verso no existe nenhum tipo de call-
back a ser implementado pelo lojista e o clculo de frete para os pedidos feito baseado em uma
planilha em Excel, feita com base nos valores de uma nica forma de envio (ex: PAC dos
Correios), onde mapeado por faixa de CEP o valor do envio. A forma de autenticao utilizada
Basic Auth. Essa verso foi desativada em 30/04/2015.
Verso 2: Apresenta uma melhoria evolutiva, sem alteraes na forma como funcionava a
verso anterior. Foram adicionadas algumas novas informaes nas classes de domnio, como
imagens do anuncio, XML da nota fiscal e URL para o rastreamento na transportadora do
pedido. Foram adicionados servios de atualizao em lote de preo e estoque dos anncios.
Outra melhoria disponibilizada foi permitir configurar, opcionalmente, um call-back para
notificao para receber alertas das alteraes de pedido. Tambm possvel definir um call-
back para realizar o clculo do frete do pedido, deixando o valor do frete mais preciso para o
cliente. A documentao completa da verso 2 est disponvel em https://api-
sandbox.bonmarketplace.com.br/docs/.
Extra (CNova): 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, 2015). Possui
2 verses da API:
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).
B2W Extra (V1) Extra (V2) Walmart Mercado Livre Magamobi

Conectividade Sim - Sim - - Sim
Interface uniforme Sim Sim Sim Sim Sim Sim
Versionamento Sim Sim Sim - - Sim
Compactao - Sim Sim - - -
Recursos no plural - Sim Sim Sim - Sim
Resposta parcial - - Sim - - Sim
Paginao Sim Sim Sim Sim Sim Sim
CamelCase Sim Sim Sim Sim - Sim
Tabela 22 Boas Prticas versus APIs. Fonte: documentao B2W, CNova, Walmart e Mercado Livre.
(Acervo do Autor).
Conforme mostra a tabela 22, a API proposta somente no implementa o padro de
compactao. Sua implementao no avaliada como necessria pois praticamente todas as
requisies tem pouco volume de dados trafegando. Para as consultas (onde pode haver maior
volume de dados, dependendo do filtro utilizado), o padro de resposta parcial mais
recomendado para diminuir o tamanho das representaes.
O segundo comparativo com relao aos recursos disponibilizados pelas API (Tabela 23).
B2W Extra (V1) Extra (V2) Walmart Mercado Livre Magamobi

Envio de anncios Sim Sim Sim Sim Sim Sim
Envio mltiplo de anncios - Sim Sim - - Sim
Notificaes V2 Sim Sim - - Sim
Atualizao de preo/estoque Sim Sim Sim Sim Sim Sim
Atualizao de geral anuncio - - - Sim Parcial Parcial
Consulta de pedidos Sim Sim Sim - Sim Sim
Atualizao pedido Em Sim Sim Sim Sim Sim Sim
Transporte
Atualizao pedido Entregue Sim Sim Sim - Sim Sim
Atualizao pedido - Sim Sim Sim - Sim
Cancelado
Consulta a atendimentos - - Sim - Sim Sim
Relatrio de pagamentos - - - - - Sim
Portal do lojista Sim Sim Sim Sim Sim -
Tabela 23 Recursos disponveis versus APIs. Fonte: documentao B2W, CNova, Walmart e Mercado
Livre. (Acervo do Autor).
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
Este trabalho consistiu na formao de uma anlise para implementao de um ambiente de

marketplace integrado a uma plataforma existente de e-commerce. O foco principal foi a rea de
integrao, via API de servios. Embora tenha o foco na API, foi necessrio compreender e
analisar todo o fluxo de funcionamento de um marketplace, e onde seriam necessrias as
alteraes em outras partes da plataforma. No se pode modelar uma parte sem conhecer o todo,
e isso levado como uma lio aprendida desse projeto.
Analisar as solues existentes no mercado uma boa prtica para coletar requisitos, avaliar
seus pontos fortes e diferenas entre implementaes fazem o seu projeto extrair o melhor de
todos eles e se tornar um diferencial.
Antes de modelar as classes e servios, importante conhecer os padres e boas prticas
relacionados a tecnologia que a soluo vai ser desenvolvida. Como se trata de servios que
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.
E-Commerce News. O que E-Commerce? 2015. Disponvel em:

<http://ecommercenews.com.br/o-que-e-e-commerce> Acessado em 25 de junho de 2015.
Extra.com.br. Venda no Extra.com.br | Extra Marketplace. 2014. Disponvel em:

<http://www.extra.com.br/marketplace/venda-no-extra.aspx/> Acessado em 23 de fevereiro de
2015.
Extra.com.br. Extra.com.br Desenvolvedores. 2014. Disponvel em:

<https://desenvolvedores.extra.com.br/api-portal/docs/apilojistav1/apis/index.html> Acessado
em 25 de fevereiro de 2015.
FURGERI, Srgio. Business to Business: Aprenda a desenvolver aplicaes. So Paulo: rica,

2001.
GILBERTONI, Mariana. Marketplaces: sua loja j aderiu?. 2014. Disponvel em:

<http://www.ecommercebrasil.com.br/artigos/marketplaces-sua-loja-ja-aderiu/> Acessado em 23
de fevereiro de 2015.
GLOVER, Andrew. Construa um Servio da Web RESTful. 2008. Disponvel em:

<http://www.ibm.com/developerworks/br/library/j-rest> Acessado em 14 de abril 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.
GRANDES, Luisa Ancona. Relacionamentos no varejo eletrnico: Um estudo de caso sobre

o marketplace e seus parceiros. So Paulo, 2013.
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.
MAGAMOBI. 2015. Disponvel em: <http://www.magamobi.com.br/> Acessado em 24 de abril

de 2015.
MEIRA Jr., Wagner. [et al.]. Sistemas de Comrcio Eletrnico: Projeto e desenvolvimento. Rio
de Janeiro: Campus, 2002, 1.
Mercado Livre. Sobre Mercado Livre. 2015. Disponvel em:

<http://institucional.mercadolivre.com.br/sobre-mercadolivre/> Acessado em 24 de abril de
2015.
Mercado Livre. MercadoLibre Developers Site. 2015. Disponvel em:

<http://developers.mercadolibre.com/> Acessado em 24 de abril de 2015.
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.
PRESSMAN, Roger. S. Engenharia de Software. So Paulo: Makron Books, 1995.
RICHARDSON, Leonard. RUBY, Sam. RESTful servios Web. Traduo Eveline Vieira e
Patricia Azeredo. Rio de Janeiro: Alta Books, 2007
SEBRAE. Conhea as vantagens do e-marketplace para os pequenos negcios. Disponvel

em: <http://www.sebrae.com.br/sites/PortalSebrae/artigos/Conhe%C3%A7a-as-vantagens-do-
e%E2%80%93marketplace-para-os-pequenos-neg%C3%B3cios> Acessado em 23 de fevereiro
de 2015.
TREPPER, Charles H. Estratgias de E-commerce. Traduo Ana Beatriz Rodrigues. Rio de

Janeiro: Campus, 2000, 13.
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.
Walmart. Wal-Mart Marketplace RESTful API. 2014. Disponvel em:

<http://adapter.waldev.com.br/> Acessado em 25 de fevereiro de 2015.
WHINSTON, Andrew B. CHOI, Soon-Yong. STAHL, Dale O. The Economics of Electronic

Commerce. MacMillan Publishing Company, 1997.
APNDICE A Regras de negcios e requisitos coletados
Este apndice demonstra o resultado da coleta de regras de negcio e requisitos necessrios

para a criao de um ambiente de marketplace. A coleta foi efetuada na empresa Magamobi E-
Business S/A.
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.
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.
Requisitos Gerencial Marketplace
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.
RNF-GER-01 Deve estar integrado com a plataforma de e-commerce utilizada pelo

marketplace.
Requisitos Site do Marketplace
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
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)
RF-API-07 Disponibilizar um servio de atualizao de preo do anncio. RN-03

(PUT /items/ID/price)
RF-API-08 Disponibilizar um servio de atualizao de estoque do anncio. RN-03
(PUT /items/ID/stock)
RF-API-09 Disponibilizar um servio de ativao/desativao do anncio. RN-03
(PUT /items/ID/status)
RF-API-10 Disponibilizar um servio de consulta geral dos pedidos.
(GET /order)
Possibilitando os seguintes filtros opcionais:
Data/hora inicial
Data/hora final
Situao
Identificador de Anncio
RF-API-11 Disponibilizar um servio de consulta de um pedido especfico.
(GET /orders/ID)
As informaes do pedido so as seguintes:
Identificador (nico e que servir de referncia para consultas e alteraes do
item em questo)
Nmero (nmero do pedido para o cliente)
Site do marketplace em que foi realizado a venda
Data/hora do pedido
Situao (Novo, Aprovado, Cancelado, Em Transporte, Entregue)
Dados do cliente (CPF/CNPJ, nome, telefones)
Itens comprados (Identificador do anncio, valor unitrio, quantidade)
Dados de Entrega (Forma de envio, valor do frete, nome destinatrio, endereo,
nmero, bairro, complemento, CEP, cidade, estado)
Valor total do pedido
Data/hora da ltima atualizao.
RF-API-12 Disponibilizar um servio de atualizao do pedido para Em RN-08
Transporte.
(PUT /orders/ID/shipped)
As informaes necessrias para o registro do envio so:
Nome da transportadora
Cdigo de rastreamento na transportadora
Itens enviados (Identificador do anncio, quantidade)
Data/hora
Dados da nota fiscal (Nmero, srie, data de emisso, chave de acesso)
RF-API-13 Disponibilizar um servio de atualizao do pedido para Entregue. RN-09
(PUT /orders/ID/delivered)
As informaes necessrias para o registro de entrega so:
Itens entregues (Identificador do anncio, quantidade)
Data/hora
RF-API-14 Disponibilizar um servio de atualizao do pedido para Cancelado. RN-07
(PUT /orders/ID/cancel)
As informaes necessrias para o cancelamento so:
Itens cancelados (Identificador do anncio, quantidade)
Data/hora
Motivo do cancelamento
RF-API-15 Disponibilizar um servio de consulta geral dos protocolos de

atendimento.
(GET /tickets)
Data/hora inicial
Data/hora final
Situao
RF-API-16 Disponibilizar um servio de resposta a um protocolo de atendimento.
(POST /tickets/ID/messages)
RF-API-17 Disponibilizar servio de consulta dos repasses financeiros para lojista. RN-10
(GET /reports/transfers) RN-11
Listagem contendo o resumo do ciclo:
Identificador ciclo
Perodo
Data de pagamento
Total de crditos
Total de dbitos
RF-API-17 Disponibilizar servio de detalhamento de um repasse financeiro para RN-10
lojista. RN-11
(GET /reports/transfers/ID)
As informaes so as seguintes:
Data/hora
Tipo do movimento (Crdito ou Dbito)
Pedido de referencia
Descrio
Valor do repasse
RF-API-18 Disponibilizar servio de consulta dos atendimentos.
(GET /tickets)
Data/hora abertura inicial
Data/hora abertura final
Data/hora ltima atualizao inicial
Data/hora ltima atualizao final
Status
RF-API-19 Disponibilizar servio para adicionar uma mensagem (resposta) em um
atendimento.
(POST /tickets/ID/messages)
As informaes necessrias so:
Mensagem
Nome do usurio
RF-API-20 - 19 Disponibilizar servio para encerrar um atendimento.
(PUT /tickets/ID/finalize)
Opcionalmente pode ser enviado uma mensagem.
RNF-API-01 A API deve ser modelada utilizando os padres de arquitetura REST

(Representational State Transfer).
Formato das representaes (entrada e sada): JSON
Charset: UTF-8
Content-Type: application/json
Formato de data/hora (ISO-8601): YYYY-MM-DDThh:mm:ss.TZD.

Ex: 2015-05-09T16:50:45-03:00
RNF-API-02 A API deve somente operar em ambiente seguro utilizando HTTPS.
RNF-API-03 Cdigos HTTP retornados pela API:
Cdigos de sucesso:
200 Para mtodo GET Indica consulta processada com sucesso.
201 Para mtodo POST Indica que o recurso foi criado com sucesso.
204 Para mtodo PUT Indica que o recurso foi alterado com sucesso.
Cdigos de erro (retornados devido a erro por parte do lojista):
400 Requisio mal formada.
401 Requisio no autorizada. (Credenciais invlidas).
403 Requisio negada. (Credenciais suspensas ou bloqueadas / acesso negado).
404 Recurso no encontrado.
405 Mtodo no implementado.
422 Excees de negcio.
429 Limite de requisies por minuto atingido.
Cdigos de erro (retornados devido a erro por parte do marketplace):
500 Erro interno do servidor.
RNF-API-04 Em casos de erro, as informaes retornadas sero as seguintes:
Cdigo de erro
Mensagem
RNF-API-05 O marketplace deve disponibilizar toda documentao necessria da
API, afim de orientar o desenvolvimento do lojista.
RNF-API-06 A API deve possuir alta disponibilidade. Percentual desejado de 97%
no mnimo.
Prottipos Site do Marketplace
Prottipo de alta fidelidade Pgina do produto RF-SIT-05

Prottipo de alta fidelidade Pgina do lojista RF-SIT-06

APNDICE B Detalhamento das classes e exemplos em JSON
Este apndice demonstra detalhadamente o significado de cada atributo das classes de

domnio utilizadas nos servios da API. Tambm apresentado um exemplo em formato JSON
da representao da classe.
Objetos comuns a todos os recursos da API

Link - Link/referncia para um recurso especfico
Propriedade Tipo Requerido Descrio
id integer Sim Identificador do recurso.
rel string Sim Tipo do recurso: item, order, ticket.
href string Sim Link para acessar o recurso.
Exemplo:
{
"id": 3330,
"rel": "item",
"href": "\/items\/3330"
}
List - Listagem de recursos

list array Sim Objetos dos registros.
totalRows integer Sim Total de registros.
offset integer Sim Posio inicial da consulta. Iniciado em 0.
limit integer Sim Registros por consulta. Mximo 50.
Exemplo:
{
"list": [],
"totalRows": 0,
"offset": 0,
"limit": 50
}
Error - Resposta de erro

code integer No Cdigo.
message string Sim Mensagem.
httpCode integer Sim Cdigo HTTP.
Exemplo:
{
"code": 400,
"message": "Propriedade \"title\" vazia ou nao encontrada no objeto Item",
"httpCode": 400
}
Objetos da API Lojista

Notification - Notificao
eventDate string Sim Data/hora. Formato: YYYY-MM-DDThh:mm:ss.TZD.
resource Link Sim Recurso.
resourceStatus string No Status do recurso.
Exemplo:
{
"eventDate": "2015-05-06T13:40:55-03:00",
"resource": {
"id": 3330,
"rel": "item",
"href": "\/items\/3330"
},
"resourceStatus": "approved"
}
FreightPreviewItem - Item para o clculo de frete

item Link Sim Link do anncio.
quantity integer Sim Quantidade.
FreightPreview - Clculo de frete

zipcode integer Sim CEP.
items array[FreightPreviewItem] Sim Lista dos itens.
Exemplo:
{
"zipcode": 89186000,
"items": [
{
"item": {
"id": 3330,
"rel": "item",
"href": "\/items\/3330"
},
"quantity": 1
}
]
}
ShippingService - Opo de envio do anncio

id string Sim Identificador.
name string Sim Nome.
price double Sim Valor.
estimatedDeliveryDate string Sim Data estimada de entrega.
FreightPreviewItemResponse - Item da resposta do clculo de frete

itemId integer Sim Identificador do anncio.
FreightPreviewResponse - Resposta do clculo de frete

items array[FreightPreviewItemResponse] Sim Lista dos itens.
shippingServices array[ShippingService] Sim Opes de envio.
Exemplo:
{
"zipcode": 89186000,
"items": [
{
"itemId": 3330,
"quantity": 1
}
],
"shippingServices": [
{
"id": "PAC",
"name": "Correios - PAC",
"price": 15,
"estimatedDeliveryDate": "2015-05-28"
},
{
"id": "Sedex",
"name": "Correios - Sedex",
"price": 23.5,
"estimatedDeliveryDate": "2015-05-22"
}
]
}
Objetos recurso /items (anncios)

Price - Preo do anncio
default double Sim Preo "de".
sale double Sim Preo "por". Preo real de venda.
Dimension - Dimenses do anncio

length double No Comprimento (cm).
width double No Largura (cm).
height double No Altura (cm).
Item - Anncio
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",
"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
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.
price Price Sim Preo.
dimensions Dimensions No Dimenses.
weight double Sim Peso (gramas).
status string Sim Status. (pending, approved, rejected, selling).
statusDescription string No Observao sobre o status.
Stock - Estoque
Active - Ativo
Objetos recurso /orders (pedidos)

Telephone - Telefone de contato
number string Sim Nmero.
type string Sim Tipo. (home, cellphone, business).
Client - Dados do cliente

documentNumber string Sim CPF/CNPJ.
phones array[Telephone] Sim Telefones de contato.
ShippingAddress - Endereo de entrega

addressType string Sim Tipo. (commercial, residential).
receiverName string No Responsvel.
receiverPhone string No Fone responsvel.
street string Sim Endereo.
number string No Nmero.
additionalInfo string No Complemento.
neighborhood string Sim Bairro.
city string Sim Cidade.
reference string No Ponto de referncia.
state string Sim Estado (sigla).
country string Sim Pas (sigla).
OrderItem - Item do pedido

item Link Sim Anncio.
price double Sim Preo unitrio.
Order - Pedido
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": [
{
"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
documentNumber string Sim CNPJ.
Invoice - Nota Fiscal

number string Sim Nmero.
line string Sim Srie.
issueDate string Sim Data/hora de emisso. Formato: YYYY-MM-DDThh:mm:ss.TZD.
accessKey string Sim Chave de acesso.
TrackingItem - Item do tracking

itemId integer Sim Identificador do anncio.
Shipping - Tracking de envio para a transportadora

items array[TrackingItem] Sim Lista dos itens.
eventDate string Sim Data/hora de envio. Formato: YYYY-MM-
DDThh:mm:ss.TZD.
carrier Carrier Sim Transportadora.
trackingNumber string Sim Cdigo de rastreio na transportadora.
invoice Invoice Sim Nota Fiscal.
Exemplo:
{
"items": [
{
"itemId": 3330,
"quantity": 1
}
],
"eventDate": "2015-05-08T09:42:20-03:00",
"carrier": {
"documentNumber": "34.028.316\/0001-03",
"name": "Correios"
},
"trackingNumber": "PI275554091BR",
"invoice": {
"number": "321861",
"line": "1",
"issueDate": "2015-05-08T08:40:12-03:00",
"accessKey": "42150212687276000179550010003218611174804266"
}
}
Delivery - Tracking de entrega para o cliente

eventDate string Sim Data/hora de entrega. Formato: YYYY-MM-
DDThh:mm:ss.TZD.
Exemplo:
{
"items": [
{
"itemId": 3330,
"quantity": 1
}
],
"eventDate": "2015-05-25T13:02:17-03:00"
}
Canceled - Tracking de cancelamento

eventDate string Sim Data/hora de cancelamento. Formato: YYYY-MM-
DDThh:mm:ss.TZD.
reason string Sim Motivo.
Exemplo:
{
"items": [
{
"itemId": 3330,
"quantity": 1
}
],
"eventDate": "2015-05-08T09:42:20-03:00",
"reason": "Solicita\u00e7\u00e3o do cliente"
}
Objetos recurso /tickets (atendimentos)

Message - Mensagem do protocolo de atendimento
id int Sim Identificador.
dateCreated string Sim Data/hora. Formato: YYYY-MM-DDThh:mm:ss.TZD.
userName string Sim Usurio.
message string Sim Mensagem.
Ticket - Protocolo de atendimento

dateCreated string Sim Data/hora de abertura. Formato: YYYY-MM-
DDThh:mm:ss.TZD.
type string Sim Tipo. (Dvidas, Vendas, Reclamaes, Trocas).
subject string Sim Assunto.
status string Sim Status.
client Client Sim Cliente.
order Link No Pedido.

store string Sim Loja do marketplace.
messages array Sim Mensagens.
lastUpdate string Sim Data/hora ltima atualizao. Formato: YYYY-MM-
DDThh:mm:ss.TZD.
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"
}
Objetos recurso /reports (relatrios)

Transaction - Movimentao financeira
date string Sim Data.
type string Sim Tipo da operao. (credit, debit).
order Link No Pedido.
value double Sim Valor.
Exemplo:
{
"date": "2015-05-08",
"type": "credit",
"order": {
"id": 1350522,
"rel": "orders",
"href": "\/orders\/1350522"
},
"value": 914.99
}
Transfer - Repasse financeiro

startDate string Sim Data de incio do ciclo.
finishDate string Sim Data de final do ciclo.
paymentDate string Sim Data de pagamento.
creditAmount double Sim Valor total de crdito.

debitAmount double Sim Valor total de dbito.
totalAmount double Sim Valor total repassado.
Exemplo:
{
"id": 3510,
"startDate": "2015-05-01",
"finishDate": "2015-05-15",
"paymentDate": "2015-05-25",
"creditAmount": 914.99,
"debitAmount": 109.79,
"totalAmount": 805.2
}

Mktplace

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Mktplace

Hochgeladen von

Copyright:

Verfügbare Formate

Universidade do Estado de Santa Catarina

Centro de Educao Superior do Alto Vale do Itaja

PROJETANDO UMA API DE SERVIOS PARA

Palavras-chave: API. E-commerce. Marketplace.

DESIGNING AN API SERVICES TO PROVIDE A

Keywords: API. E-commerce. Marketplace.

O e-commerce, que em portugus significa comrcio eletrnico, uma modalidade de comrcio

encontram um novo canal de vendas ao consumidor e descreve que desde o surgimento do

2.3 HTTP: Documentos em envelopes

2.4 REST: Representational State Transfer

Para GLOVER (2008), REST uma forma de pensar, e no um protocolo ou um padro. um

Tarefa do Aplicativo Mtodo HTTP Descrio

Create POST Criar um novo recurso.

2.5 JSON: JavaScript Object Notation

O JSON (JavaScript Object Notation) um formato de serializao para estruturas de dados em

2.6 ROA: Resource-Oriented Architecture

RICHARDSON e RUBY (2007), propem a Arquitetura Orientada a Recursos (ROA), uma

Verificar quais mtodos HTTP um determinado recurso suporta: HTTP OPTIONS.

2.7 Melhores Prticas para REST e ROA

RICHARDSON e RUBY (2007) propem, em um capitulo especfico, algumas boas prticas

3. Projetando a API de servios para marketplace

3.1 Coleta das Regras de Negcios e Requisitos

Uma compreenso completa dos requisitos de software fundamental para um bem-sucedido

Ano Trimestre Total geral de pedidos Total de origem marketplace Percentual

Para o levantamento foram realizadas conversas com os responsveis comerciais e com o

3.2 Projetando a API

3.3 API Viso geral

ingls, atendendo as pretenses de expanso para o exterior da empresa envolvida na pesquisa.

Figura 1 Diagrama de classes comuns da API (Acervo do Autor).

3.4 Recurso: anncios (/items)

Figura 2 Diagrama de classes do recurso anncios (Acervo do Autor).

Os servios disponveis para o recurso de anncios so os seguintes:

Mtodo HTTP POST

Mtodo HTTP PUT

Mtodo HTTP PUT

Mtodo HTTP PUT

Mtodo HTTP PUT

Mtodo HTTP GET

Mtodo HTTP GET

3.5 Calculo do frete API lojista

Figura 3 Diagrama de classes do clculo de frete API Lojista (Acervo do Autor).

Mtodo HTTP POST

3.6 Recurso: pedidos (/orders)

Figura 4 Diagrama classes do recurso pedidos (Acervo do Autor).

Os servios disponveis para o recurso de pedidos so os seguintes:

Mtodo HTTP GET

Mtodo HTTP GET

Figura 5 Diagrama classes do recurso pedidos atualizao de status (Acervo do Autor).

Mtodo HTTP PUT

Mtodo HTTP PUT

Mtodo HTTP PUT

3.7 Recurso: atendimentos (/tickets)

Esse recurso se refere a atendimento ao cliente. Assim como os pedidos, os atendimentos so

Figura 6 Diagrama classes do recurso atendimentos (Acervo do Autor).

Mtodo HTTP GET

Mtodo HTTP POST

Mtodo HTTP PUT

3.8 Recurso: relatrios (/reports)

Esse recurso se refere a relatrios e extratos. A princpio est planejado a implementao de 2

Figura 7 Diagrama classes do recurso relatrios (Acervo do Autor).

Mtodo HTTP GET

Mtodo HTTP GET

3.9 Call-back de notificaes API lojista