Paginação

Durante a exibição do resultado de alguns métodos da API é necessário o uso de parâmetros de paginação. Para paginar resultados é necessário utilizar dois parâmetros na própria Query String _offset e _limit, conforme exemplos abaixo: http://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.

Observação: o índice das listagens inicia em 0 (zero). Ou seja para uma consulta com os 10 primeiros itens de uma lista (_offset=0 e _limit=10), os índices serão de zero (0) a nove (9).

OBSERVAÇÃO IMPORTANTE:
Para 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 uma 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

Para 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ê pode buscar apenas as informações que são mais relevantes para sua solução. Segue um exemplo de como utilizar esse recurso: http://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, sendo que cada item da lista conterá apenas os atributos solicitados, conforme abaixo:

[
    {
       "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 sua aplicação a fazer a paginação dos resultados obtidos. Essas informações são retornadas em todas as consultas de listagens. Abaixo, segue nome e formato do objeto:

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

Optamos por esse formato devido à possibilidade de incluirmos mais informações úteis da consulta no futuro sem quebrarmos a assinatura, pois trata-se de um mapa com chave/valor. Segue um exemplo de 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" }
    ]
}

Importante: *Os endpoints abaixo sempre retornarão apenas 50 itens por página, mesmo que sua paginação exceda uma quantidade superior deste limite.

  • 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
Português, Brasil