PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope....

37
Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí PROJETANDO UMA API DE SERVIÇOS PARA DISPONIBILIZAÇÃO DE UM MARKETPLACE Maicon Sasse, Osmar de Oliveira Braz Junior Pós-Graduação em Engenharia de Software - PGES Centro de Educação Superior do Alto Vale do Itajaí - CEAVI Universidade do Estado de Santa Catarina - UDESC [email protected], [email protected] Resumo Este artigo tem por finalidade a análise e projeto para desenvolvimento de uma API de serviços para disponibilizar um ambiente de marketplace integrado a uma plataforma de e-commerce. Nesse documento serão demonstrados os conceitos de e-commerce e marketplace, bem como as técnicas de integração para a implementação de uma API de serviços. O levantamento dos requisitos necessários 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 padrões e melhores práticas, com todos os recursos e serviços necessários para a integração entre lojistas e marketplace. Utilizando essa abordagem não 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. Introdução A área de e-commerce vem crescendo constantemente, segundo o E-bit (2015) o ano de 2014 apresentou resultado bastante positivo no comércio eletrônico brasileiro, tendo superado mais uma vez a expectativa inicial para o faturamento do setor e registrado crescimento de 24% em relação a 2013. Comprar pela internet está ficando cada vez mais comum como também mostra o E-bit (2015) ao mencionar que 51,5 milhões de consumidores fizeram compra pela Internet no último ano, sendo 10,2 milhões de estreantes. Ter uma loja online não é mais somente para grandes empresas, mas cada vez mais pequenas e médias empresas vêm buscando espaço nesse segmento. Nessa busca por espaço na internet ter somente uma loja virtual não é mais suficiente, é preciso encontrar novos meios de vender, novos canais.

Transcript of PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope....

Page 1: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

PROJETANDO UMA API DE SERVIÇOS PARA DISPONIBILIZAÇÃO DE UM MARKETPLACE

Maicon Sasse, Osmar de Oliveira Braz Junior Pós-Graduação em Engenharia de Software - PGES

Centro de Educação Superior do Alto Vale do Itajaí - CEAVI Universidade do Estado de Santa Catarina - UDESC

[email protected], [email protected]

Resumo Este artigo tem por finalidade a análise e projeto para desenvolvimento de uma API de serviços para disponibilizar um ambiente de marketplace integrado a uma plataforma de e-commerce. Nesse documento serão demonstrados os conceitos de e-commerce e marketplace, bem como as técnicas de integração para a implementação de uma API de serviços. O levantamento dos requisitos necessários 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 padrões e melhores práticas, com todos os recursos e serviços necessários para a integração entre lojistas e marketplace. Utilizando essa abordagem não 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. Introdução

A área de e-commerce vem crescendo constantemente, segundo o E-bit (2015) o ano de 2014 apresentou resultado bastante positivo no comércio eletrônico brasileiro, tendo superado mais uma vez a expectativa inicial para o faturamento do setor e registrado crescimento de 24% em relação a 2013. Comprar pela internet está ficando cada vez mais comum como também mostra o E-bit (2015) ao mencionar que 51,5 milhões de consumidores fizeram compra pela Internet no último ano, sendo 10,2 milhões de estreantes. Ter uma loja online não é mais somente para grandes empresas, mas cada vez mais pequenas e médias empresas vêm buscando espaço nesse segmento. Nessa busca por espaço na internet ter somente uma loja virtual não é mais suficiente, é preciso encontrar novos meios de vender, novos canais.

Page 2: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação 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 são do que shopping centers virtuais que reúnem ofertas de diferentes fornecedores, despontam como uma tendência entre grandes marcas do varejo. Acompanhando esse movimento, pequenos e médios empresários pegam carona na visibilidade e capacidade de atrair tráfego de empresas como Magazine Luiza, Walmart, Extra, para expandir suas vendas. “O marketplace é espaço 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 também para o lojista que usa o espaço (SEBRAE, 2015). As integrações com o marketplace são feitas via API (Application Programming Interface) seguindo padrões REST, disponibilizadas pelo próprio e-commerce (B2W - Companhia Digital, 2014; Extra.com.br, 2014; Walmart.com.br, 2014).

Assim como outros grupos de comercio eletrônico, que dispõe 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 também deseja a criação 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 revisão de conceitos teóricos referentes a assuntos relevantes ao trabalho, demonstrando conceitos do ramo de negócio, e-commerce e marketplace. Ainda nessa primeira parte são apresentados os conceitos tecnológicos envolvidos para a criação de uma API para marketplace, abordando definições de REST, ROA, JSON e boas práticas para definição de API. A segunda parte é o desenvolvimento do projeto, descrevendo as soluções e os serviços necessários para a API, baseando-se nas regras e requisitos coletados (disponíveis no Apêndice A). O detalhamento das classes utilizadas, com exemplos em JSON estão disponíveis no Apêndice B.

2. Fundamentação Teórica

Neste tópico são apresentados os fundamentos e assuntos utilizados como base para realização deste trabalho. Os dois primeiros tópicos são referentes aos conceitos de negócio, nos tópicos seguintes é abordado os conceitos de tecnológicos baseados principalmente no livro RESTful Serviços Web de RICHARDSON e RUBY (2007).

2.1 E-commerce

O e-commerce, que em português significa comércio eletrônico, é uma modalidade de comércio que realiza suas transações financeiras por meio de dispositivos e plataformas eletrônicas, como computadores e celulares. Um exemplo deste tipo de comércio é comprar ou vender produtos em lojas virtuais (E-Commerce News, 2015).

Segundo WHINSTON, CHOI, & STAHL (2007) o e-commerce refere-se à utilização de meios eletrônicos e tecnologias para conduzir o comércio (compra, venda, transferência ou troca de produtos, serviços, e / ou de informação). Conforme TREPPER (2000), em sua forma mais pura, o termo e-commerce designa qualquer transação 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 serviços por dinheiro pela internet. É uma tecnologia capacitadora que permite às empresas aumentar a precisão e eficiência do processamento das transações do negócio. O e-commerce é também um meio que possibilita a troca de informações entre a empresa e seus clientes e fornecedores, beneficiando todos os envolvidos.

MEIRA Jr. (2002) descreve que o comércio eletrônico é considerado uma atividade fundamental para o desenvolvimento do setor produtivo pois possibilita a ampliação e a diversificação dos mercados consumidores. FURGERI (2001), comenta que as empresas

Page 3: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

encontram um novo canal de vendas ao consumidor e descreve que desde o surgimento do comercio eletrônico as empresas estão sempre a acompanhando esse novo mercado interativo, fascinadas pela facilidade de se comunicar com o consumidor, coletando, armazenando e recuperando suas preferências pessoais de forma automática e on-line.

2.2 Marketplace

O conceito de marketplace nasceu nos Estados Unidos, com o lançamento do e-Bay, em 1995, inicialmente um site de leilões, mas que evoluiu para uma plataforma de ofertas de produtos de diversas marcas. Posteriormente, a Amazon, que começou 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 múltiplas empresas ofertam e comercializam os seus produtos e serviços, a transação é processada pelo operador do próprio marketplace e os benefícios atingem a todos. VILHA (2002) descreve como "uma nova e vantajosa forma de conduzir negócios".

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 tráfego 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 tráfego 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 negócio impulsiona as suas receitas através do comissionamento recebido pelas vendas; a variedade de produtos ofertados estimulam a compra; o ticket médio da loja aumenta; e é mais fácil fidelizar os clientes.

• Já o consumidor encontra produtos de diversos segmentos em um só local, agregando valor à experiência de compra; tem acesso a preços mais competitivos; pode comprar em diferentes “lojas”, pagando pelos produtos em uma única transação.

O marketplace não redireciona os consumidores ao site de terceiros, e por concentrar toda a experiência 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, tráfego, mídia, e outros serviços e, em troca, fica com uma remuneração paga pelo lojista (que pode ser uma comissão sobre pedidos e/ou uma taxa fixa mensal). A fonte de renda do marketplace é, então, 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 negócios, criando o único Shopping Mercado do Brasil (Extra.com.br, 2014). Seus milhares de visitantes mensais encontram produtos vendidos por lojistas de todo o país, de diferentes portes e categorias.

2.3 HTTP: Documentos em envelopes

Entender o HTTP e suas partes é o primeiro passo para construção 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 também em um envelope e envia-o para o cliente. O HTTP tem padrões rigorosos para a aparência dos envelopes, mas não cuida muito do que está dentro.

Partes da solicitação HTTP:

Page 4: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

• Método HTTP (que no REST poderá ser chamado de “verbo HTTP” ou “ação HTTP”) indica como o cliente espera que o servidor processe este envelope.

