Aivooz

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 /produtos e 1.000 itens em PATCH /estoque.
  • Número máximo de produtos ativos conforme o plano (veja em status).

Erros

HTTPQuando
400JSON malformado ou campo obrigatório ausente.
401Chave ausente, inválida ou revogada.
404Produto, documento ou rota não encontrados.
413Lote maior que o permitido.
422Nenhum item do lote pôde ser gravado (veja resultado).
429Limite 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.

CampoTipoDescrição
idtextoObrigatório. Seu identificador do produto. Enviar de novo o mesmo id atualiza.
nometextoObrigatório.
descricaotextoPode conter HTML (é convertido em texto).
categoriatextoEx.: Calças > Jeans.
marca, tagstextoAjudam a IA a encontrar o produto.
generotextofeminino, masculino, unissex ou infantil.
preco, preco_promocionalnúmeroEm reais. Ex.: 189.9.
linkURLPágina do produto (a IA envia ao cliente).
imagenslista de URLsA primeira é a principal. A IA envia as fotos no WhatsApp e usa a principal para busca por foto.
videoslista de URLsMP4 de até 16 MB.
atributosobjetoCaracterísticas livres. Ex.: {"tecido": "viscose"}.
ativobooleanofalse tira o produto do atendimento sem apagar.
estoqueinteiroSó para produto sem variações. Omitido = não controlado (sempre disponível).
variacoes[]listaid, 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 }
      ] }'
Loja conectada (Shopify, Bling...) também é atualizada sozinha na sincronização. Use o PATCH quando quiser o estoque em tempo real entre uma sincronização e outra.

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 }