Apresentação

Através da API, você pode acessar os dados e realizar operações da sua loja. Esse guia mostrará quais recursos estão disponpiveis e como utilizá-los.

Como Começar

01 curl -X GET
02   -H "Accept: application/json"
03   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
04   'https://demo.vnda.com.br/api/...'
      

Cada URL dará acesso a determinado recurso, mas tem como base a URL da loja.

Todas as respostas da API seguem o formato JSON.

A comunicação com a API precisa ser autenticada usado HTTP Basic.

Você pode obter o usuário e senha da sua loja pelo painel administrativo. Estes são exclusivos para acessar a API, e não são os mesmos usados para logar no painel administrativo.

As informações usadas nos exemplos são fictícias.

Pedidos

05 curl -X GET
06   -H "Accept: application/json"
07   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
08   'http://demo.vnda.com.br/api/v2/orders'

09 curl -X GET
10   -H "Accept: application/json"
11   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
12   'http://demo.vnda.com.br/api/v2/orders?status=confirmed,canceled&client_id=1'

13 curl -X GET
14   -H "Accept: application/json"
15   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
16   'http://demo.vnda.com.br/api/v2/orders/CBE2F7E7A1'

13 curl -X GET
14   -H "Accept: application/json"
15   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
16   'http://demo.vnda.com.br/api/v2/orders/CBE2F7E7A1/items'

Os pedidos podem ser listados e filtrados por Status e Cliente.

Os status aceitos para filtro são "received", "confirmed", "canceled". Também são aceitas combinações destes status, desde que separados por vídgula. Ex: "confirmed,canceled"

Para filtrar os pedidos por cliente, deve ser fornecido o código do cliente, que consiste de um número inteiro.

Podem ser usados os parâmetros "page" e "per_page" para controlar a paginação da listagem

Informando o código alfanumerico o pedido, serão retornados os dados somente deste.

Clientes


17 curl -X GET
18   -H "Accept: application/json"
19   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
20   'http://demo.vnda.com.br/api/clients'

21 curl -X GET
22   -H "Accept: application/json"
23   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
24   'http://demo.vnda.com.br/api/client?id=1'

25 curl -X POST
26   -H "Accept: application/json"
27   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
28   'http://demo.vnda.com.br/api/client?email=fulano@empresa.com.br'

A listagem de clientes é limitada aos 30 recém atualizados.

Também é possível buscar um cliente pelo seu ID.

É possível solicitar uma nova senha para um cliente, informando seu email. Esta senha será enviada para o email do cliente.

Estoque

29 curl -X GET
30   -H "Accept: application/json"
31   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
32   'http://demo.vnda.com.br/api/v2/variants/AB123/quantity'

33 curl -X POST
34   -H "Accept: application/json"
35   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
36   'http://demo.vnda.com.br/api/v2/variants/AB123/quantity?quantity=33'

33 curl -X POST
34   -H "Accept: application/json"
35   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
36   'http://demo.vnda.com.br/api/v2/variants/AB123/sold/33'

              

O estoque é ajustado automaticamente, de acordo com as vendas e cancelamentos de pedidos realizados. Entretando, é possível consultar e modificar estas informações pela API.

Para consultar o estoque, deve ser informado o SKU desejado. No exemplo, usamos o SKU AB123.

A quantidade de itens em estoque pode ser ajustada, envinado um valor no parâmetro "quantity". Neste exemplo, o estoque será modificado para 33 unidades, independentemente do estoque atual aual.

Essa quantidade também pode diminuida de forma relativa. Ou seja, o valor informado será diminuído do estoque atual. Neste exemplo, o estoque passará de 99 para 66, pois estamos solicitando a redução de 33 unidades. Se não existir estoque disponível para a quantidade solicitada, será retornado erro.

Produtos

37 curl -X GET
38   -H "Accept: application/json"
39   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
40   'http://demo.vnda.com.br/api/v2/products/?page=2&per_page=20'


41 curl -X GET
42   -H "Accept: application/json"
43   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
44   'http://demo.vnda.com.br/api/v2/products/?tag=nome-de-uma-tag-existente'

41 curl -X GET
42   -H "Accept: application/json"
43   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
44   'http://demo.vnda.com.br/api/v2/products/?tag=carro&parent_tag=automovel'

45 curl -X GET
46   -H "Accept: application/json"
47   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
48   'http://demo.vnda.com.br/api/v2/products/?filter[size]=GG'

49 curl -X GET
50   -H "Accept: application/json"
51   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
52   'http://demo.vnda.com.br/api/v2/products/?filter[price]=120-200&sort=newest'


53 curl -X GET
54   -H "Accept: application/json"
55   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
56   'http://demo.vnda.com.br/api/v2/products/?limit=10&sort=price,desc'


57 curl -X GET
58   -H "Accept: application/json"
59   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
60   'http://demo.vnda.com.br/api/v2/products/506'