• Path (nos termos da metáfora do envelope, o path é o endereço do envelope), também chamado de URI.

• Cabeçalhos da solicitação - são bits de metadados: os pares de chave-valor que agem como adesivos colocados no envelope.

• Corpo da entidade, também chamado de documento ou representação. A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em

três partes: • Código da resposta HTTP: este código numérico informa ao cliente se sua solicitação

foi bem ou insuficiente e como o cliente este envelope e seu conteúdo. • Cabeçalhos da resposta: exatamente como os cabeçalhos da solicitação, são adesivos

informativos colocados no envelope. O mais importante desses adesivos é o Content-

Type que fornece o tipo de mídia do corpo da entidade. Ex: text/html, application/xml. • Corpo da entidade e representação.

Todos os serviços web usam o HTTP, mas utilizam-no de maneiras diferentes. Uma solicitação para um serviço web REST coloca as informações do método no método HTTP e as informações de escopo na URI.

2.4 REST: Representational State Transfer

Para GLOVER (2008), REST é uma forma de pensar, e não um protocolo ou um padrão. É 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 não 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 são perfeitamente mapeados para necessidades de aplicativo de negócios padrão, como create read, update, and delete (CRUD). RICHARDSON e RUBY (2007), afirmam que REST não é uma arquitetura: é um conjunto de critérios de desenvolvimento. Esse autor, além das operações padrão CRUD, adiciona duas novas operações: headers e options. O mapeamento de funções da aplicação REST é mostrado na tabela abaixo.

Tarefa do Aplicativo Método HTTP Descrição

Create POST Criar um novo recurso. Read GET Recuperar a representação de um recurso. Update PUT Modificar um recurso existente. Delete DELETE Apagar um recurso existente. Headers HEAD Recuperar uma representação com metadados apenas. Options OPTIONS Verificar quais métodos 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 dissertação de PhD que o REST

"enfatiza a escalabilidade das interações do componente, a generalidade das interfaces, a implementação independente de componentes e componentes intermediários para reduzir a latência da interação, forçar a segurança e encapsular sistemas legados" (consulte Recursos). A construção de sistemas RESTful não é difícil, e os sistemas são altamente escaláveis, enquanto são fracamente acoplados aos dados subjacentes; eles também alavancam perfeitamente o armazenamento em cache. (GLOVER, 2008)

Page 5: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

2.5 JSON: JavaScript Object Notation

O JSON (JavaScript Object Notation) é um formato de serialização para estruturas de dados em geral. É muito mais leve e legível 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 programação (números, arrays, etc.) como strings. (RICHARDSON; RUBY, 2007)

2.6 ROA: Resource-Oriented Architecture

RICHARDSON e RUBY (2007), propõem a Arquitetura Orientada a Recursos (ROA), uma arquitetura concreta para o desenvolvimento de sistemas para a Web seguindo o estilo arquitetônico REST. A arquitetura ROA se apresenta como um conjunto de regras e boas práticas para a implementação de serviços que utilizam todo o potencial oferecido pela Web.

A ROA é um modo de transformar um problema em um serviço web REST: uma organização de URIs, HTTP e XML que funciona como o resto da web e que os programadores gostarão 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 execução de um algoritmo.

Tudo na Web (páginas, imagens, entre outras coisas) são a essência 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 exposição da tecnologia subjacente. (GLOVER, 2008)

Identificadores de Recursos (URI): Um recurso tem que ter pelo menos uma URI. A URI é o nome e o endereço de um recurso. Um recurso e sua URI devem ter uma correspondência clara. Ex: /software/realease/latest. As URIs devem ter uma estrutura e devem variar de modo previsíveis.

Representações: A representação fala sobre o estado do recurso. A principal finalidade de qualquer representação é enviar o estado do recurso. O “estado do recurso” é praticamente qualquer informação sobre o recurso subjacente. Os formatos de representação mais comuns são o XML e o JSON.

As quatro propriedades da ROA são: Endereçamento: diz que toda parte interessante da informação que o servidor pode fornecer

deve ser exibida como um recurso e dada em sua própria URI. Falta de estado: A falta de estado significa que toda solicitação HTTP ocorre em um

isolamento completo. Quando um cliente faz uma solicitação HTTP, inclui todas as informações necessárias para o servidor satisfazer-lhe. O servidor nunca conta com as informações das solicitações anteriores.

Conectividade: É a propriedade que permite que um cliente navegue por entre os recursos da aplicação através de enlaces hipermídia embutidos nas representações, ou seja documentos que contêm não apenas dados, mas links para outros recursos.

Interface uniforme: Em toda web, existem apenas algumas coisas básicas que você pode fazer em um recurso. O HTTP fornece quatro métodos básicos para as quatro operações mais comuns:

• Recuperar a representação 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 representação com metadados apenas: HTTP HEAD;

Page 6: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

• Verificar quais métodos HTTP um determinado recurso suporta: HTTP OPTIONS.

2.7 Melhores Práticas para REST e ROA

RICHARDSON e RUBY (2007) propõem, em um capitulo específico, algumas boas práticas para a implementação correta de serviços REST utilizando os conceitos de ROA. Eles descrevem os seguintes passos como sendo uma boa prática:

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) representações aceitas pelo cliente. 6. Projete a(s) representações fornecidas ao cliente. 7. Integre esse recurso aos recursos existentes, usando links hipermídia e formulários. 8. Considere o caminho típico dos eventos: o que deve acontecer? 9. Considere as condições 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 princípio numa primeira leitura pode parecer redundância, porem o motivo é justamente ressaltar a importância dos mesmos para uma boa implementação.

Outras dicas descritas por eles que merecem destaque são: Representação de saída: Use os códigos de status HTTP para informar como o cliente deve

considerar o documento que você está servindo. Se houver erro, você deve definir o código de status para indicar uma condição de erro apropriada, possivelmente 400 (“Bad Request”). Do contrário, o cliente poderá tratar sua mensagem de erro como uma representação do recurso que ele requisitou.

O código de status diz para que serve o documento. Já o cabeçalho de resposta Content-Type diz que formato está o documento. Sem esse cabeçalho, seus clientes não saberão como analisar ou tratar os documentos servidos por você.

Estabelecendo versões para os serviços: Se essa a regra for mudada, alguns clientes escritos por você quebraram. Em situações desse tipo, o serviço deve permitir um período de transição no qual recursos antigos funcionem lado a lado com os novos. A forma mais simples de fazer isto consiste em incorporar as informações de versão, tornando-a a primeira variável do path: /v1/resource versus /v2/resource.

Mesmo um serviço bem encadeado pode precisar de novas versões. Às vezes, reescrever um serviço altera o significado das representações e todos os clientes quebram, mesmo os que compreendiam as deixas semânticas anteriores. Em caso de dúvida, estabeleça versões para seus serviços.

Compactação: Representações textuais podem ser compactadas a uma fração de seu tamanho. Uma biblioteca cliente para o HTTP pode requisitar uma versão compactada de sua representação, e em seguida, descompacta-la de forma transparente para seu usuário. Junto com a requisição HTTP o cliente envia um cabeçalho Accept-Encoding, que diz os tipos de algoritmos de compactação compreendidos pelo cliente. Se o servidor compreender o Accept-

Encoding, ele poderá compactar a representação antes de servi-la. O servidor envia o mesmo Content-Type que enviaria se a representação não estivesse compactada. E também envia o cabeçalho Content-Encoding para informar ao cliente que o documento foi compactado. Essa técnica pode economizar muita largura de banda com pouquíssimo custo em termos de complexidade adicional.

Page 7: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

Outras boas práticas de uma API REST são descritas por MULLOY (2002), • O princípio número 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 fácil.

• Use duas URLs de base por recurso. A primeira URL é para uma coleção; a segunda é para um elemento específico na coleção. Ex: /dogs e /dogs/1234.

• Mantenha verbos fora de seus URLs de base. • Use MÉTODOS de HTTP para operar nas coleções 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. Porém, tendo em conta que a primeira coisa que a maioria das pessoas provavelmente fazem com uma API RESTful é um GET, nós 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 método como eles aprendem a trabalhar com sua API.

• Resposta parcial: permite dar aos desenvolvedores apenas a informação de que necessitam.

• Paginação: Use limit e offset para tornar mais fácil para os desenvolvedores para paginar objetos.

• Use JSON como padrão. • Siga convenções JavaScript para nomear atributos:

o Use a capitalização medial (aka CamelCase), Ex: tipoContato. o Use letras maiúsculas ou minúsculas, dependendo do tipo de objeto.

Seguindo as práticas e orientações desses autores, temos um bom embasamento para a criação de uma API funcional e intuitiva.

3. Projetando a API de serviços para marketplace

