Neste artigo você vai aprender o que as APIs de Catálogo resolvem, quais são seus conceitos-chave e quais endpoints usar em cada caso para gerenciar seu estoque dentro do Botmaker.
As APIs de Catálogo permitem gerenciar todo o seu estoque de produtos dentro do Botmaker para usá-lo nas conversas com os seus clientes: exibir o catálogo no WhatsApp, recomendar produtos a partir de um agente, controlar o estoque por loja física, aplicar preços diferentes conforme a região geográfica e manter tudo sincronizado com plataformas externas como a Meta (WhatsApp/Facebook). Em vez de cadastrar produtos manualmente, você pode integrá-las ao seu e-commerce, ERP ou sistema de estoque e manter o Botmaker atualizado automaticamente.
Você pode:
Requisitos prévios
Acesso à sua conta do Botmaker com permissões para administrar catálogos. Credenciais de API válidas para autenticar as suas requisições. Se você for publicar no WhatsApp, uma integração com a Meta configurada na sua conta.
Conceitos-chave
Antes de operar com a API, vale conhecer os seis conceitos sobre os quais se apoia toda a gestão do catálogo.
Catálogo: o contêiner principal. Costuma haver um por marca ou por unidade de negócio.
Categorias: agrupamentos de produtos (por exemplo, Bebidas, Sobremesas, Promoções). Servem para filtrar e ordenar. Produtos: cada item que você vende. É identificado pelo SKU e inclui nome, descrição, preço, imagens, disponibilidade e estoque.
Lojas (Stores): pontos de venda físicos ou lógicos. Cada loja tem o seu próprio estoque por SKU.
Zonas: áreas geográficas que agrupam lojas. Servem para aplicar preços diferentes conforme a região.
Esquemas de preço (Price Schemas): listas de preços que sobrescrevem os preços base para uma ou várias zonas.
Todos os endpoints ficam sob o prefixo /v2.0/ecommerce/catalogs. Abaixo estão as operações agrupadas conforme o que você precisa fazer.
Passo 1: Comece criando e administrando o catálogo
O catálogo é o ponto de partida: é o contêiner onde vão viver as suas categorias, produtos, lojas e preços.
O que você quer fazer | Endpoint |
Listar os seus catálogos | GET /ecommerce/catalogs |
Criar um catálogo novo | POST /ecommerce/catalogs |
Passo 2: Organize o catálogo com categorias
As categorias agrupam os seus produtos para facilitar o filtro e a ordenação dentro da conversa.
O que você quer fazer | Endpoint |
Ver as categorias de um catálogo | GET /ecommerce/catalogs/{catalogId}/categories |
Criar ou atualizar categorias (em lote) | POST /ecommerce/catalogs/{catalogId}/categories |
Excluir uma categoria | DELETE /ecommerce/catalogs/{catalogId}/categories/{categoryCode} |
Passo 3: Carregue e mantenha os seus produtos
Esta é a operação mais frequente: o caso típico é o seu sistema enviar ao Botmaker a lista de produtos atualizada de tempos em tempos.
O que você quer fazer | Endpoint |
Listar ou buscar produtos do catálogo | GET /ecommerce/catalogs/{catalogId}/products |
Ver o detalhe de um produto | GET /ecommerce/catalogs/{catalogId}/products/{sku} |
Criar ou atualizar produtos (vários por requisição) | POST /ecommerce/catalogs/{catalogId}/products |
Excluir um produto | DELETE /ecommerce/catalogs/{catalogId}/products/{sku} |
Excluir produtos em lote (até 50 por requisição) | POST /ecommerce/catalogs/{catalogId}/products/batch/delete |
Passo 4: Gerencie lojas e estoque por loja
Se você vende a partir de mais de um ponto de venda e cada um tem o seu próprio estoque, esta é a seção que você precisa.
O que você quer fazer | Endpoint |
Listar as suas lojas | GET /ecommerce/catalogs/{catalogId}/stores |
Criar ou atualizar lojas com o seu estoque | POST /ecommerce/catalogs/{catalogId}/stores |
Excluir uma loja | DELETE /ecommerce/catalogs/{catalogId}/stores/{code} |
Excluir lojas em lote | POST /ecommerce/catalogs/{catalogId}/stores/batch/delete |
Passo 5: Configure zonas geográficas e preços diferenciados
Se você trabalha com preços diferentes por região (capital vs. interior, país A vs. país B, zona premium vs. padrão), você combina zonas com esquemas de preço.
O que você quer fazer | Endpoint |
Listar zonas | GET /ecommerce/catalogs/{catalogId}/zones |
Ver uma zona | GET /ecommerce/catalogs/{catalogId}/zones/{zoneCode} |
Criar ou atualizar zonas | POST /ecommerce/catalogs/{catalogId}/zones |
Excluir uma zona | DELETE /ecommerce/catalogs/{catalogId}/zones/{zoneCode} |
Excluir zonas em lote | POST /ecommerce/catalogs/{catalogId}/zones/batch/delete |
Listar todos os esquemas de preço | GET /ecommerce/catalogs/{catalogId}/price-schemas |
Listar o esquema de preço de uma zona | GET /ecommerce/catalogs/{catalogId}/price-schemas/{zoneCode} |
Criar ou atualizar um esquema de preço | POST /ecommerce/catalogs/{catalogId}/price-schemas |
Passo 6: Integre com a Meta (WhatsApp / Facebook)
Com esta integração, o seu catálogo do Botmaker é publicado automaticamente no WhatsApp e pode ser exibido dentro do chat.
O que você quer fazer | Endpoint |
Conectar o seu catálogo à Meta | POST /ecommerce/catalogs/{catalogId}/platform-integrations |
Sincronizar (publicar produtos na Meta) | POST /ecommerce/catalogs/{catalogId}/platform-integrations/{platform}/sync |
Desconectar a integração | DELETE /ecommerce/catalogs/{catalogId}/platform-integrations/{platform} |
Nota: depois de criar ou atualizar produtos no Botmaker, você precisa chamar o endpoint de sync para que essas mudanças apareçam no WhatsApp/Meta. A sincronização é assíncrona: o endpoint devolve um identificador para que você possa consultar o resultado.
Se você está se integrando pela primeira vez, esta é a ordem sugerida:
Daqui para frente, mantenha tudo atualizado chamando os POST de produtos e lojas quando houver mudanças no seu sistema, e dispare sync para refleti-las no WhatsApp.
Lembre-se de visitar nossa Central de Ajuda para obter mais informações.