57 curl -X GET
58   -H "Accept: application/json"
59   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
60   'http://demo.vnda.com.br/api/v2/products/attributes?name=Cor&tag=oculos'

              

Para a listagem de produtos, são aceitos os parâmetros "limit", "page", "per_page", "tag", "parent_tag", "filter" e "sort". Podendo serem combinados.

Caso o parametro "limit" seja informado, os parametros "page" e "per_page" serão desconsiderados.

Os produtos podem ser filtrados por tag, tamanho ou preço.

Informando algo no parâmetro "tag", serão listados somente os produtos com essa tag. Junto com o parâmetro "tag", pode ser usado o parâmetro "parent_tag".

Para filtrar produtos por tamanho, basta informar o tamanho desejado no parâmetro "filter[size]".

Para filtrar por preço, informe um intervalo de valores no parâmetro "filter[price]", separando os valores minímo e máximo com um traço. Ex: "120-200 para mostrar os produtos com preço entre 120,00 e 200,00.

Por padrão, os produtos são ordenados de forma que os atualizados mais recentemente sejam exibidos primeiro. Caso o parâmetro "tag" esteja presente, os produtos serão ordenados pela importância dentro de cada tag.

É possível reordenar os produtos por preco, informando "price" no parâmetro "sort". Também é possível usar o valor "newest" para ordenar pela data de cadastro. Para inverter qualquer destas ordenações, é possível usar "price,desc" ou "newest,desc".

Para listar algum produto em expecífico, colocar o ID do produto na url. Neste caso, os demais parâmetros não se aplicam.

Quando se está criando um filtro, pode ser necessário listar todos os Tamanhos ou Cores disponíveis. Para essa finalidade, dispomos de uma lista de atributos, para a qual deve ser informado o parâmetro "name". Caso necessário, é possível listar os atributos somente dos produtos que tem determinada Tag, informando os parâmetros "tag" e "parent_tag".

57 curl -X GET
58   -H "Accept: application/json"
59   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
60   'http://demo.vnda.com.br/api/v2/menus'

57 curl -X GET
58   -H "Accept: application/json"
59   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
60   'http://demo.vnda.com.br/api/v2/menus?position=principal'

61 curl -X GET
62   -H "Accept: application/json"
63   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
64   'http://demo.vnda.com.br/api/v2/menus?parent_id=5'

              

Sem informar qualquer parâmetro, serão retornados todos os itens de 1º nível existentes, independente da posição.

Informando o parâmetro "position", serão retornados os itens que estão no 1º nível da posição de menu.

Cada item de menu tem uma propriedade "items_count". Ela mostra quandos filhos o item possui. Se o valor é maior do que zero, indica que o item tem submenu.

Para receber os itens deste submenu, deve-se fazer uma nova busca, informando o ID deste item.

Banners

61 curl -X GET
62   -H "Accept: application/json"
63   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
64   'http://demo.vnda.com.br/api/v2/banners?limit=3

65 curl -X GET
66   -H "Accept: application/json"
67   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
68   'http://demo.vnda.com.br/api/v2/banners?position=destaque-esquerda'

Lista os banners cadastrados. Sendo possível filtar os resultados informando o patâmetro "position".

Também aceita o parâmetro "limit", para determinar o número máximo de resultados ddesejados.

Cada banner possui a propriedade "external", que indica se o link deve abrir em uma nova janela do navegador.

Páginas

69 curl -X GET
70   -H "Accept: application/json"
71   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
72   'http://demo.vnda.com.br/api/v2/pages/nossa-loja
            

Páginas são trechos de html que podem ser cadastrados pelo painel administrativo da loja, e resgatados pela url.

Tags

73 curl -X GET
74   -H "Accept: application/json"
75   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
76   'http://demo.vnda.com.br/api/v2/tags

77 curl -X GET
78   -H "Accept: application/json"
79   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
80   'http://demo.vnda.com.br/api/v2/tags?type=marca

81 curl -X GET
82   -H "Accept: application/json"
83   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
84   'http://demo.vnda.com.br/api/v2/tags/nome-de-uma-tag-qualquer

As tags podem ser listadas sem parâmetros, ou usando os fltros "type" e "product_id".

Os parâmetros "type" e "product_id" podem ser usados indivitualmente ou juntos.

Para restringir a quantidade de registros retornados, pode ser usado o parâmetro "limit" ou os parâmetros "page" e "per_page".

Para retornar uma tag expecífica, deve ser informado o nome da mesma na url.

Variantes

85 curl -X GET
86   -H "Accept: application/json"
87   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
88   'http://demo.vnda.com.br/api/v2/products/657/variants

89 curl -X GET
90   -H "Accept: application/json"
91   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
92   'http://demo.vnda.com.br/api/v2/variants/A1S2D3