Esta seção dedica-se ao desenvolvimento do trabalho. Iniciada pela coleta de regras de negócio e requisitos e a separação do resultado em grupos. Logo após é apresentada uma visão geral da API, onde são mostrados conceitos que vão abranger todos os recursos. Por fim são detalhados os recursos e seus serviços que a API vai disponibilizar, com diagramas das classes de domínio das representações de entrada e saída dos mesmos.

3.1 Coleta das Regras de Negócios e Requisitos

Uma compreensão completa dos requisitos de software é fundamental para um bem-sucedido desenvolvimento de software. A tarefa de análise de requisitos é um processo de descoberta, refinamento, modelagem e especificação (PRESSMAN, 1995). O levantamento das regras e requisitos necessários 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 Comércio Eletrônico 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.

Page 8: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

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 responsáveis comerciais e com o

grupo de TI da empresa. As soluções de marketplace utilizadas pela empresa também foram fontes de pesquisa. O resultado completo da coleta de regras e requisitos está no Apêndice A desse documento.

A empresa pretende ainda em 2015 lançar seu marketplace próprio, visando expandir seu portfólio de produtos e suas vendas, realizando novas parcerias comerciais. Outro fator importante é o fato que a disponibilização desse recurso agregará valor a plataforma de e-commerce da empresa, que há pretensão de futuramente ser comercializada. Além disso a empresa tem pretensões de expansão para outros países como mostra a visão da empresa: "Ser a maior e melhor operação de varejo online, especializada em celulares e smartphones da América Latina, atuando também com soluções em e-commerce, presente em mais de 5 países e com receita bruta anual superior a R$ 1 bilhão até 31/12/2020" (Magamobi, 2015).

3.2 Projetando a API

Após o levantamento das regras e requisitos, é possível 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 avaliação dos anúncios enviados e posteriormente a associação e categorização do anuncio afim de disponibiliza-lo para venda nos sites do marketplace. Também no gerencial serão feitos o cadastramento dos ciclos de vendas e o percentual de comissão que o marketplace irá receber por venda.

API: Parte central da integração, ela será o meio de integração entre o lojista e marketplace, por meio dela o lojista fará a gestão de seus anúncios e pedidos. A API vai disponibilizar todos os recursos e funcionalidades necessários 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: anúncios, pedidos, atendimentos e relatórios. Os recursos, e suas operações, serão descritos posteriormente.

API lojista: O lojista também deve implementar alguns serviços para o marketplace invocar. O serviço essencial é o de cálculo de frete para a venda dos anúncios. O outro serviço é o call-back das notificações que o marketplace envia ao lojista, esse serviço é opcional. Esses serviços também deverão seguir os padrões REST e ROA. A função do marketplace nessa parte é apenas documentar as representações de entrada e saída esperadas.

Alterações no site: São as alterações necessárias para que os anúncios do lojista sejam listados no site.

O foco do presente documento se concentra na área de integrações via API.

3.3 API – Visão geral

Nesse tópico será abordado aspectos comuns a todos os recursos da API que está sendo proposta. Idioma das representações e serviços: Toda a API (serviços, classes de domínio das

representações de entrada e saída e seus respectivos atributos) foram modelados no idioma

Page 9: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

inglês, atendendo as pretensões de expansão para o exterior da empresa envolvida na pesquisa. Essa é uma prática comum (todas as quatro APIs analisadas de marketplace que a empresa utiliza também seguem esse padrão) pois o idioma inglês é considerado a língua universal.

Autenticação: Algo extremamente importante ao construir uma API é definir de qual forma será feita a autenticação do usuário. Para esse projeto foi escolhido o padrão de autenticação básica (Basic Auth), por ser simples e eficaz, além de ser bem conhecido entre a comunidade de desenvolvedores. Para garantir a segurança no tráfego de informações entre lojista de marketplace, todas as requisições 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 padrão Basic Auth. RICHARDSON e RUBY (2007), descrevem que a autenticação básica consiste em um simples conjunto desafio/resposta. Se você tentar acessar um recurso protegido por autenticação básica e não fornecer as credenciais adequadas, vai receber um desafio e terá que repetir a requisição. O servidor desafia a repetir minha requisição com as credenciais corretas. Para responder a um desafio da autenticação básica, o cliente precisa de um nome de usuário e senha. Uma vez que o cliente tenha as informações, o nome de usuário e a senha são combinados em uma única string e codificados por meio da codificação base64. Essa string de caracteres aparentemente aleatória é o valor do cabeçalho Authorization. O Servidor decodifica essa string e compara com a lista de usuários e senhas. Se eles forem iguais, a resposta continua sendo processada. Se não, a requisição falha e código de resposta é o 401 (“Unauthorized” / Não Autorizado).

Erros: Quando houver erro na requisição a API, o código de resposta HTTP irá identificar o mesmo. Esses códigos de erro podem ser classificados em dois grupos, erros da parte do lojista (representados pela família de código 400), e os erros internos do servidor da aplicação (representados pela família de código 500). Nesses casos a representação de saída do serviço será um objeto Error (Figura 1). Os erros mais comuns por parte do cliente são: atributos obrigatórios não preenchidos, identificador duplicado (no caso de serviços de criação) e consulta a recursos inexistentes.

Consultas de listagem: Existem serviços de consulta que retornam uma lista de recursos. Para evitar uma representação de saída muito grande, é necessário paginar os registros. O conceito é o mesmo utilizado em banco de dados. Isso é feito enviando os parâmetros _limit (quantidade de registros por pagina) e _offset (posição inicial da consulta), por exemplo _limit=30&_offset=60 trará 30 registros a partir da posição 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 parâmetro _attributes, por exemplo enviado _attributes=id,name, somente esses atributos estarão disponíveis nos registros listados na consulta. O parâmetro de ordenação dos registros é _sort, e as possíveis formas de ordenação são definidas pelo serviço em específico.

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

Conectividade: Quando houver um atributo no objeto que é uma referência a algum outro

recurso, é utilizado o objeto Link (Figura 1), contendo o identificador do recurso associado e sua URI.

Page 10: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

3.4 Recurso: anúncios (/items)

Esse recurso é o primeiro passo da integração, para vender dentro dos sites do marketplace é necessário o envio/cadastro dos dados do anúncio (produto). Esses dados serão avaliados pelo marketplace e posteriormente, se tudo estiver correto, serão disponibilizados para a venda. Seria algo como perguntar: marketplace, vende esse produto para mim? Na figura 2, é apresentado o diagrama das classes de domínio utilizadas nesse recurso, são as representações de entrada dos serviços. Os atributos das classes detalhados, e exemplo da representação JSON, podem ser encontrados no Apêndice B desse documento.

Figura 2 – Diagrama de classes do recurso anúncios (Acervo do Autor).

Os serviços disponíveis para o recurso de anúncios são os seguintes: Cadastro do anúncio: Esse é o serviço invocado pelo lojista para enviar os dados dos anúncios

que deseja vender no marketplace, é possível fazer o envio de mais de um anúncio por vez, pois o serviço aceita uma lista de anúncios.

Método HTTP POST URI /items Representação de entrada Array de objetos Item Código de resposta HTTP de sucesso 201 Representação de saída de sucesso Nenhum

Tabela 3 – Especificação do serviço POST /items (Acervo do Autor).

Atualização do anúncio: Esse é o serviço invocado pelo lojista para atualizar todos os dados do anúncio. Acessível enquanto o anuncio estiver na fase inicial de cadastro, principalmente para corrigir informações cadastrais. Após o anúncio aprovado o serviço irá retornar erro 403.

Método HTTP PUT URI /items/{ID} Representação de entrada Objeto Item Código de resposta HTTP de sucesso 204 Representação de saída de sucesso Nenhum

Tabela 4 – Especificação do serviço PUT /items/{ID} (Acervo do Autor). Atualização de preço do anúncio: Esse é o serviço invocado pelo lojista para atualizar as

informações de preço do anúncio.

Page 11: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

Método HTTP PUT URI /items/{ID}/price Representação de entrada Objeto Price Código de resposta HTTP de sucesso 204 Representação de saída de sucesso Nenhum

Tabela 5 – Especificação do serviço PUT /items/{ID}/price (Acervo do Autor). Atualização de estoque do anúncio: Esse é o serviço invocado pelo lojista para atualizar a

quantidade disponível para venda do anúncio.

Método HTTP PUT URI /items/{ID}/stock Representação de entrada Objeto Stock Código de resposta HTTP de sucesso 204 Representação de saída de sucesso Nenhum

Tabela 6 – Especificação do serviço PUT /items/{ID}/stock (Acervo do Autor).

