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".
Menus
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.
- valid_to: "store" ou "cart", obrigatório
- name: nome que identifique a promoção, obrigatório
- start_at: data de início, obrigatório, ex 2017-03-26 18:15
- end_at: data de encerramento, opcional, ex 2017-03-27 18:15
- description: texto descrevendo a promoção promoção, opcional
- enabled: 0 ou 1, opcional, padrão 1
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.
- apply_to: (product, tag, subtotal, total, shipping, gift), obrigatório
- amount_type: (%, R$), obrigatório
- amount: valor do desconto em decimal com 2 dígitos de precisão, obrigatório
- product_id: código do produto, opcional
- tag_id: código da tag, opcional
- min_quantity: quantidade minima de itens, opcional
- shipping_method, forma de entrega, opcional
- min_subtotal: valor mínimo de subtotal, opcional
- gift: (1-per-crt, cheaper, more-expensive), opcional
- combinated_product_id, código do produto combinado, opcional
- client_tag, código do cliente, opcional
- regions: regiões para aplicação do frete, opcional
- gift_quantity: quantidade de brindes, opcional
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