API Aivooz
Envie o catálogo, o estoque e os documentos da sua empresa. A IA de atendimento consulta esses dados no WhatsApp para responder, mostrar fotos e vender.
URL base: https://aivooz.com.br/api/v1. Todas as requisições e respostas usam JSON (UTF-8). Os campos aceitam nomes em português (como nos exemplos) ou em inglês (name, price, stock...).
Usa Shopify, WooCommerce, Bling ou Tiny? Não precisa da API: conecte a loja em Catálogo → Lojas e sistemas.
Autenticação
Gere uma chave em Catálogo → API e envie em todas as requisições:
Authorization: Bearer avz_SUA_CHAVE A chave dá acesso aos dados da sua conta. Guarde no servidor, nunca em código que roda no navegador ou no aplicativo. Se vazar, revogue no painel e gere outra.
Limites
- 300 requisições por minuto por chave (acima disso: HTTP 429 com
Retry-After). - Até 500 produtos por requisição em
POST /produtose 1.000 itens emPATCH /estoque. - Número máximo de produtos ativos conforme o plano (veja em status).
Erros
| HTTP | Quando |
|---|---|
| 400 | JSON malformado ou campo obrigatório ausente. |
| 401 | Chave ausente, inválida ou revogada. |
| 404 | Produto, documento ou rota não encontrados. |
| 413 | Lote maior que o permitido. |
| 422 | Nenhum item do lote pôde ser gravado (veja resultado). |
| 429 | Limite de requisições atingido. |
O corpo de erro sempre traz {"erro": "mensagem"}. Em lotes, cada item tem seu próprio status: um item com erro não impede os outros.
Objeto produto
Cada produto pode ter variações (tamanho, cor...). O estoque e o preço ficam na variação. Produto sem variações: informe estoque e preco direto no produto.
| Campo | Tipo | Descrição |
|---|---|---|
id | texto | Obrigatório. Seu identificador do produto. Enviar de novo o mesmo id atualiza. |
nome | texto | Obrigatório. |
descricao | texto | Pode conter HTML (é convertido em texto). |
categoria | texto | Ex.: Calças > Jeans. |
marca, tags | texto | Ajudam a IA a encontrar o produto. |
genero | texto | feminino, masculino, unissex ou infantil. |
preco, preco_promocional | número | Em reais. Ex.: 189.9. |
link | URL | Página do produto (a IA envia ao cliente). |
imagens | lista de URLs | A primeira é a principal. A IA envia as fotos no WhatsApp e usa a principal para busca por foto. |
videos | lista de URLs | MP4 de até 16 MB. |
atributos | objeto | Características livres. Ex.: {"tecido": "viscose"}. |
ativo | booleano | false tira o produto do atendimento sem apagar. |
estoque | inteiro | Só para produto sem variações. Omitido = não controlado (sempre disponível). |
variacoes[] | lista | id, sku, tamanho, cor, atributos, preco, preco_promocional, estoque, ativo. |
POST/produtos
Cria ou atualiza pelo id. Envie um produto ou {"produtos": [...]}.
curl -X POST https://aivooz.com.br/api/v1/produtos \
-H "Authorization: Bearer avz_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"produtos": [{
"id": "CJ-100",
"nome": "Calça Jeans Mom Plus Size",
"categoria": "Calças > Jeans",
"genero": "feminino",
"preco": 189.90,
"preco_promocional": 159.90,
"link": "https://minhaloja.com.br/calca-mom",
"imagens": ["https://minhaloja.com.br/fotos/mom-1.jpg"],
"variacoes": [
{ "id": "CJ100-44-AZ", "sku": "CJ100-44-AZ", "tamanho": "44", "cor": "Azul", "estoque": 3 },
{ "id": "CJ100-46-AZ", "sku": "CJ100-46-AZ", "tamanho": "46", "cor": "Azul", "estoque": 0 }
]
}]
}' {
"processados": 1,
"erros": 0,
"resultado": [ { "external_id": "CJ-100", "status": "criado", "id": 57 } ]
} status: criado, atualizado, sem_alteracao ou erro. Variações que não vierem no envio são removidas do produto. Em poucos segundos o produto fica disponível para a IA.
GET/produtos?pagina=1&limite=50
Lista os produtos enviados pela API (até 200 por página). inativos=1 inclui os desativados.
GET/produtos/{id}
Retorna o produto com as variações e o estoque atual.
DELETE/produtos/{id}
Apaga o produto. Para só tirar do atendimento, prefira enviar "ativo": false.
Estoque e preço
PATCH/estoque
Atualização rápida, ideal para chamar a cada venda. Identifique por sku (vale para qualquer origem, inclusive lojas conectadas) ou por produto_id + variacao_id (produtos da API).
curl -X PATCH https://aivooz.com.br/api/v1/estoque \
-H "Authorization: Bearer avz_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{ "itens": [
{ "sku": "CJ100-44-AZ", "estoque": 2 },
{ "sku": "CJ100-46-AZ", "estoque": 5, "preco": 179.90 }
] }' Base de conhecimento
Textos que a IA consulta para responder: políticas, manuais, perguntas frequentes. Arquivos (PDF, Word) podem ser enviados pelo painel.
POST/conhecimento
curl -X POST https://aivooz.com.br/api/v1/conhecimento \
-H "Authorization: Bearer avz_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{ "titulo": "Política de trocas", "texto": "Aceitamos trocas em até 7 dias..." }' Resposta 201 com {"id": 12, "status": "pending"}. O documento fica ready em alguns segundos. Para atualizar um texto, remova o antigo e envie o novo.
GET/conhecimento
Lista os documentos com status (pending, processing, ready, error).
DELETE/conhecimento/{id}
Remove o documento. A IA deixa de usá-lo na hora.
Status da conta
GET/status
{ "ok": true, "produtos_ativos": 1240, "documentos": 8, "limite_produtos": 50000 } 