Ativação e desativação do anúncio: Esse é o serviço invocado pelo lojista para ativar o desativar a venda do anúncio. Anúncios desativados não são apresentados no site do marketplace.

Método HTTP PUT URI /items/{ID}/status Representação de entrada Objeto Active Código de resposta HTTP de sucesso 204 Representação de saída de sucesso Nenhum

Tabela 7 – Especificação do serviço PUT /items/{ID}/status (Acervo do Autor).

Embora pareça redundante ter 4 serviços para atualização do anuncio, isso é necessário e comum entre as APIs de marketplace.

Consulta geral de anúncios: Esse é o serviço invocado pelo lojista para consultar a lista dos seus anúncios no marketplace. O serviço segue o padrão geral de consultas de listagem.

Método HTTP GET URI /items/ Parâmetros de filtro brand, title, active, status Parâmetros de ordenação id (padrão), title Representação de entrada Nenhum Código de resposta HTTP de sucesso 200 Representação de saída de sucesso Objeto List, contendo um array de ItemResponse

Tabela 8 – Especificação do serviço GET /items (Acervo do Autor). Consulta de anúncio: Esse é o serviço invocado pelo lojista para consultar os dados de um

anúncio em específico, tendo como referência seu identificador. Caso o recurso não exista será retornado erro 404.

Método HTTP GET URI /items/{ID} Representação de entrada Nenhum Código de resposta HTTP de sucesso 200 Representação de saída de sucesso Objeto ItemResponse

Tabela 9 – Especificação do serviço GET /items/{ID} (Acervo do Autor).

Page 12: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

3.5 Calculo do frete – API lojista

Esse recurso é o segundo passo da integração. Após os anúncios estarem a venda no site do marketplace, é necessário que haja uma simulação do frete a ser pago pelo envio. O cálculo de frete é um serviço que o lojista deve implementar conforme as orientações e padronizações definidas pelo marketplace. É enviado para o lojista as informações dos itens e quantidades, e o CEP de destino da mercadoria (objeto FreightPreview). O lojista deve retornar os serviços disponíveis de entrega, seus valores e prazo de entrega (objeto FreightPreviewResponse). Na figura 3, é apresentado o diagrama das classes de domínio utilizadas nesse recurso, são as representações de entrada e saída do serviço. Os atributos das classes detalhados, e exemplo da representação JSON, podem ser encontrados no Apêndice B desse documento.

Figura 3 – Diagrama de classes do cálculo de frete – API Lojista (Acervo do Autor).

Caso ocorra algum erro, o lojista deve retornar um código de resposta HTTP de erro, e

retornar na representação um objeto Error, nos mesmos moldes dos serviços disponibilizados pelo marketplace.

Método HTTP POST URI /orders/freightPreview Representação de entrada Objeto FreightPreview Código de resposta HTTP de sucesso 200 Representação de saída de sucesso Objeto FreightPreviewResponse

Tabela 10 – Especificação do serviço de cálculo de frete – API lojista (Acervo do Autor).

3.6 Recurso: pedidos (/orders)

Esse recurso é o terceiro passo da integração. Os anúncios 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 situações: novo, aprovado (pago), em transporte, entregue. O pedido também pode vir a ser cancelado, caso não seja identificado o pagamento ou haja solicitação de cancelamento. Na figura 4, é apresentado o diagrama das classes de domínio utilizadas nesse recurso, são as representações de saída do serviço. Os atributos das classes detalhados, e exemplo da representação JSON, podem ser encontrados no Apêndice B desse documento.

Page 13: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

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

Os serviços disponíveis para o recurso de pedidos são os seguintes: Consulta geral de pedidos: Esse é o serviço 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 aprovações. O serviço segue o padrão geral de consultas de listagem.

Método HTTP GET URI /orders Parâmetros de filtro dateCreated, status, itemId Parâmetros de ordenação id (padrão) Representação de entrada Nenhum Código de resposta HTTP de sucesso 200 Representação de saída de sucesso Objeto List, contendo um array de Order

Tabela 11 – Especificação do serviço GET /orders (Acervo do Autor).

Consulta de pedido: Esse é o serviço invocado pelo lojista para consultar os dados de um pedido em específico, tendo como referência seu identificador. Caso o recurso não exista será retornado erro 404.

Método HTTP GET URI /orders/{ID} Representação de entrada Nenhum Código de resposta HTTP de sucesso 200 Representação de saída de sucesso Objeto Order

Tabela 12 – Especificação do serviço GET /orders/{ID} (Acervo do Autor).

Após ser feita a importação 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 domínio utilizadas para a atualização do status do recurso, são as representações de entrada do serviço. Os atributos das classes detalhados, e exemplo da representação JSON, podem ser encontrados no Apêndice B desse documento. Os serviços disponíveis para a atualização são descritos logo abaixo.

Page 14: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

Figura 5 – Diagrama classes do recurso pedidos – atualização de status (Acervo do Autor).

Atualização do pedido para “em transporte”: Esse é o serviço invocado pelo lojista para

notificar o marketplace da entrega dos itens do pedido a transportadora. Nele serão enviados os dados de nota fiscal e dados de rastreamento na transportadora. Somente pedidos aprovados (pagos) podem ser atualizados para “em transporte”.

Método HTTP PUT URI /orders/{ID}/shipped Representação de entrada Objeto Shipping Código de resposta HTTP de sucesso 204 Representação de saída de sucesso Nenhum

Tabela 13 – Especificação do serviço PUT /orders/{ID}/shipped (Acervo do Autor).

Atualização do pedido para “entregue”: Esse é o serviço invocado pelo lojista para notificar o marketplace da entrega dos itens do pedido ao cliente. Somente pedidos em transporte podem ser atualizados para entregue.

Método HTTP PUT URI /orders/{ID}/delivered Representação de entrada Objeto Delivery Código de resposta HTTP de sucesso 204 Representação de saída de sucesso Nenhum

Tabela 14 – Especificação do serviço PUT /orders/{ID}/delivered (Acervo do Autor).

Cancelamento do pedido: Esse é o serviço invocado pelo lojista para notificar o marketplace do cancelamento do pedido. Somente pedidos novos ou aprovados podem ser cancelados.

Método HTTP PUT URI /orders/{ID}/canceled Representação de entrada Objeto Canceled Código de resposta HTTP de sucesso 204 Representação de saída de sucesso Nenhum

Tabela 15 – Especificação do serviço PUT /orders/{ID}/canceled (Acervo do Autor).

Page 15: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

3.7 Recurso: atendimentos (/tickets)

Esse recurso se refere a atendimento ao cliente. Assim como os pedidos, os atendimentos são 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 domínio utilizadas no recurso, são as representações de entrada e saída do serviço. Os atributos das classes detalhados, e exemplo da representação JSON, podem ser encontrados no Apêndice B desse documento.

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

Consulta geral dos atendimentos: Esse é o serviço invocado pelo lojista para consultar os

atendimentos do lojista no marketplace. O serviço segue o padrão geral de consultas de listagem.

Método HTTP GET URI /tickets Parâmetros de filtro dateCreated, status, lastUpdate Parâmetros de ordenação id (padrão), lastUpdate Representação de entrada Nenhum Código de resposta HTTP de sucesso 200 Representação de saída de sucesso Objeto List, contendo um array de Ticket

Tabela 16 – Especificação do serviço GET /tickets (Acervo do Autor).

Inserir mensagem no atendimento: Esse é o serviço invocado pelo lojista para inserir uma mensagem (resposta) no atendimento.

Método HTTP POST URI /tickets/{ID}/messages Representação de entrada Objeto Message Código de resposta HTTP de sucesso 201 Representação de saída de sucesso Nenhum

Tabela 17 – Especificação do serviço PUT /tickets/{ID}/messages (Acervo do Autor).

Finalizar atendimento: Esse é o serviço invocado pelo lojista para encerrar o atendimento. Após o atendimento finalizado não é mais possível adicionar mensagens.

Método HTTP PUT URI /tickets/{ID}/finalize Representação de entrada Objeto Message (opcional) Código de resposta HTTP de sucesso 204 Representação de saída de sucesso Nenhum

Tabela 18 – Especificação do serviço PUT /tickets/{ID}/finalize (Acervo do Autor).

Page 16: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

3.8 Recurso: relatórios (/reports)

Esse recurso se refere a relatórios e extratos. A princípio está planejado a implementação de 2 serviços, ambos relacionados ao repasse financeiro ao lojista. Na figura 7, é apresentado o diagrama das classes de domínio utilizadas no recurso, são as representações de saída do serviço. Os atributos das classes detalhados, e exemplo da representação JSON, podem ser encontrados no Apêndice B desse documento. Os serviços são descritos logo a seguir.

Figura 7 – Diagrama classes do recurso relatórios (Acervo do Autor).

