Como utilizar a API da Vendizap
O que é uma API?
Uma API (Interface de Programação de Aplicações) é uma "ponte" que permite que dois sistemas conversem automaticamente
entre si, sem ninguém precisar digitar nada.
No caso da Vendizap, a API permite que o seu sistema de gestão (ERP) ou um programa feito sob medida se conecte à sua
loja para, por exemplo, cadastrar produtos automaticamente ou puxar os pedidos para dentro do seu sistema, tudo sem
abrir o painel e fazer manualmente.
Você não precisa entender de API para usar a Vendizap. Este recurso é voltado para quem já, pretende usar um sistema ou
contrata um desenvolvedor/ERP para fazer essa ponte.
A documentação técnica completa (com todos os campos de cada endpoint) está disponível em https://api-docs.vendizap.com/
Para quem está disponível?
O acesso à API está disponível nos planos Profissional e Empresarial. O plano Essencial não tem acesso a este recurso.
Passo 1: Gere suas credenciais
Acesse sua conta Vendizap e vá até: Configurar > Integrações na sua conta Vendizap.
Gere o seu par de credenciais: Client ID e Client Secret.
⚠️ Por segurança, o Client e Secret ficam ocultos e só são exibidos apenas no momento da criação.
Não há como recuperá-lo depois. Se você perder, será necessário gerar um novo par. E ao gerar novos o par antigo deixa
de existir, sendo preciso atualizar as credenciais em todos os sistemas que já usavam a integração.
Passo 2: Autentique suas requisições
Toda requisição precisa enviar suas credenciais no cabeçalho (header). Você pode usar o formato:
X-Auth-Id: SEU_CLIENT_ID
X-Auth-Secret: SEU_CLIENT_SECRET
Passo 3: Faça sua primeira requisição
Um bom teste é consultar os dados da sua própria conta:
GET https://app.vendizap.com/api/usuario
Se as credenciais estiverem corretas, a resposta virá com status 200 e os dados da loja em formato JSON (nome, empresa,
e-mail, endereço e subdomínios).
O que dá para fazer com a API?
Usuário - Consultar os dados da conta vendizap autenticada
Produtos - Listar, buscar, cadastrar e atualizar produtos
Categorias - Listar, buscar, cadastrar e atualizar categorias
Variações e Variáveis - Criar e gerenciar opções (tamanho, cor etc.) e vinculá-las aos produtos
Combinações - Listar, vincular e alterar combinações de variações de um produto
Estoque - Atualizar o saldo de estoque
Pedidos - Buscar um pedido específico ou listar pedidos
Descontos progressivos - Listar, buscar, cadastrar, atualizar e excluir
A API não gerencia clientes, cupons, fretes ou pagamentos atualmente.
Paginação e filtros
limit — quantidade de itens por página (padrão e máximo: 100)
skip — quantos registros pular (para avançar de página)
sort — campo de ordenação (padrão: _id)
sortType — ASC ou DESC
Exemplo: GET https://app.vendizap.com/api/produtos?skip=0&limit=50&sort=descricao&sortType=DESC
💡 Para baixar todos os itens, percorra as páginas aumentando o skip de 100 em 100 até a resposta vir vazia. A listagem
traz os dados resumidos; para o registro completo, busque pelo ID (ex.: GET /produtos/{id}).
Webhooks (receber avisos de pedidos)
Em vez de ficar consultando a API o tempo todo, o seu sistema pode cadastrar uma URL de webhook: a Vendizap avisa
automaticamente essa URL sempre que houver um novo pedido ou atualização de status.
O aviso enviado contém, entre outros campos:
{
"client_id": "SEU_CLIENT_ID",
"objeto": "pedidos",
"operacao": "criado",
"id": "ID_DO_PEDIDO",
"resource": "https://app.vendizap.com/api/pedidos/ID_DO_PEDIDO"
}
Ao receber o aviso, seu sistema usa o id para buscar os detalhes completos do pedido.
Limite de requisições
Plano Profissional - 150 requisições por hora
Plano Empresarial - Sem limite prático
Para garantir a melhor performance e estabilidade da nossa plataforma, estabelecemos um limite máximo de 150 requisições
por hora para cada integração.
O que isso significa na prática?
Imagine que seu sistema realiza 100 requisições às 14h30. Às 15h15, ele realiza mais 50 requisições, totalizando 150 no
período. A partir desse momento, a API será temporariamente indisponível para seu sistema até às 15:31, onde serão
liberadas 100 requisições.
Ao exceder, a API responde com status 429 ("Limite da API atingido").
Exemplo prático: sua loja tem 300 produtos e o seu ERP precisa importá-los.
- ❌ Sem boas práticas: o ERP busca um produto de cada vez → 300 requisições. No plano Profissional, ele trava na 150ª
(erro 429) e só continua na hora seguinte.
- ✅ Com boas práticas: o ERP usa a listagem com limit=100 → traz 100 produtos por chamada e baixa os 300 em apenas 3
requisições.
⚠️ Mesmo no Empresarial, integrações mal otimizadas (loops, falhas de script, falta de boas práticas) podem gerar
consumo excessivo e sofrer bloqueio temporário. Sempre use webhooks e paginação em vez de consultas repetidas.
Por que esse limite?
Essa medida é fundamental para manter a estabilidade, evitando sobrecarga no sistema e garantindo que todos os nossos
clientes tenham acesso à API de forma eficiente.
Formato de erros
Quando algo dá errado, a API retorna o código HTTP correspondente e, no corpo, uma mensagem em texto explicando o
motivo:
400 Requisição inválida
401 Sem autorização (credenciais erradas ou plano sem acesso)
404 Registro não encontrado
429 Limite de requisições atingido
500 Erro interno
Exemplo completo: cadastrar um produto com variações e imagens
1. Crie a variação (ex.: "Tamanho" com as variáveis P e M):
POST https://app.vendizap.com/api/variacoes
{
"nome": "Tamanho",
"variaveis": [
{ "nome": "P" },
{ "nome": "M" }
]
}
A resposta traz os IDs da variação e das variáveis — você usa esses IDs no próximo passo.
2) Cadastre o produto, vinculando a variação, as combinações e as imagens:
POST https://app.vendizap.com/api/produtos
{
"descricao": "Camiseta Básica",
"codigo": "CAM-001",
"preco": 79.90,
"detalhes": "Camiseta 100% algodão",
"exibir": true,
"unidadeVenda": "Unidade",
"unidadePreco": "Unidade",
"dimensoes": { "altura": 2, "largura": 20, "comprimento": 30, "peso": 0.2 },
"imagens": [
"https://www.vendizap.com/imagens/produto1.jpg",
"https://www.vendizap.com/imagens/produto2.jpg"
],
"variacoes": [
{
"id": "ID_DA_VARIACAO_TAMANHO",
"obrigatoria": true,
"variaveis": [
{ "id": "ID_VARIAVEL_P", "imagem": 0 },
{ "id": "ID_VARIAVEL_M", "imagem": 1 }
]
}
],
"combinacoes": [
{ "codigo": "CAM-001-P", "preco": 79.90, "combinacao": [ { "variacao": "ID_DA_VARIACAO_TAMANHO", "variavel": "ID_VARIAVEL_P" } ] },
{ "codigo": "CAM-001-M", "preco": 79.90, "combinacao": [ { "variacao": "ID_DA_VARIACAO_TAMANHO", "variavel": "ID_VARIAVEL_M" } ] }
]
}
💡 Sobre as imagens: informe a URL de cada imagem (a Vendizap baixa e hospeda automaticamente). A primeira imagem do
array vira a capa do produto. No bloco variaveis, o campo imagem é o índice (começando em 0) da imagem que aparece
quando aquela variável for selecionada.
3) Atualize o estoque de cada combinação:
PUT https://app.vendizap.com/api/estoque/{ID_DO_PRODUTO}
[
{ "combinacaoSKU": "CAM-001-P", "quantidade": 15 },
{ "combinacaoSKU": "CAM-001-M", "quantidade": 20 }
]
Principais dúvidas
Como cadastro um produto já inativo (oculto na loja)?
Envie "exibir": false no cadastro (POST /produtos). O produto é criado normalmente, mas não aparece na loja até você
atualizá-lo para "exibir": true.
Como inativo ou removo um produto pela API?
A API não exclui produtos definitivamente. Para tirar um produto da loja, atualize-o com "exibir": false (PUT ou PATCH).
Ele deixa de ser exibido, mas continua salvo na sua conta e pode ser reativado a qualquer momento com "exibir": true.
Como pesquiso um produto pelo código?
Use codigocomo filtro na listagem e informe o código exato, Exemplo:
GET https://app.vendizap.com/api/produtos?codigo=CAM-001
Como pesquiso um produto pelo descrição?
Use descricao → busca parcial. Encontra qualquer produto que contenha o texto. Ex.: ?descricao=camiseta traz "Camiseta
Básica", "Camiseta Estampada" etc. Exemplo:
GET https://app.vendizap.com/api/produtos?descricao=camiseta
Como pesquiso um produto pelo detalhes?
Use detalhes → busca parcial. Também encontra por trecho do texto. Ex.: ?detalhes=algodão. Exemplo:
GET https://app.vendizap.com/api/produtos?detalhes=algodão
Quais informações vêm em um pedido pela API?
O pedido retorna todas as informações: dados do cliente (com endereço), itens/produtos (com variações, combinações,
quantidades e valores), forma de pagamento, valor total, frete/taxa de entrega, vendedor (quando houver), observações e
o status do pedido.
Quem controla o estoque: a Vendizap ou o meu ERP?
Depende da lógica do seu ERP. A Vendizap mantém o estoque da loja e permite atualizá-lo pela API (PUT /estoque), mas
como sincronizar (qual sistema é a fonte da verdade e quando atualizar) é definido pelo sistema que você integra.
Quando eu vendo na loja Vendizap, a baixa de estoque vai automaticamente para o meu ERP?
Não automaticamente. Quando há um novo pedido, a Vendizap avisa o seu sistema por webhook (objeto: pedidos, operacao:
criado). A partir desse aviso, o seu ERP decide quando importar o pedido e dar baixa no estoque do lado dele.
Recebi o erro 429 (limite atingido). Quanto tempo preciso esperar?
O limite funciona em janela deslizante de 60 minutos: a Vendizap conta quantas requisições você fez nos últimos 60
minutos. Não existe um "reset" em horário fixo — você recupera capacidade aos poucos, à medida que cada requisição
completa 60 minutos. Por exemplo: se você fez 150 chamadas em 5 minutos, precisará esperar cerca de 55 minutos para a
maior parte "sair" da janela.
