Por mais de uma década, o Schema.org foi sinônimo de rich snippets — estrelinhas de avaliação no Google, preços em destaque, breadcrumbs clicáveis. Lindo. Mas superficial.
Enquanto o mercado de SEO ainda debate se o FAQ rich snippet ajuda ou atrapalha, uma revolução silenciosa acontece nas entrelinhas do vocabulário Schema.org: a marcação de ações.
Não se trata mais de aparecer. Trata-se de executar.
Rich snippet é visibilidade. Action é receita.
Rich snippet tradicional responde a uma pergunta implícita do Google: “O que tem nessa página?”.
Schema.org para ações responde a uma pergunta muito mais poderosa: “O que um agente pode fazer nessa página?”.
Um agente de IA — como Operator, ChatGPT Shopping ou Claude com MCP — não quer saber apenas o preço do seu produto. Ele quer saber:
- Posso comprar esse produto diretamente?
- Qual o endpoint para adicionar ao carrinho?
- É POST ou GET?
- Quais parâmetros preciso enviar?
- Precisa de autenticação?
- Há um hook humano obrigatório?
Quando você implementa potentialAction com BuyAction e EntryPoint, você está entregando ao agente o manual de instruções para converter.
Os três tipos de ação que seu negócio precisa implementar
1. BuyAction — Comprar um produto ou serviço
Usado em Product, Service ou Offer. É a ação mais direta e a que gera receita imediata.
Exemplo mínimo:
json
{
"@context": "https://schema.org",
"@type": "Product",
"name": "Filtro de Óleo Esportivo",
"offers": {
"@type": "Offer",
"price": "49.90",
"priceCurrency": "BRL",
"availability": "https://schema.org/InStock",
"url": "https://www.lojax.com/filtro-oleo-esportivo"
},
"potentialAction": {
"@type": "BuyAction",
"target": {
"@type": "EntryPoint",
"urlTemplate": "https://www.lojax.com/api/agent/cart/add",
"httpMethod": "POST",
"contentType": "application/json"
},
"description": "Adiciona o produto ao carrinho e retorna checkout_url."
}
}
O que isso comunica ao agente:
- “Você pode comprar este item.”
- “Para isso, faça um POST neste endpoint enviando JSON.”
- “Se der certo, receberá a URL do checkout.”
2. ReserveAction — Reservar horário, mesa, consulta
Ideal para restaurantes, clínicas, escritórios, salões.
json
{
"@context": "https://schema.org",
"@type": "Service",
"name": "Consulta Odontológica",
"provider": {
"@type": "Dentist",
"name": "Clínica Sorriso",
"address": { ... }
},
"potentialAction": {
"@type": "ReserveAction",
"target": {
"@type": "EntryPoint",
"urlTemplate": "https://www.clinicasorriso.com/api/agent/schedule",
"httpMethod": "POST",
"contentType": "application/json"
},
"result": {
"@type": "Reservation",
"name": "Confirmação de Consulta"
}
}
}
3. CheckAvailability — Verificar disponibilidade sem compromisso
Para agentes que comparam antes de executar.
json
{
"potentialAction": {
"@type": "CheckAction",
"target": {
"@type": "EntryPoint",
"urlTemplate": "https://www.lojax.com/api/agent/stock?sku={sku}",
"httpMethod": "GET"
}
}
}
A anatomia de um potentialAction de sucesso
Para um agente executar a ação, seis elementos precisam estar presentes e corretos:
| Elemento | O que é | Erro mais comum |
|---|---|---|
@type | Tipo de ação: BuyAction, ReserveAction, CheckAction | Usar tipo genérico Action sem especificar a intenção real. |
target / EntryPoint | O endpoint HTTP que recebe a requisição | Usar URL relativa, esquecer httpMethod, não declarar contentType. |
httpMethod | POST para ações que alteram estado; GET para consultas simples | Usar GET para ação destrutiva. |
contentType | application/json (recomendado) | Deixar em branco; o agente pode enviar formulário e ser rejeitado. |
description | Texto legível explicando a ação | Omitir; o agente pode interpretar mal a função. |
result (opcional) | O tipo de objeto retornado pela ação (Order, Reservation) | Não declarar; dificulta o agente interpretar a resposta. |
Exemplo completo de e-commerce pronto para ação
Abaixo, um JSON-LD realista de uma página de produto que um agente consegue ler, entender e comprar:
json
{
"@context": "https://schema.org",
"@type": "Product",
"name": "Kit Relação Honda CB 500",
"description": "Kit completo de relação para Honda CB 500 2019-2024. Inclui corrente, coroa e pinhão. Material de alta resistência, durabilidade de 30 mil km.",
"image": [
"https://www.rr14motoparts.com/img/kit-cb500-1.jpg",
"https://www.rr14motoparts.com/img/kit-cb500-2.jpg"
],
"sku": "KIT-CB500-2024",
"mpn": "KIT-CB500-2024",
"brand": {
"@type": "Brand",
"name": "Riffel"
},
"offers": {
"@type": "Offer",
"price": "329.90",
"priceCurrency": "BRL",
"availability": "https://schema.org/InStock",
"url": "https://www.rr14motoparts.com/kit-relacao-cb500",
"priceValidUntil": "2026-12-31",
"shippingDetails": {
"@type": "OfferShippingDetails",
"shippingRate": {
"@type": "MonetaryAmount",
"value": "0",
"currency": "BRL"
},
"deliveryTime": {
"@type": "ShippingDeliveryTime",
"handlingTime": { "minValue": 1, "maxValue": 1 },
"transitTime": { "minValue": 2, "maxValue": 5 }
}
}
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "4.8",
"reviewCount": "112"
},
"review": [
{
"@type": "Review",
"author": "João Silva",
"reviewBody": "Excelente qualidade. Superou as expectativas. Instalação tranquila."
}
],
"potentialAction": {
"@type": "BuyAction",
"target": {
"@type": "EntryPoint",
"urlTemplate": "https://www.rr14motoparts.com/api/agent/cart/add",
"httpMethod": "POST",
"contentType": "application/json"
},
"description": "Adiciona o Kit Relação ao carrinho. Requer SKU e quantidade no corpo da requisição.",
"result": {
"@type": "Order",
"name": "Pedido confirmado"
},
"additionalProperty": {
"@type": "PropertyValue",
"name": "requiresHumanApproval",
"value": "true",
"description": "Pedidos acima de R$ 500 passam por aprovação humana antes da confirmação."
}
}
}
O que um agente extrai disso em milissegundos:
- Produto compatível com Honda CB 500 2019-2024.
- Preço R$ 329,90 com frete grátis.
- 4.8 estrelas em 112 avaliações.
- Disponível em estoque.
- Pode comprar via POST em endpoint específico.
- Compras acima de R$ 500 precisam de aprovação humana.
Tempo do agente: um único parse de JSON.
Tempo do humano que encontraria a mesma informação: 2 a 5 minutos navegando.
Entrada, ação e resultado: o ciclo completo
O Schema.org para ações cobre três momentos do que o agente precisa:
| Momento | Schema.org | Função no mundo real |
|---|---|---|
| 1. Descoberta | EntryPoint + urlTemplate | Onde bater para consultar ou executar |
| 2. Execução | BuyAction, ReserveAction, CheckAction | O que o agente pode fazer ali |
| 3. Validação | result + additionalProperty | O que esperar como resposta e quais restrições existem |
Se faltar qualquer um desses três, o agente pode interpretar mal ou abandonar a ação.
Os erros mais comuns em implementações de ação
1. Usar GET para ação que altera estado
Um endpoint de compra acessível via GET é um desastre de segurança e um convite a erro de cache. Sempre POST ou PUT.
2. Não declarar contentType
Se o agente não souber que o endpoint aceita JSON, ele pode enviar application/x-www-form-urlencoded e ser rejeitado.
3. URL relativa ou quebrada
Toda URL no JSON-LD deve ser absoluta e funcional. O agente não “navega” pelo domínio. Ele faz uma requisição HTTP direta.
4. Ignorar o campo description e result
Sem descrição, o agente precisa inferir a função pela URL. Sem result, ele não sabe o que esperar de retorno e pode interpretar falhas como sucesso.
5. Esquecer do additionalProperty
Campos como requiresHumanApproval, maxOrderValue, availablePaymentMethods são metadados de governança que evitam ações indesejadas.
Além do e-commerce: ações em serviços, IoT e B2B
Negócios que não vendem produtos físicos também precisam implementar Schema.org para ações.
| Setor | Ação recomendada | Endpoint real |
|---|---|---|
| IoT / Sensores | CheckAction | GET /api/agent/sensors/{id}/reading |
| Fintech | PayAction ou TransferAction | POST /api/agent/payment/initiate |
| Jurídico | SearchAction customizado | POST /api/agent/jurisprudence/search |
| Educação | SubscribeAction | POST /api/agent/course/enroll |
| Saúde | ReserveAction | POST /api/agent/appointment/schedule |
O vocabulário Schema.org cobre dezenas de tipos de ação. O que falta na maioria das empresas não é tecnologia — é implementação.
Conclusão: o rich snippet virou commodity. A ação virou diferencial.
A marcação de dados estruturados tradicional trouxe visibilidade para a era dos buscadores. Mas a era dos agentes exige uma nova camada: a de execução.
BuyAction, ReserveAction e CheckAction não fazem seu site ganhar uma estrelinha a mais no Google. Fazem seu site ser o escolhido quando uma IA decide comprar.
O mercado de SEO brasileiro ainda está focado em meta tags e CTR. Enquanto isso, quem implementar Schema.org para ações agora se posiciona como o backend preferido dos agentes — com receita recorrente e ticket médio maior.
Seu Schema.org está pronto para a era das ações ou parou nos rich snippets?
O Diagnóstico Agent Readiness audita seus dados estruturados, valida endpoints, simula a compra com agente real e entrega um plano de ação priorizado. Em 7 dias você sabe se está pronto para vender — ou apenas para aparecer.