Consulta dos repasses financeiros: Esse é o serviço invocado pelo lojista para consultar os

repasses financeiros feitos pelo marketplace. Cada repasse corresponde a um ciclo de pedidos. O serviço segue o padrão geral de consultas de listagem.

Método HTTP GET URI /reports/transfers Representação de entrada Nenhum Código de resposta HTTP de sucesso 200 Representação de saída de sucesso Objeto List, contendo um array de Transfer

Tabela 19 – Especificação do serviço GET /reports/transfers (Acervo do Autor).

Consulta dos movimentos os repasse financeiro: Esse é o serviço invocado pelo lojista para consultar o detalhamento das movimentações que compreendem um repasse financeiro específico. O serviço segue o padrão geral de consultas de listagem.

Método HTTP GET URI /reports/transfers/{ID}/transaction Representação de entrada Nenhum Código de resposta HTTP de sucesso 200 Representação de saída de sucesso Objeto List, contendo um array de Transaction

Tabela 20 – Especificação do serviço GET /reports/transfers/{id} (Acervo do Autor).

3.9 Call-back de notificações – API lojista

Esse recurso se refere a notificações de eventos ocorridos no marketplace. Sua implementação pelo lojista é opcional, porem recomendada. Na figura 8, é apresentado o diagrama das classes de domínio utilizada para a notificação, é a representação de entrada do serviço. Os atributos das classes detalhados, e exemplo da representação JSON, podem ser encontrados no Apêndice B desse documento.

Figura 8 – Diagrama classe da notificação (Acervo do Autor).

Page 17: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

Os eventos notificados para o lojista são: • Anúncio aprovado • Anúncio recusado • Pedido incluído • Pedido aprovado • Pedido cancelado • Atendimento incluído • Atendimento alterado (nova mensagem incluída) • Atendimento encerrado

Método HTTP POST URI /notification Representação de entrada Objeto Notification Código de resposta HTTP de sucesso 200 Representação de saída de sucesso Nenhum

Tabela 21 – Especificação do serviço de notificação – API lojista (Acervo do Autor).

4. Trabalhos correlatos

O primeiro trabalho correlato é intitulado “Relacionamentos no varejo eletrônico: 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 criação dos sites Americanas.com e Submarino, em 2005 a empresa adquiriu o Shoptime. Em outubro de 2013 lançou o serviço de marketplace no site Submarino, em junho de 2014 disponibilizou o serviço no site Americanas.com e em janeiro de 2015 no site Shoptime. Possui 2 versões da API:

Versão 1: apresentava os recursos básicos necessários para integração: para o recurso de anúncios são disponibilizados os serviços de envio, atualização de preço, atualização de estoque, atualização de status e consulta individual e listagem. Para o recurso de pedidos é disponibilizado a consulta individual e listagem e as opções de atualização do status do pedido para nota fiscal emitida, em transporte e entregue. Nessa versão não existe nenhum tipo de call-back a ser implementado pelo lojista e o cálculo 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 autenticação utilizada é Basic Auth. Essa versão foi desativada em 30/04/2015.

Versão 2: Apresenta uma melhoria evolutiva, sem alterações na forma como funcionava a versão anterior. Foram adicionadas algumas novas informações nas classes de domínio, como imagens do anuncio, XML da nota fiscal e URL para o rastreamento na transportadora do pedido. Foram adicionados serviços de atualização em lote de preço e estoque dos anúncios. Outra melhoria disponibilizada foi permitir configurar, opcionalmente, um call-back para notificação para receber alertas das alterações de pedido. Também é possível definir um call-back para realizar o cálculo do frete do pedido, deixando o valor do frete mais preciso para o cliente. A documentação completa da versão 2 está disponível 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 negócios, criando o único Shopping Mercado do Brasil. (Extra.com.br, 2015). Possui 2 versões da API:

Page 18: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

Versão 1: Assim como a versão 1 da B2W, apresenta recursos para manipular anúncios e os pedidos. A diferença dessa API em relação versão 1 da B2W é o recurso de permitir enviar mais de um anuncio na mesma requisição POST, mandando vários itens dentro de um array. Os dados dessa requisição são compactados no formato GZip. O cálculo de frete pode ser feito via planilha ou por call-back configurado. Existe call-back para notificação das alterações de status de anúncios e pedidos. A forma de autenticação utilizada é própria e se baseia em um par de chaves enviado no cabeçalho de cada requisição. A documentação está disponível em https://desenvolvedores.extra.com.br/api-portal/docs/apilojistav1/main/index.html.

Versão 2: Ao contrário da B2W, a segunda versão da API do Extra foi completamente redesenhada: alterou-se o método de autenticação para oAuth 2.0 e todas as classes de domínio dos serviços foram remodeladas. Todo o contrato dos serviços foi quebrado, necessitando por parte dos lojistas uma implementação praticamente do zero. As principais melhorias foram adicionadas a informações do pedido o site de origem, e o status atual do pedido. Na parte dos anúncios foi disponibilizado o serviço de ativação/desativação 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 documentação está disponível em http://desenvolvedores.cnova.com/api-portal/docs/apilojista/main/index.html.

Walmart: Sua API apresenta diferenças consideráveis em relação as outras estudadas. O gerenciamento do recurso de anúncios em geral é semelhante aos outros marketplace, existindo um diferencial que o todos os dados do anuncio podem ser alterados após a aprovação do mesmo. O grande diferencial está no recurso de pedidos, enquanto nos outros marketplace a implementação de call-backs é opcional, o Walmart exige a implementação de uma API do lojista, com um os seguintes serviços: cálculo de frete, teste de conectividade, criação de pedido, aprovação de pedido e cancelamento do pedido. Se os serviços do lojista estiverem off-line, não é permitido finalizar a venda no site do marketplace. Não existe serviço de consulta aos dados de pedidos. É possível enviar e retornar as representações em formato JSON e XML. A forma de autenticação utilizada é Basic Auth. A documentação está disponível em http://adapter.waldev.com.br/.

Mercado Livre: Fundada em 1999, MercadoLivre é uma companhia de tecnologia líder em comércio eletrônico na América Latina. Por meio de suas principais plataformas MercadoLivre.com e MercadoPago.com, oferece soluções de comércio eletrônico 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 documentação vasta. Através da API é possível acessar informações de recursos de usuários, categorias dos anúncios, realizar prévias dos valores cobrados pelo anuncio e venda de um item, responder perguntas de usuários, fazer avaliação (feedback) de compradores, gerar etiquetas de postagem (quando utilizado o Mercado Envios como forma de postagem), entre outros. Destaque para a replicação praticamente instantânea de qualquer alteração feita no anuncio ou pedido via API para a visualização no site. A forma de autenticação é oAuth 2.0 e é necessário criar apps e definir quais recursos esse terá privilégio. O usuário ao conectar deve confirmar as permissões que o app terá. A documentação está disponível 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 informações que não estão disponibilizadas na API.

Abaixo vamos realizar 2 comparativos: o primeiro expondo as implementações dos marketplace acimas ao padrões e melhores práticas descritos no capitulo 2.7 desse artigo (Tabela 22).

Page 19: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

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 Compactação - Sim Sim - - - Recursos no plural - Sim Sim Sim - Sim Resposta parcial - - Sim - - Sim Paginação Sim Sim Sim Sim Sim Sim CamelCase Sim Sim Sim Sim - Sim

Tabela 22 – Boas Práticas versus APIs. Fonte: documentação B2W, CNova, Walmart e Mercado Livre. (Acervo do Autor).

Conforme mostra a tabela 22, a API proposta somente não implementa o padrão de compactação. Sua implementação não é avaliada como necessária pois praticamente todas as requisições tem pouco volume de dados trafegando. Para as consultas (onde pode haver maior volume de dados, dependendo do filtro utilizado), o padrão de resposta parcial é mais recomendado para diminuir o tamanho das representações.

O segundo é comparativo é com relação aos recursos disponibilizados pelas API (Tabela 23).

B2W Extra (V1) Extra (V2) Walmart Mercado Livre Magamobi

Envio de anúncios Sim Sim Sim Sim Sim Sim Envio múltiplo de anúncios - Sim Sim - - Sim Notificações V2 Sim Sim - - Sim Atualização de preço/estoque Sim Sim Sim Sim Sim Sim Atualização de geral anuncio - - - Sim Parcial Parcial Consulta de pedidos Sim Sim Sim - Sim Sim Atualização pedido Em Transporte

Sim Sim Sim Sim Sim Sim

Atualização pedido Entregue Sim Sim Sim - Sim Sim Atualização pedido Cancelado

- Sim Sim Sim - Sim

