Capacidades por Tópico de Notificação
Tópicos de Notificação | O que os Agentes Podem (e Não Podem) Fazer
Para future Claude
Esta nota é um aprofundamento da seção "Tópicos monitorados hoje" do Mapa Geral (seção 2). Pra cada um dos 18 tópicos de webhook, mapeamos: o recurso que o handler consulta depois da notificação (padrão notify-then-fetch), a categoria de permissão que cobre esse recurso (ver Permissões funcionais), o que a API permite ler e escrever segundo a doc oficial, e qual agente do Bunker consome isso hoje.
Diagramas (D10) ficam pra uma próxima etapa, depois que o conteúdo em markdown estiver fechado.
Como ler as tabelas
- Status (✅/⬜): mesmo do Mapa Geral, indica se o Bunker já tem handler pra esse tópico hoje.
- Recurso (GET): a chamada que o handler faz após receber a notificação, pra buscar o dado completo.
- Lê: o que a doc oficial diz que esse GET retorna.
- Escreve: ações de escrita disponíveis (em qualquer endpoint relacionado ao recurso, não só no GET), ou "nenhuma" quando o recurso é só leitura/diagnóstico.
- Permissão: categoria funcional de Permissões funcionais que precisa estar habilitada no DevCenter pra essa chamada não cair em
PA_UNAUTHORIZED_RESULT_FROM_POLICIES(403). - Agente Bunker: quem consome isso hoje, segundo a tabela "Onde cada agente atua no ML" do Mapa Geral (seção 3).
Vendas
| Status | Tópico | Recurso (GET) | Lê | Escreve | Permissão | Agente Bunker |
|---|---|---|---|---|---|---|
| ✅ | orders_v2 |
/orders/$ORDER_ID |
Itens, comprador, pagamentos, envio, status e tags do pedido (ex.: paused, cancelled) |
Nenhuma direta. Não existe PUT /orders; ações reais passam por outros recursos (feedback, envio, pagamento) |
Vendas e envios | Gestor, Analista, SAC |
| ✅ | payments |
/collections/$PAYMENT_ID |
Status do pagamento (approved, in_process, rejected, refunded), valor, taxas |
Nenhuma neste recurso. Estornos e disputas passam pelo fluxo de claims/returns | Vendas e envios | Gestor (conciliação financeira), Analista (margem real) |
| ✅ | shipments |
/shipments/$SHIPMENT_ID |
Status e substatus (ready_to_ship, shipped, delivered, invoice_pending, receiver_absent...), rastreio, custo de envio |
Geração de etiqueta. Em envios custom/ME1, "marcar como entregue" acontece via orders_feedback, não aqui |
Vendas e envios | SAC, Gestor |
| ⬜ | orders_feedback |
/orders/$ORDER_ID/feedback, /feedback/$FEEDBACK_ID |
Feedback (rating, motivo, mensagem) de compra e de venda de cada pedido | POST /orders/$ORDER_ID/feedback (publicar feedback do vendedor), POST /feedback/$FEEDBACK_ID/reply (responder feedback recebido), PUT /feedback/$FEEDBACK_ID (alterar) |
Vendas e envios | nenhum hoje |
Produto/Estoque
| Status | Tópico | Recurso (GET) | Lê | Escreve | Permissão | Agente Bunker |
|---|---|---|---|---|---|---|
| ✅ | items |
/items/$ITEM_ID (ou /items/$ITEM_ID/sale_price?context=... quando a notificação for de mudança de preço) |
Título, descrição, atributos, preço, fotos, status (active/paused/under_review), available_quantity |
PUT /items/$ITEM_ID (título, atributos, preço), POST /items (criar anúncio) |
Publicação e sincronização | Anúncios (título/atributos), Criativo (fotos), Analista (preço/listing type) |
| ✅ | stock-location |
/user-products/$USER_PRODUCT_ID/stock |
Quantidade por depósito, dentro do modelo de Estoque Distribuído | Configuração dos stock_locations do User Product |
Publicação e sincronização | Gestor, Analista |
| ⬜ | price_suggestion |
/suggestions/items/$ITEM_ID/details |
Preço sugerido pelo Mercado Livre pra esse item | Nenhuma no próprio recurso. Aplicar a sugestão é um PUT /items/$ITEM_ID com o novo preço |
Publicação e sincronização | nenhum hoje |
| ⬜ | user_products_families |
/sites/$SITE_ID/user-products-families/$FAMILY_ID |
Atributos compartilhados da família (family_name, domain_id) e lista de User Products (variações) filhos |
POST .../tasks (edita atributos da família e propaga pra todas as variações, assíncrono), POST /user-products/$USER_PRODUCT_ID/items (adiciona uma nova condição de venda à variação) |
Publicação e sincronização | nenhum hoje |
Pra quem não é dev
"User Products" e "família de produtos" são o jeito do Mercado Livre de agrupar variações do mesmo anúncio (cor, tamanho, voltagem) sob um produto pai. Mudar um atributo da família propaga pra todas as variações de uma vez.
Catálogo
| Status | Tópico | Recurso (GET) | Lê | Escreve | Permissão | Agente Bunker |
|---|---|---|---|---|---|---|
| ⬜ | catalog_item_competition_status |
/items/$ITEM_ID/price_to_win?version=v2 |
Status da disputa de catálogo (winning, competing, sharing_first_place, listed), price_to_win, lista de boosts (ex.: fulfillment, frete grátis), motivos de não estar competindo, dados do vencedor atual |
Nenhuma neste recurso. É puramente diagnóstico, a ação acontece em outro lugar (mudar preço, ativar Flex/Full) | Publicação e sincronização | nenhum hoje |
| ⬜ | catalog_suggestions |
/catalog_suggestions/$SUGGESTION_ID |
Status da sugestão de catálogo (UNDER_REVIEW, WAITING_FOR_FIX, PUBLISHED, REJECTED) e sub-status |
POST /catalog_suggestions (criar sugestão de novo produto pro catálogo), PUT /catalog_suggestions/$SUGGESTION_ID (editar), POST /catalog_suggestions/validate (pré-validar), POST/PUT na descrição da sugestão |
Publicação e sincronização | nenhum hoje |
Pra quem não é dev
"Catálogo" no Mercado Livre é a página de produto compartilhada por vários vendedores (a "buy box"). price_to_win é o preço que o anúncio precisaria ter pra ganhar o destaque dessa página. "Catalog suggestions" é o canal pra propor a inclusão de um produto novo no catálogo (parte do Brand Central).
Pós-venda
| Status | Tópico | Recurso (GET) | Lê | Escreve | Permissão | Agente Bunker |
|---|---|---|---|---|---|---|
| ✅ | questions |
/questions/$QUESTION_ID |
Pergunta e item relacionado | POST /answers (responder) |
Comunicação pré e pós-venda | SAC |
| ✅ | messages |
/messages/$RESOURCE |
Conteúdo da mensagem (subtópico created) ou confirmação de leitura (subtópico read) |
POST /messages/packs/$PACK_ID/$SELLER_ID (responder) |
Comunicação pré e pós-venda | SAC |
| ✅ | post_purchase/claims |
/post-purchase/v1/claims/$CLAIM_ID |
Detalhe da reclamação: motivo, prazo de SLA, evidências (subtópico claims); ação executada numa claim já aberta (subtópico claims_actions) |
Mensagens e evidências na claim. Sempre Tier 3 (alto risco, exige aprovação) | Comunicação pré e pós-venda / Vendas e envios | SAC |
Fiscal
| Status | Tópico | Recurso (GET) | Lê | Escreve | Permissão | Agente Bunker |
|---|---|---|---|---|---|---|
| ⬜ | invoices |
/users/$USER_ID/invoices/$INVOICE_ID |
Nota fiscal emitida pelo Faturador do Mercado Livre (consulta e download, 11 tipos de documento) | Não é neste recurso. Pra envios drop_off/xd_drop_off/cross_docking/xd_same_day, a NF do vendedor é importada via outro endpoint (upload de XML), e é isso que resolve o substatus invoice_pending (seção 1 do Mapa Geral) |
Faturamento | nenhum hoje |
Promo/Logística
| Status | Tópico | Recurso (GET) | Lê | Escreve | Permissão | Agente Bunker |
|---|---|---|---|---|---|---|
| ✅ | public_offers |
/seller-promotions/offers/$OFFER_ID |
Status da oferta (started, finished, pending, candidate), tipo (CUSTOM, PRICE_DISCOUNT, DEAL...) |
Entrar ou saír de uma campanha via /seller-promotions/items |
Promoções, cupons e descontos | Analista |
| ✅ | public_candidates |
/seller-promotions/candidates/$CANDIDATE_ID |
Item convidado pelo Mercado Livre pra participar de uma promoção | Aceitar ou recusar o convite via /seller-promotions |
Promoções, cupons e descontos | Analista |
| ⬜ | flex-handshakes |
/flex/sites/$SITE_ID/shipments/$SHIPMENT_ID/assignment/v1 |
Transportadora/motorista atribuído no momento do handshake (transferência entre transportadoras, ou primeiro scan) | Nenhuma neste recurso. Configuração de Flex (zonas, feriados, ativar/desativar item) tem endpoints próprios, fora deste tópico | Vendas e envios | nenhum hoje |
| ⬜ | fbm_stock_operations |
/stock/fulfillment/operations/$OPERATION_ID (ou /search), /inventories/$INVENTORY_ID/stock/fulfillment |
Operações de estoque Full (entrada, confirmação de venda, devolução, transferência, ajuste/quarentena) e níveis atuais por inventário | Nenhuma. A API de estoque Full é read-only pro vendedor, ação real acontece via painel do Mercado Livre | Vendas e envios | nenhum hoje |
Os 8 gaps, em detalhe
Notas adicionais sobre cada tópico ⬜, complementando a tabela "Priorização dos gaps" do Mapa Geral (seção 2):
catalog_item_competition_status: é só leitura/diagnóstico, confirma queprice_to_winnão tem endpoint de escrita próprio. A ação de "ganhar a buy box" já está mapeada no fluxo do Analista (Mapa Geral seção 5) viaPUT /items. Esse webhook seria um segundo gatilho dePRICE_CHANGE, hoje só existe o cronprice-monitor.price_suggestion: complementa o mesmo cronprice-monitorcomo um terceiro sinal de "hora de reavaliar preço", paralelo aocatalog_item_competition_status.user_products_families: só é relevante pra quem usa variações (Preço por Variação / User Products). Tem escrita real (editar atributos da família, adicionar condição de venda), mas é o gap com menor impacto imediato se o catálogo do seller não usa variações.catalog_suggestions: é o único dos 8 gaps com escrita rica (criar, validar e editar sugestões de produto pro catálogo via Brand Central). Está na prioridade #3 (crescer) do Mapa Geral.orders_feedback: é bidirecional, lê o feedback recebido do comprador e publica/responde o feedback do vendedor. É o fechamento formal da venda quando não há Mercado Envios, e está ligado à retenção da Liberação de Pagamentos (seção 1 do Mapa Geral).invoices: é só consulta da NF já emitida pelo Faturador do Mercado Livre. O gap fiscal real da seção 1 (NF que destravainvoice_pendingemdrop_off/xd_drop_off/cross_docking/xd_same_day) é resolvido por outro endpoint (importar XML), que nem aparece como tópico de notificação, é uma ação que o vendedor dispara, não um evento que o Mercado Livre avisa.flex-handshakes: só leitura, baixa complexidade pra implementar. Só interessa a quem usa Envios Flex (entrega própria/motorista).fbm_stock_operations: confirma o que Fluxo Agentes já registrava sobre o "Agente de Estoque FULL", a API de estoque Full é read-only pro vendedor. Está na prioridade #2 (dinheiro) do Mapa Geral.
Achados de completude da tabela
Cruzando os 18 tópicos com a documentação oficial completa de "Notificações", a tabela do Mapa Geral está completa pro escopo de e-commerce geral do Bunker. Quatro detalhes valem registro:
itemstambém cobre mudança de preço. Quando a notificação deitemsvem por criação, edição ou exclusão de preço, o handler deve consultar/items/$ITEM_ID/sale_price?context=$CONTEXT(preço de venda real, considerando promoções e canal) em vez de (ou além de)/items/$ITEM_ID. Não existe um tópico separado pra isso, apesar de uma página da doc oficial citaritems_pricescomo se fosse outro tópico, o exemplo de payload da própria página de Notificações usa"topic": "items".messagestem 2 subtópicos.created(mensagem nova) eread(confirmação de leitura). A tabela do Mapa Geral não distingue, mas o handler já recebe os dois e deve tratar cada um.post_purchasetem 2 subtópicos.claims(reclamação aberta) eclaims_actions(ação executada numa claim já existente, ex.: resposta, anexo, decisão). A tabela cita sópost_purchase/claims,claims_actionsé um sinal adicional que já chega no mesmo tópico.vis_leadseleads-creditsficam de fora, corretamente. São tópicos exclusivos das verticais de imóveis, veículos e serviços (Real Estate/Motors/Services). O Bunker cobre e-commerce geral, então esses 2 tópicos não pertencem a esta tabela. Se o Bunker um dia atender essas verticais, eles entram aqui.
Relacionados
- Mapa Geral, seção 2 (tabela original) e seção 3 (mapeamento agente × área do ML)
- Permissões funcionais, as 8 categorias de permissão usadas na coluna "Permissão"
- Fluxo Agentes, detalhe do "Agente de Estoque FULL" (corrobora o achado de
fbm_stock_operationsser read-only)