Este contenido solo está disponible en portugués.
Modelagem
Padrões e tecnologias
A API de integração com o marketplace do Grupo Netshoes utiliza os conceitos de arquitetura Restful. Sendo que, para isso os seguintes padrões e tecnologias são empregados na solução.
REST
Arquitetura para a disponibilização de recursos através de sistemas distribuídos, popularmente utilizado sobre o protocolo HTTP.
HTTP 1.1
Padrão para descrição de dados utilizado para intercâmbio de informações entre sistemas, é mais simples e leve do que algumas alternativas de mercado, como XML.
JSON
Protocolo de transporte padrão, amplamente utilizado.
UTF-8
Conjunto de caracteres padrão para comunicação entre sistemas distribuídos.
ISO-8601
Padrão de formato específico para dados do tipo data e hora.
Recursos e Operações
Os recursos definidos na API do marketplace seguem o padrão Restful e, utilizam as operações padrões do protocolo HTTP para processamento das chamadas.
A tabela abaixo define a ação esperada para cada um dos métodos utilizados pela API.
| Método HTTP | Ações |
|---|---|
| GET | Consulta de um ou mais recursos do marketplace. Essa operação permite que um ou mais recursos seja pesquisado de acordo com os filtros informados na URI do recurso. Saiba mais no tópico Buscas e Paginação, ou veja as operações de consulta disponíveis no API Browser. |
| POST | Cria um novo recurso. Essa operação recebe a estrutura JSON do recurso que deverá ser criado e retorna ao consumidor a mesma estrutura já processada pelo marketplace. Assim o consumidor pode utilizar a estrutura de links (veja mais em HATEOAS) disponibilizada, para poder realizar outras operações no recurso criado. |
| PUT | Atualiza um recurso existente. Essa operação recebe a estrutura JSON do recurso que deverá ser alterado e retorna a mesma estrutura já processada pelo marketplace, juntamente com os links relacionados ao recurso. |
Buscas e Paginação
Existem duas formas de realizar a busca de dados na API do marketplace.
Busca de Coleções
A busca por coleções deverá ser utilizada em conjunto com os parâmetros de paginação. Em geral todos os serviços que retornam grande quantidade de dados sempre utilizam paginação para devolver os registros.
GET http://api-sandbox.netshoes.com.br/api/v2/products?page=0&size=20
Busca Específica
A busca de um recurso específico deverá ser realizada quando o lojista já tiver o conhecimento da existência do recurso que deve ser pesquisado.
A idetificação do recurso deverá ser informada na composição da URI de consulta, como no exemplo abaixo:
GET http://api-sandbox.netshoes.com.br/api/v2/products/12479
Parâmetro Expand
Sempre que houver a necessidade do retorno de maiores detalhes sobre algum dos atributos do recurso desejado, o parâmetro expand poderá ser utilizado.
Recomenda-se a utilização do size no máximo 50 (size=50) caso contrário, poderá ocorrer time-out ao utilizar o método GET.
GET http://api-sandbox.netshoes.com.br/api/v2/products?page=0&size=20&expand=attributes
GET http://api-sandbox.netshoes.com.br/api/v2/products/12479?expand=attributes
Hypermedia (HATEOAS)
HATEOAS (Hypermedia as the Engine of Application State) possibilita que as aplicações consumidoras possam interagir com a API do marketplace basicamente através de informações de hypermedia retornadas em cada recurso.
Em arquiteturas orientadas a serviços (SOA), as regras de comunicação entre cliente e servidor são estabelecidas através de uma interface definida entre as partes, normalmente WSDL. A utilização de HATEOAS permite que a disponibilização de novas interações ocorra de forma dinâmica e que as aplicações consumidoras tomem conhecimento das novas opções de interação sem que sejam impactadas.
Estrutura de Hypermedia
Todos os recursos da API deverão conter a seguinte estrutura de links, indicando as possibilidades de interação com o recurso em questão:
Códigos de Sucesso
A API retornará os códigos HTTP Status para cada request.
| Código HTTP | Descrição | Métodos HTTP |
|---|---|---|
| 200 | Indica que o processamento foi realizado corretamente e o retorno será conforme a expectativa. | GET |
| 201 | Indica que o recurso foi criado com sucesso. Deverá retornar o header Location: indicando a URI do novo recurso. | POST |
| 202 | Indica que o processamento será assíncrono, portanto, além do header Location, deverá retornar o conteúdo com um atributo status. | POST PUT |
| 204 | Indica que a solicitação foi processada, mas a busca nenhum registro pode ser encontrado. | GET |
| 206 | Indica que os dados foram processados parcialmente e os problemas dos itens não processados serão informados na resposta do servidor. | POST |
Códigos de Erro do Cliente
| Código HTTP | Descrição |
|---|---|
| 400 | Requisição mal formada. |
| 401 | Requisição requer autenticação. Acontece quando não é enviado o TOKEN na requisição, ou quando ele está inválido. |
| 403 | Requisição negada. |
| 404 | Recurso não encontrado. |
| 405 | Método não permitido. |
| 406 | Conteúdo ou Content-type inválido. |
| 408 | Tempo esgotado para a requisição. |
| 409 | Recurso já cadastrado. |
| 413 | Requisição excede o tamanho máximo permitido. |
| 415 | Tipo de mídia inválida (falta de informar o Content-Type correto). |
| 422 | Exceções de negócio. |
| 429 | Requisição excede a quantidade máxima de chamadas permitidas à API. |
Códigos de Erro do Servidor
| Código HTTP | Descrição |
|---|---|
| 5xx | Erro interno inesperado do servidor. |
Estrutura de Erro
Em caso de erros, a resposta ao recurso deverá retornar uma estrutura específica, como definido abaixo:
{
"type":"Bad_Request_Error",
"description":"Request invalid or malformed.",
"notifications":[
"Error on save sku:111-0457-178-52 Produto com código '111-0457-178-52' já existe para o Fornecedor '08912997000168' com SKU Netshoes '105-0003-XPB-17'",
"Error on save sku:111-0457-178-85 Produto com código '111-0457-178-85' já existe para o Fornecedor '08912997000168' com SKU Netshoes '105-0003-XPB-07'",
"Error on save sku:111-0457-178-23 Produto com código '111-0457-178-23' já existe para o Fornecedor '08912997000168' com SKU Netshoes '105-0003-XPB-06'"
]
}{
"type":"Bad_Request_Error",
"description":"Request invalid or malformed.",
"notifications":[
"Error on save sku:111-0457-178-52 Produto com código '111-0457-178-52' já existe para o Fornecedor '08912997000168' com SKU Netshoes '105-0003-XPB-17'",
"Error on save sku:111-0457-178-85 Produto com código '111-0457-178-85' já existe para o Fornecedor '08912997000168' com SKU Netshoes '105-0003-XPB-07'",
"Error on save sku:111-0457-178-23 Produto com código '111-0457-178-23' já existe para o Fornecedor '08912997000168' com SKU Netshoes '105-0003-XPB-06'"
]
}