Consulta a atendimentos - - Sim - Sim Sim Relatório de pagamentos - - - - - Sim Portal do lojista Sim Sim Sim Sim Sim -

Tabela 23 – Recursos disponíveis versus APIs. Fonte: documentação B2W, CNova, Walmart e Mercado Livre. (Acervo do Autor).

Conforme mostra a tabela 23, a API proposta possui todos os principais recursos em

comparação às outras APIs avaliadas, não necessitando da implementação do portal do lojista. O recurso de atualização geral do anúncio é parcial, pois não é permitido alteração geral após o anúncio estar disponível para venda no site.

5. Considerações Finais

Este trabalho consistiu na formação de uma análise para implementação de um ambiente de marketplace integrado a uma plataforma existente de e-commerce. O foco principal foi a área de integração, via API de serviços. Embora tenha o foco na API, foi necessário compreender e analisar todo o fluxo de funcionamento de um marketplace, e onde seriam necessárias as alterações em outras partes da plataforma. Não se pode modelar uma parte sem conhecer o todo, e isso é levado como uma lição aprendida desse projeto.

Analisar as soluções existentes no mercado é uma boa prática para coletar requisitos, avaliar seus pontos fortes e diferenças entre implementações fazem o seu projeto extrair o melhor de todos eles e se tornar um diferencial.

Antes de modelar as classes e serviços, é importante conhecer os padrões e boas práticas relacionados a tecnologia que a solução vai ser desenvolvida. Como se trata de serviços que

Page 20: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

outras aplicações utilizarão, se seus serviços seguem um padrão conhecido, sua utilização por terceiros será facilitada.

O diferencial da solução apresentada em relação as soluções estudadas é o fato de via API, o lojista poder efetuar todas as operações 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 conciliação financeira, não necessitando acessar nenhum “portal do lojista” para algumas pequenas operações. Para o marketplace, a vantagem é que o mesmo não precisa realizar a implementação e manter uma aplicação “portal do lojista”, o tempo e recursos gastos para manter essa aplicação podem ser utilizados para desenvolver serviços.

Referências

B2W - Companhia Digital. API Submarino Marketplace. 2014. Disponível em: <http://api-marketplace.submarino.com.br/docs/> Acessado em 25 de fevereiro de 2015.

E-BIT. 31ª edição WebShoppers: Comércio eletrônico cresce 24% em 2014 e maior acesso aos smartphones ajuda a alavancar mobile commerce. 2015. Disponível 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. Disponível 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. Disponível 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. Disponível em: <https://desenvolvedores.extra.com.br/api-portal/docs/apilojistav1/apis/index.html> Acessado em 25 de fevereiro de 2015.

FURGERI, Sérgio. Business to Business: Aprenda a desenvolver aplicações. São Paulo: Érica, 2001.

GILBERTONI, Mariana. Marketplaces: sua loja já aderiu?. 2014. Disponível em: <http://www.ecommercebrasil.com.br/artigos/marketplaces-sua-loja-ja-aderiu/> Acessado em 23 de fevereiro de 2015.

GLOVER, Andrew. Construa um Serviço da Web RESTful. 2008. Disponível 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 prático para o desenvolvimento de web services em Java. São Paulo: Novatec Editora, 2009, 13.

GRANDES, Luisa Ancona. Relacionamentos no varejo eletrônico: Um estudo de caso sobre o marketplace e seus parceiros. São Paulo, 2013.

HUNGRIA, Camila. Pegando carona nas grandes marcas. São Paulo. 2014. Disponível em: <http://www.dcomercio.com.br/categoria/tecnologia/pegando_carona_nas_grandes_marcas/> Acessado em 24 de fevereiro de 2015.

Page 21: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

MAGAMOBI. 2015. Disponível em: <http://www.magamobi.com.br/> Acessado em 24 de abril de 2015.

MEIRA Jr., Wagner. [et al.]. Sistemas de Comércio Eletrônico: Projeto e desenvolvimento. Rio de Janeiro: Campus, 2002, 1.

Mercado Livre. Sobre Mercado Livre. 2015. Disponível em: <http://institucional.mercadolivre.com.br/sobre-mercadolivre/> Acessado em 24 de abril de 2015.

Mercado Livre. MercadoLibre Developers Site. 2015. Disponível em: <http://developers.mercadolibre.com/> Acessado em 24 de abril de 2015.

MULLOY, Brian. Web API Design - Crafting Interfaces that Developers Love. 2012. Disponível 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. São Paulo: Makron Books, 1995.

RICHARDSON, Leonard. RUBY, Sam. RESTful serviços Web. Tradução Eveline Vieira e Patricia Azeredo. Rio de Janeiro: Alta Books, 2007

SEBRAE. Conheça as vantagens do e-marketplace para os pequenos negócios. Disponível 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. Estratégias de E-commerce. Tradução 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, Anapatrícia Morales. E-marketing para bens de consumo durável. Rio de Janeiro: Editora FGV, 2002

W3C Escritório Brasil. Manual dos dados abertos: desenvolvedores. São Paulo: 2001. Disponível em: < http://www.w3c.br/pub/Materiais/PublicacoesW3C/manual_dados_abertos_desenvolvedores_web.pdf> Acessado em 23 de fevereiro de 2015.

Walmart. Wal-Mart Marketplace RESTful API. 2014. Disponível 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.

Page 22: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

APÊNDICE A – Regras de negócios e requisitos coletados Este apêndice demonstra o resultado da coleta de regras de negócio e requisitos necessários

para a criação de um ambiente de marketplace. A coleta foi efetuada na empresa Magamobi E-Business S/A.

Regras de Negócio RN-01 – O lojista deve enviar para o marketplace os anúncios que deseja vender. Esse anúncio passará por um processo de avaliação 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 avaliação do anúncio o lojista será notificado. RN-02 – Anúncios aprovados passam por um processo de associação/categorização. Nesse processo são validados os dados e verificado se já existe um anúncio semelhante do marketplace ou de outro lojista, caso exista, o anúncio é associado ao existente, se tornando um novo fornecedor daquele item. Caso não exista anúncio semelhante, o anúncio é categorizado conforme a estrutura interna do marketplace. RN-03 – Após o anuncio estar aprovado, é permitido ao lojista alterar (sem intervenção do marketplace) as informações de preço, estoque disponível e se o anuncio está ativo ou não no site. RN-04 – O valor do frete e a estimativa de entrega do anúncio são de responsabilidade do lojista. RN-05 – O lojista será notificado quando ocorrerem novos pedidos (venda do anúncio) ou quando for identificado o pagamento dos mesmos. Após confirmado o pagamento o lojista deverá iniciar-se o envio da mercadoria para o consumidor. RN-06 – O pedido, em seu fluxo padrão, passará pelas seguintes situações: Novo -> Aprovado (Pago) -> Em Transporte -> Entregue. RN-07 – O pedido pode vir a ser cancelado por ambas as partes nas situações iniciais. O marketplace pode fazer o cancelamento automático de um pedido novo, caso não seja identificado o pagamento correspondente ao mesmo após vencimento. Quando isso ocorrer o lojista será notificado. O lojista pode cancelar o pedido enquanto o mesmo ainda não 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 informações 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 serão feitos periodicamente, obedecendo o ciclo especificado no contrato entre as empresas. Exemplo: Pedidos do dia 01 a 15 são pagos no dia 20 do mesmo mês. Pedidos do dia 16 a 31 são pagos no dia 05 do mês subsequente. RN-11 – O marketplace recebe uma comissão, 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 comissão é descontado no montante do repasse correspondente. Podem haver negociações da taxa de comissão diferenciadas para períodos específicos, como por exemplo: dia das mães.

Page 23: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

RN-12 – O lojista deve repassar para o marketplace informações sobre a empresa, política de entrega e política de trocas e devoluções. O marketplace deve disponibilizar para o consumidor essas informações. RN-13 – Os atendimentos abertos por clientes referentes a anúncios e pedidos do lojista serão encaminhados para o mesmo responder.

Requisitos – Gerencial Marketplace

Descrição Regras RF-GER-01 – Permitir que o marketplace mantenha as informações cadastrais do lojista. São informações da manutenção do lojista:

• CNPJ • Razão social • Nome fantasia • Logo da empresa • Texto informativo sobre a empresa • Política de entrega • Política de trocas e devoluções • Contatos (nome, telefone e e-mail) para os setores comercial, financeiro e

tecnologia. • Ativo

RN-12

RF-GER-02 – Permitir que o marketplace gere as chaves de acesso do lojista para a API (para os ambientes de teste e produção).

RF-GER-03 – Permitir que o marketplace realize a avaliação dos anúncios enviados pelo lojista, e realize a aprovação ou recusa do mesmo.

RN-01 RN-02

