Para desenvolvedores e agentes

API do CityBusca

Gerencie sua loja de forma programática (criar, editar e publicar produtos, atualizar dados, consultar estatísticas) ou leia o catálogo público. Pensada para integrações e para agentes de IA operarem a loja em nome do lojista.

Gerar uma chave Spec OpenAPI 3.1

Comece aqui

Gere uma chave em /painel/api, marcando apenas os escopos de que precisa. O token aparece uma única vez; guarde-o em local seguro.
Envie o token no header Authorization em toda requisição autenticada:

Authorization: Bearer cb_live_xxxxxxxxxxxxxxxxxxxxxxxx

Escopos

products:readListar e ver produtos da sua loja.
products:writeCriar, editar, publicar, arquivar e enviar imagens.
store:readVer os dados da sua loja.
store:writeAtualizar os dados da sua loja.
stats:readContatos, cliques e visitas da sua loja.

Limites de uso

120 requisições/min por chave nos endpoints autenticados.
60 requisições/min por IP nos endpoints públicos (/public/*).
Ao exceder: HTTP 429 com code: rate_limited e o campo retryAt.

Exemplo: criar um produto

Substitua o token e o categoryId pelos seus valores reais.

curl -X POST https://citybusca.com.br/api/v1/products \
  -H "Authorization: Bearer cb_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Caderno universitário 200 folhas",
    "categoryId": 12,
    "description": "Caderno espiral, capa dura, 10 matérias.",
    "priceFrom": 29.90,
    "status": "ACTIVE"
  }'

MCP — deixe um agente de IA operar sua loja

Além da API REST, o CityBusca expõe um MCP server remoto (Streamable HTTP): um agente como o Claude conecta com a mesma chave (cb_live_...) e ganha ferramentas para descobrir o catálogo, gerir produtos e ler estatísticas — operando somente a sua loja. Ideal para conversar: “quantos contatos tive essa semana?”, “publica o produto X”, “quais produtos estão sem foto?”.

Endpoint

POST https://citybusca.com.br/api/mcp — transporte Streamable HTTP, sem sessão.
Header Authorization: Bearer cb_live_... em toda requisição. Gere a chave em /painel/api, marcando os escopos das tools que o agente vai usar.

Como conectar

Em um cliente MCP que aceite servidor HTTP remoto, aponte para a URL acima e mande o header de autorização. Exemplo de configuração:

{
  "mcpServers": {
    "citybusca": {
      "type": "http",
      "url": "https://citybusca.com.br/api/mcp",
      "headers": { "Authorization": "Bearer cb_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Para testar manualmente, use o MCP Inspector: aponte-o para https://citybusca.com.br/api/mcp com o header Authorization e rode initialize → tools/list → tools/call.

Tools e escopos

Tool	Escopo	O que faz
`search_products`	público	Busca no catálogo público de uma cidade.
`get_store`	público	Detalha uma loja pública e seus produtos.
`list_my_products`	`products:read`	Lista os produtos da sua loja.
`create_product`	`products:write`	Cria um produto.
`update_product`	`products:write`	Edita um produto.
`publish_product`	`products:write`	Publica (ACTIVE).
`unpublish_product`	`products:write`	Despublica (DRAFT).
`update_store`	`store:write`	Atualiza os dados da loja.
`get_store_stats`	`stats:read`	Estatísticas dos últimos 30 dias.

Tools de descoberta leem só campos públicos. As de gestão e estatística operam apenas a loja do dono da chave (ownership garantido) e respeitam os limites do plano e o rate-limit de 120 req/min por chave.

MCP público — descoberta do catálogo sem chave

Para agentes do lado do consumidor (ex.: um agente no WhatsApp), o CityBusca expõe um MCP público somente-leitura: sem token, com rate-limit por IP, ele enxerga o catálogo da cidade inteira e devolve, para cada produto, a loja, a URL pública e um link de WhatsApp pré-preenchido — a conversão acontece na conversa com o lojista, não num checkout.

Endpoint

POST https://citybusca.com.br/api/mcp/public — transporte Streamable HTTP, sem sessão e sem header de autorização.
Limite de 60 requisições/min por IP; ao exceder, HTTP 429 com retryAt.

Tools

Tool	O que faz
`discover_products`	Busca produtos no catálogo de uma cidade; cada item traz a loja, a URL pública e o link de WhatsApp pré-preenchido.
`get_city_catalog`	Resumo da cidade: total de lojas/produtos ativos e categorias com contagem.
`get_store_public`	Vitrine pública de uma loja: contato público, produtos ativos e links de WhatsApp.

Exemplo: buscar produtos

curl -X POST https://citybusca.com.br/api/mcp/public \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "discover_products",
      "arguments": { "city": "toledo-pr", "q": "bebedouro" }
    }
  }'

Somente leitura e só campos públicos (nunca e-mail/CPF/CNPJ). Para criar, editar ou publicar produtos, use o MCP autenticado acima.

Endpoints

Referência gerada a partir do spec OpenAPI. Importe-o em ferramentas como Scalar, Swagger UI, Postman ou Insomnia para explorar de forma interativa. Base: https://citybusca.com.br/api/v1

Produtos

Gestão dos produtos da sua loja (token).

get/api/v1/productsLista produtos da sua loja

Retorna os produtos do dono da chave, em todos os status. Paginado. Filtros: `status` (ALL|DRAFT|ACTIVE|ARCHIVED), `q` (busca por nome).

escopo products:read

post/api/v1/productsCria um produto

Cria um produto na sua loja. Respeita o limite do plano grátis (`FREE_PLAN.maxProducts`); ao estourar retorna 409 `plan_limit`.

escopo products:write

get/api/v1/products/{id}Detalha um produto

escopo products:read

patch/api/v1/products/{id}Atualiza um produto

Substitui os campos do produto (mesmo corpo do POST). Checa posse.

escopo products:write

delete/api/v1/products/{id}Arquiva um produto

Soft-delete: muda o status para `ARCHIVED`. Idempotente.

escopo products:write

post/api/v1/products/{id}/publishPublica um produto

Muda o status para `ACTIVE`.

escopo products:write

post/api/v1/products/{id}/unpublishDespublica um produto

Muda o status para `DRAFT`.

escopo products:write

get/api/v1/products/{id}/imagesLista imagens de um produto

escopo products:read

post/api/v1/products/{id}/imagesRegistra uma imagem já enviada ao storage

Registra e processa uma imagem cujo binário já foi enviado ao storage. O upload do binário em si é feito por URL assinada (fluxo do painel); este endpoint apenas vincula a imagem ao produto. Conta na cota de imagens.

escopo products:write

Loja

Dados e estatísticas da sua loja (token).

get/api/v1/store/meDados da sua loja

Inclui dados sensíveis do PRÓPRIO dono (cnpj, whatsapp).

escopo store:read

patch/api/v1/store/meAtualiza a sua loja

escopo store:write

get/api/v1/store/me/statsEstatísticas da sua loja

Contatos/cliques de WhatsApp (`ContactClick`), pageviews (`PageView`), contagem de produtos por status e produtos sem foto. Janela de 30 dias.

escopo stats:read

Público

Leitura do catálogo público (sem token).

get/api/v1/public/productsBusca pública no catálogo de uma cidade

Sem token. Rate-limit por IP (60/min). Só campos públicos. Requer `city` (slug).

Público, sem token

get/api/v1/public/storeDetalhe público de uma loja + produtos ativos

Sem token. Rate-limit por IP (60/min). Só campos públicos (nunca e-mail/CPF/CNPJ de terceiros). Requer `city` e `store` (slugs).

Público, sem token

Erros

Toda resposta de erro tem o formato { "error": "…", "code": "…" }. Os códigos são estáveis: programe contra o code, não contra a mensagem. Principais: missing_token, invalid_token, revoked_token, expired_token (401); missing_scope (403); validation (400); plan_limit (409); rate_limited (429); not_found (404).