Tecnologias e Padrões

Parte superior do formulário

É a Arquitetura para a disponibilização de recursos através de sistemas distribuídos, popularmente utilizado sobre o protocolo HTTP. Veja mais detalhes acessando o link

É o 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. Conheça mais detalhes, acessando aqui

É o Protocolo de transferência de hipertexto seguro, amplamente utilizado. Veja mais detalhes acessando o link

Conjunto de caracteres padrão para comunicação entre sistemas distribuídos. Para mais informações, acesse aqui

:ISO-8601

Padrão de formato específico para dados do tipo date e hora.

Padrão: YYYY-MM-DDThh:mm:ss.sTZD

Exemplo: 2013-06-28T08:54:00.000-03:00

Consulta com paginação

Parte superior do formulário

• Paginação

Em alguns métodos da API durante a exibição do resultado, é necessário o uso de parâmetros de paginação. Para paginar esses resultados é necessário a utilização de dois parâmetros na própria Query String _offset e _limit

Veja os exemplos:

 https://api-mktplace.viavarejo.com.br/api/v2/orders/status/new?_offset=0&_limit=50

Como resultado deverá retornar uma lista contendo 50 objetos, a partir, do primeiro objeto da lista.

_offset: Indica a posição inicial da consulta, ou seja, 50 indica o primeiro registro trazido deve estar na posição 50.

_limit: Indica a quantidade de registros que deve ser trazido na consulta.

Para que você tenha uma boa performance na integração, recomendamos que a quantidade de registro solicitados (parâmetro _limit) não ultrapasse 50 nas consultas de produtos (GET /sellerItems, GET /sellerItems/status/selling e GET /products), e 50 nas consultas de pedidos (todas as consultas de pedidos por status, GET /orders/status/new, por exemplo).

Caso seja passado um valor maior que a recomendação, os serviços irão sobrescrever o valor requisitado com o valor limite para cada tipo de consulta.

• Seleção de atributos

Com o intuito de melhorar sua experiência com o uso da API, agora é possível selecionar os atributos que deverão ser retornados nas consultas (Métodos GET). Dessa forma, é possível reduzir a quantidade de informações trafegadas nos serviços e você poderá buscar apenas as informações que são mais relevantes para sua solução.

Veja o exemplo de utilização, deste novo recurso:

https://api-mktplace.viavarejo.com.br/api/v2/orders/status/approved?_offset=0&_limit=50&attributes=id,purchasedAt,approvedAt,totalAmount 

Esse conteúdo retornará uma lista de pedidos, e cada item da lista deve conter apenas os atributos solicitados:

[
    {
       "id" : "123321009",
       "purchasedAt" : "2014-08-01T08:54:00.000-03:00",
       "approvedAt" : "2014-08-01T08:59:10.000-03:00",
       "totalAmount" : "115.00"
    },
    {...}
]

• Metadados de consultas

Os metadados de consultas são informações disponibilizadas para auxiliar a aplicação para fazer a paginação dos resultados obtidos. Essas informações são retornadas em todas as consultas de listagens.

Veja o nome e o formato do objeto

"metadata": [
  { "key": "", "value": "" },
]

Nós escolhemos este formato devido já que ele possibilita incluirmos mais informações úteis da consulta no futuro sem quebrarmos a assinatura, pois trata-se de um mapa com chave/valor.

Veja como esses metadados serão retornados:

Serviço: GET /orders/status/sent?_offset=0&_limit=50

{
  "orders": [
      {..}, {..}, ... {..}
  ],
  "metadata": [
      { "key": "totalRows", "value": "259" },
      { "key": "offset", "value": "0" },
      { "key": "limit", "value": "50" },
      { "key": "first", "value": "/orders/status/sent?_offset=0&_limit=50" },
      { "key": "previous", "value": "" },
      { "key": "next", "value": "/orders/status/sent?_offset=100&_limit=50" },
      { "key": "last", "value": "/orders/status/sent?_offset=150&_limit=50" }
  ]
  }

• GET /api/v2/orders/status/approved

• GET /api/v2/orders/status/canceled

• GET /api/v2/orders/status/delivered

• GET /api/v2/orders/status/new

• GET /api/v2/orders/status/partiallyDelivered

• GET /api/v2/orders/status/partiallySent

• GET /api/v2/orders/status/sent

Lista de Códigos de Sucesso

Os códigos HTTPs para indicar retornos de sucesso comuns na API são:

Lista de Códigos de Erro

"errors": [
      {
          "code": "401.001",
          "type": "SecurityException",
          "message": "Você não tem permissão para acessar o recurso desejado",
          "skuSellerId": "" -- campo opcional
      }
  ]
}

Veja como os erros citados acima serão retornados:comuns, A API utiliza os seguintes códigos HTTPs comuns: | Cell | Cell | Cell |