RF-GER-04 – Permitir que o marketplace realize a associação e categorização dos anúncios aprovados do lojista.

RN-02

RF-GER-05 – Permitir que o marketplace mantenha os ciclos de pagamento para o lojista.

RN-10

RF-GER-06 – Permitir que o marketplace mantenha as taxas de comissão e suas respectivas condições de cobrança.

RN-11

RF-GER-07 – Permitir configurar uma URL de call-back do lojista, que será invoca para notifica-lo de alterações em anúncios e pedidos.

RN-01 RN-05

RF-GER-08 – Permitir configurar uma URL de call-back para cálculo do frete e prazo de entrega.

RN-04

RF-GER-09 – Permitir o encerramento do ciclo, apurando os valores a pagar para o lojista, descontando os valores das comissões.

RNF-GER-01 – Deve estar integrado com a plataforma de e-commerce utilizada pelo marketplace.

Requisitos – Site do Marketplace

Descrição Regras RF-SIT-01 – O marketplace deve possuir uma página informativa sobre o serviço e que possibilite o cadastro do lojista interessado em anunciar no marketplace.

RF-SIT-02 – Disponibilizar os anúncios aprovados e com estoque para venda no(s) RN-01

Page 24: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação 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 preço exibido é o do lojista com o menor valor.

RF-SIT-04 – Na página do produto, exibir as três ofertas de menor valor. RF-SIT-05 – Na página do produto, identificar qual o lojista que está ofertando o anúncio. Ex: Vendido e entregue por: Lojista XYZ. Adicionar um link no nome do lojista para a “página do lojista”.

RF-SIT-06 – No site do marketplace, deverá haver uma “página do lojista”. Nesse local será exibido todos os anúncios que o lojista tem ativos dentro do marketplace. Nessa página os clientes terão acesso as informações de descrição da empresa, política de entrega e política de troca e devoluções.

RN-12

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 anúncios. Para a visualização do cliente continua sendo um único pedido.

Requisitos – API

Descrição Regras RF-API-01 – Todo acesso a API deve ser autenticado utilizando os tokens disponibilizados ao lojista. A autenticação se dará utilizando o padrão Basic-Auth.

RF-API-02 – Consultas de listagem devem possuir limites de registros e uma forma de paginá-los em requisições diferentes. (GET /orders?_limit=X&_offset=Y)

RF-API-03 – Disponibilizar um serviço para o envio de anúncio (produto). (POST /item) As informações necessárias para o cadastro do anúncio são:

• Identificador (único e que servirá de referência para consultas e alterações do item em questão)

• Marca • Nome • Descrição (podendo conter formatação HTML) • Categoria • Lista de imagens (sendo obrigatório pelo menos 1 imagem) • Lista de vídeos [opcional] • EAN • Quantidade disponível para a venda • Preço (preço “de”) [opcional] • Preço de venda (preço “por”) • Dimensões (altura, largura, comprimento) [opcional] • Peso • Ativo

RN-01

RF-API-04 – Disponibilizar um serviço de consulta geral dos anúncios. (GET /items)

RF-API-05 – Disponibilizar um serviço de consulta de um anúncio específico. (GET /items/ID)

RF-API-06 – Disponibilizar um serviço de atualização de dados cadastrais do anúncio, acessível somente antes do anúncio ser “Aprovado”. (PUT /items/ID)

RN-01

Page 25: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

RF-API-07 – Disponibilizar um serviço de atualização de preço do anúncio. (PUT /items/ID/price)

RN-03

RF-API-08 – Disponibilizar um serviço de atualização de estoque do anúncio. (PUT /items/ID/stock)

RN-03

RF-API-09 – Disponibilizar um serviço de ativação/desativação do anúncio. (PUT /items/ID/status)

RN-03

RF-API-10 – Disponibilizar um serviço de consulta geral dos pedidos. (GET /order) Possibilitando os seguintes filtros opcionais:

• Data/hora inicial • Data/hora final • Situação • Identificador de Anúncio

RF-API-11 – Disponibilizar um serviço de consulta de um pedido específico. (GET /orders/ID) As informações do pedido são as seguintes:

• Identificador (único e que servirá de referência para consultas e alterações do item em questão)

• Número (número do pedido para o cliente) • Site do marketplace em que foi realizado a venda • Data/hora do pedido • Situação (Novo, Aprovado, Cancelado, Em Transporte, Entregue) • Dados do cliente (CPF/CNPJ, nome, telefones) • Itens comprados (Identificador do anúncio, valor unitário, quantidade) • Dados de Entrega (Forma de envio, valor do frete, nome destinatário, endereço,

número, bairro, complemento, CEP, cidade, estado) • Valor total do pedido • Data/hora da última atualização.

RF-API-12 – Disponibilizar um serviço de atualização do pedido para “Em Transporte”. (PUT /orders/ID/shipped) As informações necessárias para o registro do envio são:

• Nome da transportadora • Código de rastreamento na transportadora • Itens enviados (Identificador do anúncio, quantidade) • Data/hora • Dados da nota fiscal (Número, série, data de emissão, chave de acesso)

RN-08

RF-API-13 – Disponibilizar um serviço de atualização do pedido para “Entregue”. (PUT /orders/ID/delivered) As informações necessárias para o registro de entrega são:

• Itens entregues (Identificador do anúncio, quantidade) • Data/hora

RN-09

RF-API-14 – Disponibilizar um serviço de atualização do pedido para “Cancelado”. (PUT /orders/ID/cancel) As informações necessárias para o cancelamento são:

• Itens cancelados (Identificador do anúncio, quantidade) • Data/hora • Motivo do cancelamento

RN-07

Page 26: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

RF-API-15 – Disponibilizar um serviço de consulta geral dos protocolos de atendimento. (GET /tickets) Possibilitando os seguintes filtros opcionais:

• Data/hora inicial • Data/hora final • Situação

RF-API-16 – Disponibilizar um serviço de resposta a um protocolo de atendimento. (POST /tickets/ID/messages)

RF-API-17 – Disponibilizar serviço de consulta dos repasses financeiros para lojista. (GET /reports/transfers) Listagem contendo o resumo do ciclo:

• Identificador ciclo • Período • Data de pagamento • Total de créditos • Total de débitos

RN-10 RN-11

RF-API-17 – Disponibilizar serviço de detalhamento de um repasse financeiro para lojista. (GET /reports/transfers/ID) As informações são as seguintes:

• Data/hora • Tipo do movimento (Crédito ou Débito) • Pedido de referencia • Descrição • Valor do repasse

RN-10 RN-11

RF-API-18 – Disponibilizar serviço de consulta dos atendimentos. (GET /tickets) Possibilitando os seguintes filtros opcionais:

• Data/hora abertura inicial • Data/hora abertura final • Data/hora última atualização inicial • Data/hora última atualização final • Status

RF-API-19 – Disponibilizar serviço para adicionar uma mensagem (resposta) em um atendimento. (POST /tickets/ID/messages) As informações necessárias são:

• Mensagem • Nome do usuário

RF-API-20 - 19 – Disponibilizar serviço para encerrar um atendimento. (PUT /tickets/ID/finalize) Opcionalmente pode ser enviado uma mensagem.

RNF-API-01 – A API deve ser modelada utilizando os padrões de arquitetura REST (Representational State Transfer). Formato das representações (entrada e saída): JSON Charset: UTF-8 Content-Type: application/json

Page 27: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

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 – Códigos HTTP retornados pela API: Códigos de sucesso: 200 – Para método GET – Indica consulta processada com sucesso. 201 – Para método POST – Indica que o recurso foi criado com sucesso. 204 – Para método PUT – Indica que o recurso foi alterado com sucesso. Códigos de erro (retornados devido a erro por parte do lojista): 400 – Requisição mal formada. 401 – Requisição não autorizada. (Credenciais inválidas). 403 – Requisição negada. (Credenciais suspensas ou bloqueadas / acesso negado). 404 – Recurso não encontrado. 405 – Método não implementado. 422 – Exceções de negócio. 429 – Limite de requisições por minuto atingido. Códigos de erro (retornados devido a erro por parte do marketplace): 500 – Erro interno do servidor.

RNF-API-04 – Em casos de erro, as informações retornadas serão as seguintes: • Código de erro • Mensagem

RNF-API-05 – O marketplace deve disponibilizar toda documentação necessária da API, afim de orientar o desenvolvimento do lojista.

RNF-API-06 – A API deve possuir alta disponibilidade. Percentual desejado de 97% no mínimo.

Protótipos – Site do Marketplace

Protótipo de alta fidelidade – Página do produto – RF-SIT-05

Page 28: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

Protótipo de alta fidelidade – Página do lojista – RF-SIT-06

Page 29: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