89 curl -X PUT
90   -H "Accept: application/json"
91   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
92   'http://demo.vnda.com.br/api/product?id=123&variant_id=22&price=159.23
            

Lista as variantes de um produto.




Para ver uma variante em expecífico, basca colocar o sku na url.




Também é possível ajustar o preço de uma variante. Será necessário informar o ID do produto, o ID da variante e o NOVO PREÇO.

Imagens

93 curl -X GET
94   -H "Accept: application/json"
95   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
96   'http://demo.vnda.com.br/api/v2/products/657/images

97 curl -X GET
98   -H "Accept: application/json"
99   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
100   'http://demo.vnda.com.br/api/v2/products/657/variants/A1S2D3/images
            

É possível listar as imagens por produto ou por variante.

Quando listanto imagens por produto, serão exibidas todas as imagens do produto.

Quando listanto imagens por variante, só serão exibidas as imagens que são associadas com a variante em questão.

Se nenhuma variante for associada a imagen, significa que a mesma é comum a todas as variantes. Neste caso, a imagem só aparecerá quando listada por produto.

A ordem da listagem é definida pelo painel administrativo da loja.

Vídeos

93 curl -X GET
94   -H "Accept: application/json"
95   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
96   'http://demo.vnda.com.br/api/v2/products/657/videos
            

Os vídeos podem ser listados por produto.









Promoções

Existem promoções válidas para toda a loja (store) ou para cada carrinho (cart). Dependendo do tipo de promoção, estarão disponíveis diferentes regras de descontos.

As promoções podem valer em um deretminado período de datas ou a partir de uma data e sem prazo de encerramento.

curl -X POST
  -H "Accept: application/json"
  -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
  'http://demo.vnda.com.br/api/v2/discounts

Response 201 Created
{"id":15,"name":"nome do desconto","description":null,"facebook":false,"valid_to":"cart","seal_uid":null,"seal_url":null,"start_at":"2016-01-01T00:00:00.000-02:00","end_at":null,"rules":[]}
              

Adicionar e Atualizar uma promoção.


curl -X PUT
  -H "Accept: application/json"
  -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
  'http://demo.vnda.com.br/api/v2/discounts/15

Response 204 No content
            

Regras de desconto

curl -X POST
  -H "Accept: application/json"
  -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
  'http://demo.vnda.com.br/api/v2/discounts/15/rules

Response 201 Created

{"id":16,"amount":50.0,"type":null,"apply_to":"subtotal","min_quantity":1}


curl -X PUT
  -H "Accept: application/json"
  -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
  'http://demo.vnda.com.br/api/v2/discounts/15/rules/1

Response 204 No content


curl -X DELETE
  -H "Accept: application/json"
  -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
  'http://demo.vnda.com.br/api/v2/discounts/15/rules

Response 204 No content
              

Estas regras adicionam descontos a cada promoção. A combinação adequada dos atributos abaixo produz diferentes tipos de descontos.

Cupons

Cupons de desconto tem a finalidade de limitar a aplicação de promoções.

Para manipular cupons de desconto, é necessário possuir o ID de uma promoção já cadastrada

97 curl -X GET
98   -H "Accept: application/json"
99   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
100   'http://demo.vnda.com.br/api/v2/discounts/22/coupons

Response: 200 OK
[{"id":4,"discount_id":22,"code":"DESCONTO50","uses_per_code":0,"created_at":"2015-08-19T11:51:31.013-03:00","updated_at":"2015-08-19T11:51:31.013-03:00","uses_per_user":0}]

Listar cupons de uma promoção










101 curl -X POST
102   -H "Accept: application/json"
103   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
104   'http://demo.vnda.com.br/api/v2/discounts/22/coupons?code=XYZ&uses_per_code=1

Response: 201 Created
{"id":5,"discount_id":22,"code":"XYZ","uses_per_code":1,"created_at":"2017-06-06T10:08:54.619-03:00","updated_at":"2017-06-06T10:08:54.619-03:00","uses_per_user":0}

Adicionar cupons a uma promoção

O parâmetro "code" é obrigatório e será o texto que o cliente deve informar no checkout para ativar a promoção.

O parâmetro "uses_per_code" indica quantas de vezes que o cupom pode ser utilizado (opcional, padrão 0, significa uso ilimitado).




105 curl -X DELETE
106   -H "Accept: application/json"
107   -u 1393b0e9db3d83f2f0ba8de4cbfb97ed:1afc729e7125e4283a57a85057e9526b
108   'http://demo.vnda.com.br/api/v2/discounts/22/coupons/32

Apagar cupons

Para pagar um cupom, é necessário saber o ID do mesmo

Em caso de sucesso, será retornado HTTP 204

Caso o cupom esteja em uso, será retornado HTTP 422

Caso o cupom não exista, será retornado HTTP 404