APÊNDICE B – Detalhamento das classes e exemplos em JSON Este apêndice demonstra detalhadamente o significado de cada atributo das classes de

domínio utilizadas nos serviços da API. Também é apresentado um exemplo em formato JSON da representação da classe. Objetos comuns a todos os recursos da API Link - Link/referência para um recurso específico Propriedade Tipo Requerido Descrição

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 Propriedade Tipo Requerido Descrição

list array Sim Objetos dos registros. totalRows integer Sim Total de registros. offset integer Sim Posição inicial da consulta. Iniciado em 0. limit integer Sim Registros por consulta. Máximo 50. Exemplo: { "list": [], "totalRows": 0, "offset": 0, "limit": 50 } Error - Resposta de erro Propriedade Tipo Requerido Descrição

code integer Não Código. message string Sim Mensagem. httpCode integer Sim Código HTTP. Exemplo: { "code": 400, "message": "Propriedade \"title\" vazia ou nao encontrada no objeto Item", "httpCode": 400 } Objetos da API Lojista Notification - Notificação Propriedade Tipo Requerido Descrição

eventDate string Sim Data/hora. Formato: YYYY-MM-DDThh:mm:ss.TZD. resource Link Sim Recurso. resourceStatus string Não Status do recurso. Exemplo: { "eventDate": "2015-05-06T13:40:55-03:00", "resource": { "id": 3330,

Page 30: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

"rel": "item", "href": "\/items\/3330" }, "resourceStatus": "approved" } FreightPreviewItem - Item para o cálculo de frete Propriedade Tipo Requerido Descrição

item Link Sim Link do anúncio. quantity integer Sim Quantidade. FreightPreview - Cálculo de frete Propriedade Tipo Requerido Descrição

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 - Opção de envio do anúncio Propriedade Tipo Requerido Descrição

id string Sim Identificador. name string Sim Nome. price double Sim Valor. estimatedDeliveryDate string Sim Data estimada de entrega. FreightPreviewItemResponse - Item da resposta do cálculo de frete Propriedade Tipo Requerido Descrição

itemId integer Sim Identificador do anúncio. quantity integer Sim Quantidade. FreightPreviewResponse - Resposta do cálculo de frete Propriedade Tipo Requerido Descrição

zipcode integer Sim CEP. items array[FreightPreviewItemResponse] Sim Lista dos itens. shippingServices array[ShippingService] Sim Opções de envio. Exemplo: { "zipcode": 89186000, "items": [ { "itemId": 3330, "quantity": 1 } ], "shippingServices": [ { "id": "PAC", "name": "Correios - PAC", "price": 15, "estimatedDeliveryDate": "2015-05-28" }, {

Page 31: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

"id": "Sedex", "name": "Correios - Sedex", "price": 23.5, "estimatedDeliveryDate": "2015-05-22" } ] }

Objetos recurso /items (anúncios) Price - Preço do anúncio Propriedade Tipo Requerido Descrição

default double Sim Preço "de". sale double Sim Preço "por". Preço real de venda. Dimension - Dimensões do anúncio Propriedade Tipo Requerido Descrição

length double Não Comprimento (cm). width double Não Largura (cm). height double Não Altura (cm). Item - Anúncio Propriedade Tipo Requerido Descrição

id integer Sim Identificador (único e que servirá de referência para consultas e alterações do item em questão).

brand string Sim Marca. title string Sim Título. description string Sim Descrição detalhada. Pode conter tags de

formatação HTML. category string Sim Categoria. images array[string] Sim Lista de URLs das imagens. É obrigatório pelo

menos uma. videos array[string] Não Lista de URLs de vídeos. ean string Não EAN. availableQuantity integer Sim Quantidade disponível para venda. price Price Sim Preço. dimensions Dimensions Não Dimensões. 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",

Page 32: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação 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 - Anúncio Propriedade Tipo Requerido Descrição

id integer Sim Identificador (único e que servirá de referência para consultas e alterações do item em questão).

brand string Sim Marca. title string Sim Título. description string Sim Descrição detalhada. Pode conter tags de formatação

HTML. category string Sim Categoria. images array[string] Sim Lista de URLs das imagens. É obrigatório pelo menos

uma. videos array[string] Não Lista de URLs de vídeos. ean string Não EAN. availableQuantity integer Sim Quantidade disponível para venda. price Price Sim Preço. dimensions Dimensions Não Dimensões. weight double Sim Peso (gramas). active boolean Sim Ativo. status string Sim Status. (pending, approved, rejected, selling). statusDescription string Não Observação sobre o status. Stock - Estoque Propriedade Tipo Requerido Descrição

availableQuantity integer Sim Quantidade disponível para venda. Active - Ativo Propriedade Tipo Requerido Descrição

active boolean Sim Ativo. Objetos recurso /orders (pedidos) Telephone - Telefone de contato Propriedade Tipo Requerido Descrição

number string Sim Número. type string Sim Tipo. (home, cellphone, business). Client - Dados do cliente Propriedade Tipo Requerido Descrição

documentNumber string Sim CPF/CNPJ. name string Sim Nome. phones array[Telephone] Sim Telefones de contato.

Page 33: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

ShippingAddress - Endereço de entrega Propriedade Tipo Requerido Descrição

addressType string Sim Tipo. (commercial, residential). receiverName string Não Responsável. receiverPhone string Não Fone responsável. street string Sim Endereço. number string Não Número. additionalInfo string Não Complemento. neighborhood string Sim Bairro. city string Sim Cidade. zipcode integer Sim CEP. reference string Não Ponto de referência. state string Sim Estado (sigla). country string Sim País (sigla). OrderItem - Item do pedido Propriedade Tipo Requerido Descrição

item Link Sim Anúncio. quantity integer Sim Quantidade. price double Sim Preço unitário. Order - Pedido Propriedade Tipo Requerido Descrição

id integer Sim Identificador. siteId string Sim Número do pedido para o cliente. store string Sim Loja do marketplace. dateCreated string Sim Data/hora de criação. 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 Endereço de entrega. estimatedDeliveryDate string Sim Data estimada de entrega. shippingService string Sim Identificador da opção de envio. freight double Sim Valor de frete. totalAmount double Sim Valor total. lastUpdate string Sim Data/hora última atualização.

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": [

Page 34: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação 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 Descrição

documentNumber string Sim CNPJ. name string Sim Nome. Invoice - Nota Fiscal Propriedade Tipo Requerido Descrição

number string Sim Número. line string Sim Série. issueDate string Sim Data/hora de emissão. Formato: YYYY-MM-DDThh:mm:ss.TZD. accessKey string Sim Chave de acesso. TrackingItem - Item do tracking Propriedade Tipo Requerido Descrição

itemId integer Sim Identificador do anúncio. quantity integer Sim Quantidade. Shipping - Tracking de envio para a transportadora Propriedade Tipo Requerido Descrição

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 Código 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",

Page 35: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação 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" } } Delivery - Tracking de entrega para o cliente Propriedade Tipo Requerido Descrição

items array[TrackingItem] Sim Lista dos itens. 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 Propriedade Tipo Requerido Descrição

items array[TrackingItem] Sim Lista dos itens. 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 Propriedade Tipo Requerido Descrição

id int Sim Identificador. dateCreated string Sim Data/hora. Formato: YYYY-MM-DDThh:mm:ss.TZD. userName string Sim Usuário. message string Sim Mensagem. Ticket - Protocolo de atendimento Propriedade Tipo Requerido Descrição

id int Sim Identificador. dateCreated string Sim Data/hora de abertura. Formato: YYYY-MM-

DDThh:mm:ss.TZD. type string Sim Tipo. (Dúvidas, Vendas, Reclamações, Trocas). subject string Sim Assunto. status string Sim Status. client Client Sim Cliente.

Page 36: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

order Link Não Pedido. store string Sim Loja do marketplace. messages array Sim Mensagens. lastUpdate string Sim Data/hora última atualização. 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 (relatórios) Transaction - Movimentação financeira Propriedade Tipo Requerido Descrição

date string Sim Data. type string Sim Tipo da operação. (credit, debit). order Link Não 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 Propriedade Tipo Requerido Descrição

id int Sim Identificador. startDate string Sim Data de início do ciclo. finishDate string Sim Data de final do ciclo. paymentDate string Sim Data de pagamento.

Page 37: PROJETANDO UMA API DE SERVIÇOS PARA … · A resposta HTTP também é um documento em um envelope. A resposta pode ser dividida em três partes: • Código da resposta HTTP: este

Universidade do Estado de Santa Catarina Centro de Educação Superior do Alto Vale do Itajaí

creditAmount double Sim Valor total de crédito. debitAmount double Sim Valor total de débito. 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 }