Pós-venda com aprovação
Consulta pedido, rastreio e nota pela API da loja, explica a política pela base — e só executa troca ou cancelamento depois que uma pessoa aprova.
Atualizado em 01 de set. de 2026
Pós-venda é onde o agente para de responder e começa a mexer no seu sistema: trocar, devolver, cancelar, estornar. É também onde um erro custa dinheiro de verdade.
O desenho aqui separa o que é seguro do que não é. Consultar pedido, rastreio e nota: livre. Trocar ou cancelar: só depois de uma pessoa aprovar — e por um agente que só tem essas duas ferramentas na mão.
Duas camadas de trava: o slot e o tools_filter
O escopo dos cards é por slot: cada agente só enxerga o que está ligado a ele. Aqui o mesmo card Webhook serve os dois agentes (dois slots), então entra a segunda camada — o agente de leitura declara tools_filter só com as rotas de consulta, e o executor só com as de escrita. Se o atendimento enxergasse solicitar_troca, a pausa de aprovação viraria enfeite.
Como importar
Na plataforma: Agents → Importar, escolha o arquivo baixado. Ele entra como um rascunho novo (nada existente é alterado), com ids de observabilidade renovados. Depois preencha o que é do seu ambiente — credenciais, URLs e bases de conhecimento — e publique.
orders-desk.hinow-agent.jsonjson
{
"format": "hinow.agent",
"version": 1,
"exported_at": "2026-09-01T00:00:00Z",
"credentials_included": false,
"agent": {
"name": "Pós-venda com aprovação",
"description": "Consulta pedido, rastreio e nota pela API da loja; explica a política pela base; e só executa troca ou cancelamento depois que uma pessoa aprova.",
"avatar": null,
"model": null,
"system_prompt": null,
"config": {},
"tools": null,
"workflow": {
"nodes": [
{
"id": "start",
"type": "start",
"position": {
"x": 300,
"y": 0
},
"data": {
"label": "Início",
"variables": [
{
"name": "customer_id",
"type": "input",
"required": true,
"description": "Identificador da conta do cliente, vindo da sua aplicação."
}
]
}
},
{
"id": "agent-read",
"type": "agent",
"position": {
"x": 285,
"y": 150
},
"data": {
"name": "posvenda",
"model": "hinow/himax",
"system_prompt": "Você é o pós-venda da Loja Aurora. Fala com quem já comprou.\n\nO CLIENTE DESTA CONVERSA\nA conta é {{customer_id}}. Use sempre esse valor nas ferramentas.\n\nO QUE VOCÊ FAZ\n- Consulta pedido, rastreio e segunda via de nota — sempre pelo sistema, nunca de memória.\n- Explica a política de trocas e devoluções pela base de conhecimento: prazos, o que pode e o que não pode.\n- Quando o cliente quer MESMO trocar, devolver ou cancelar, você NÃO executa. Você monta o pedido: diga em uma frase o que será feito, com número do pedido, item e motivo, e encaminhe para aprovação.\n\nCOMO VOCÊ FALA\nDireto e gentil. Cliente de pós-venda costuma estar contrariado: reconheça o problema antes de explicar regra.\n\nO QUE VOCÊ NUNCA FAZ\n- Nunca promete estorno, prazo ou isenção que a política não dá.\n- Nunca pede dados de cartão, senha ou documento. Se vierem, peça para não repetir.\n- Nunca diz que uma troca foi feita — quem executa é a etapa seguinte, depois da aprovação.",
"config": {
"temperature": 0.3,
"tools_filter": [
"consultar_pedido",
"listar_pedidos",
"rastrear_entrega",
"segunda_via_nota",
"rag_search"
]
}
}
},
{
"id": "appr-1",
"type": "user_approval",
"position": {
"x": 265,
"y": 320
},
"data": {
"name": "Aprovar a solicitação",
"approval_message": "Confirma executar a solicitação acima no sistema da loja?",
"approval_options": [
"Aprovar",
"Rejeitar"
]
}
},
{
"id": "agent-write",
"type": "agent",
"position": {
"x": 75,
"y": 490
},
"data": {
"name": "executor",
"model": "hinow/himax",
"system_prompt": "A solicitação foi APROVADA. Execute agora, uma única vez, a ação combinada (troca, devolução ou cancelamento) com as ferramentas de escrita, usando exatamente os dados já confirmados na conversa.\n\nDepois de a ferramenta retornar sucesso, confirme ao cliente com o número do protocolo e o próximo passo real. Se a ferramenta falhar, diga com honestidade o que aconteceu e ofereça abrir um chamado — não tente de novo mais de uma vez.",
"config": {
"temperature": 0.2,
"tools_filter": [
"solicitar_troca",
"cancelar_pedido"
]
}
}
},
{
"id": "agent-no",
"type": "agent",
"position": {
"x": 470,
"y": 490
},
"data": {
"name": "revisor",
"model": "hinow/himax",
"system_prompt": "A solicitação foi REJEITADA. Nada foi executado. Diga isso com clareza, sem drama, e pergunte o que o cliente quer ajustar — outro item, outro motivo, ou falar com uma pessoa.",
"config": {
"temperature": 0.4,
"tools_filter": []
}
}
},
{
"id": "rag-1",
"type": "rag_search",
"position": {
"x": 590,
"y": 80
},
"data": {
"label": "Política de trocas",
"config": {
"rag_ids": [],
"top_k": 4,
"min_score": 0.35
}
}
},
{
"id": "hook-1",
"type": "webhook",
"position": {
"x": 590,
"y": 225
},
"data": {
"label": "ERP da loja",
"config": {
"name": "API da loja",
"baseUrl": "https://api.suaempresa.com/store/v2",
"timeout": 20000,
"auth": {
"type": "api_key",
"apiKey": "COLE_SUA_CHAVE_AQUI",
"apiKeyName": "X-API-Key",
"apiKeyLocation": "header"
},
"defaultHeaders": {
"X-Origem": "agente-atendimento"
},
"retryOnError": true,
"maxRetries": 2,
"routes": [
{
"id": "r-consultar_pedido",
"name": "consultar_pedido",
"method": "GET",
"path": "/orders/{{order_id}}",
"description": "Traz status, itens, valores e datas de um pedido.",
"whenToUse": "Sempre que o cliente citar um número de pedido ou perguntar sobre uma compra.",
"responseDescription": "Status, data da compra, itens com preço, forma de pagamento e previsão de entrega.",
"parameters": [
{
"name": "order_id",
"type": "string",
"required": true,
"description": "Número do pedido",
"howToObtain": "O cliente informa, ou vem de listar_pedidos",
"example": "AUR-77120"
},
{
"name": "customer_id",
"type": "string",
"required": true,
"description": "Identificador da conta",
"howToObtain": "É o {{customer_id}} desta conversa",
"example": "cli_5521"
}
],
"enabled": true,
"queryParams": {
"customer_id": "{{customer_id}}"
}
},
{
"id": "r-listar_pedidos",
"name": "listar_pedidos",
"method": "GET",
"path": "/orders",
"description": "Lista os pedidos recentes do cliente.",
"whenToUse": "Quando o cliente não sabe o número do pedido, ou fala 'minha última compra'.",
"responseDescription": "Lista de pedidos com número, data, valor e status.",
"parameters": [
{
"name": "customer_id",
"type": "string",
"required": true,
"description": "Identificador da conta",
"howToObtain": "É o {{customer_id}} desta conversa",
"example": "cli_5521"
}
],
"enabled": true,
"queryParams": {
"customer_id": "{{customer_id}}",
"limit": "5"
}
},
{
"id": "r-rastrear_entrega",
"name": "rastrear_entrega",
"method": "GET",
"path": "/orders/{{order_id}}/tracking",
"description": "Traz o rastreio da entrega: transportadora, código e último evento.",
"whenToUse": "Quando a pergunta é sobre onde está o pedido, atraso ou previsão de chegada.",
"responseDescription": "Transportadora, código de rastreio, último evento com data e previsão.",
"parameters": [
{
"name": "order_id",
"type": "string",
"required": true,
"description": "Número do pedido",
"howToObtain": "Vem de consultar_pedido",
"example": "AUR-77120"
}
],
"enabled": true
},
{
"id": "r-segunda_via_nota",
"name": "segunda_via_nota",
"method": "GET",
"path": "/orders/{{order_id}}/invoice",
"description": "Gera o link da segunda via da nota fiscal.",
"whenToUse": "Quando o cliente pede nota, cupom ou comprovante da compra.",
"responseDescription": "Link para download da nota, válido por tempo limitado.",
"parameters": [
{
"name": "order_id",
"type": "string",
"required": true,
"description": "Número do pedido",
"howToObtain": "Vem de consultar_pedido",
"example": "AUR-77120"
}
],
"enabled": true
},
{
"id": "r-solicitar_troca",
"name": "solicitar_troca",
"method": "POST",
"path": "/returns",
"description": "Registra uma solicitação de troca ou devolução e gera a etiqueta de postagem.",
"whenToUse": "SOMENTE na etapa posterior à aprovação humana. Nunca chame durante o atendimento.",
"responseDescription": "Protocolo da solicitação, prazo e o link da etiqueta de postagem.",
"parameters": [
{
"name": "order_id",
"type": "string",
"required": true,
"description": "Pedido relacionado",
"howToObtain": "Vem de consultar_pedido",
"example": "AUR-77120"
},
{
"name": "item_sku",
"type": "string",
"required": true,
"description": "SKU do item a trocar/devolver",
"howToObtain": "Vem dos itens de consultar_pedido",
"example": "CAM-AZ-M"
},
{
"name": "motivo",
"type": "string",
"required": true,
"description": "Motivo em uma frase, nas palavras do cliente"
},
{
"name": "tipo",
"type": "string",
"required": true,
"description": "troca ou devolucao",
"howToObtain": "O que o cliente pediu; na dúvida, pergunte",
"example": "troca"
},
{
"name": "customer_id",
"type": "string",
"required": true,
"description": "Identificador da conta",
"howToObtain": "É o {{customer_id}} desta conversa",
"example": "cli_5521"
}
],
"enabled": true,
"bodyTemplate": "{\"customer_id\": \"{{customer_id}}\", \"order_id\": \"{{order_id}}\", \"item_sku\": \"{{item_sku}}\", \"motivo\": \"{{motivo}}\", \"tipo\": \"{{tipo}}\"}"
},
{
"id": "r-cancelar_pedido",
"name": "cancelar_pedido",
"method": "POST",
"path": "/orders/{{order_id}}/cancel",
"description": "Cancela um pedido que ainda não foi despachado.",
"whenToUse": "SOMENTE na etapa posterior à aprovação humana.",
"responseDescription": "Confirmação do cancelamento e prazo de estorno.",
"parameters": [
{
"name": "order_id",
"type": "string",
"required": true,
"description": "Número do pedido",
"howToObtain": "Vem de consultar_pedido",
"example": "AUR-77120"
},
{
"name": "motivo",
"type": "string",
"required": true,
"description": "Motivo do cancelamento"
}
],
"enabled": true,
"bodyTemplate": "{\"motivo\": \"{{motivo}}\"}"
}
]
}
}
},
{
"id": "end-1",
"type": "end",
"position": {
"x": 305,
"y": 660
},
"data": {
"label": "Fim",
"status": "success"
}
}
],
"edges": [
{
"id": "e-start-agent-read-d",
"source": "start",
"target": "agent-read"
},
{
"id": "e-rag-1-agent-read-slot-1",
"source": "rag-1",
"target": "agent-read",
"targetHandle": "slot-1"
},
{
"id": "e-hook-1-agent-read-tool",
"source": "hook-1",
"target": "agent-read",
"sourceHandle": "tool",
"targetHandle": "slot-2"
},
{
"id": "e-agent-read-appr-1-d",
"source": "agent-read",
"target": "appr-1"
},
{
"id": "e-appr-1-agent-write-approved",
"source": "appr-1",
"target": "agent-write",
"sourceHandle": "approved"
},
{
"id": "e-appr-1-agent-no-rejected",
"source": "appr-1",
"target": "agent-no",
"sourceHandle": "rejected"
},
{
"id": "e-hook-1-agent-write-tool",
"source": "hook-1",
"target": "agent-write",
"sourceHandle": "tool",
"targetHandle": "slot-1"
},
{
"id": "e-agent-write-end-1-d",
"source": "agent-write",
"target": "end-1"
},
{
"id": "e-agent-no-end-1-d",
"source": "agent-no",
"target": "end-1"
}
]
}
}
}| Card | Por que está aqui | O que faz |
|---|---|---|
**Agent posvenda** | Conversa e apura. | Consulta pedido/rastreio/nota e explica a política. tools_filter com as 4 rotas de leitura + rag_search. **Não** tem como executar troca. |
| **Conhecimento (RAG)** | A política escrita. | Prazos, o que pode e o que não pode. Regra muda com frequência e não deve virar prompt. |
| **Webhook** (6 rotas) | O ERP da loja. | Autenticação api_key em header (X-API-Key) + defaultHeaders marcando a origem — útil no log do seu ERP. |
| **Aprovação do Usuário** | A trava. | Pausa o fluxo com o resumo do que vai ser feito. Retoma na próxima mensagem do mesmo thread. |
**Agent executor** | Executa uma vez só. | tools_filter: ["solicitar_troca", "cancelar_pedido"] — nada além disso. temperature: 0.2. |
**Agent revisor** | Trata o "não". | tools_filter: [] — literalmente sem ferramentas. Só conversa e pergunta o que ajustar. |
| Rota | Método | Quem enxerga |
|---|---|---|
listar_pedidos | GET + query | Atendimento — quando o cliente não sabe o número. |
consultar_pedido | GET + path + query | Atendimento — itens, valores, status. |
rastrear_entrega | GET + path | Atendimento — onde está, previsão. |
segunda_via_nota | GET + path | Atendimento — link da nota. |
solicitar_troca | POST + body | **Só o executor**, depois da aprovação. |
cancelar_pedido | POST + path + body | **Só o executor**, depois da aprovação. |
Este fluxo usa o segundo tipo de autenticação mais comum em ERP e e-commerce — a chave em header:
auth do cardjson
"auth": {
"type": "api_key",
"apiKey": "COLE_SUA_CHAVE_AQUI",
"apiKeyName": "X-API-Key",
"apiKeyLocation": "header"
}Trocando apiKeyLocation para "query", a mesma chave vai como ?X-API-Key=... — o que algumas APIs antigas exigem. Em qualquer um dos casos o valor não passa pelo modelo: entra direto na chamada HTTP.
- Aprovação por quem decide, não pelo cliente: hoje quem aprova é quem está na conversa. Para aprovação interna, dispare a notificação ao supervisor por uma rota do próprio Webhook antes da pausa e deixe a resposta voltar pelo mesmo thread.
- Limite de alçada: peça o valor no resumo e escreva no prompt do atendimento que acima de X a solicitação vai para um segundo nível.
- Estorno: é mais uma rota de escrita no
tools_filterdo executor — nunca no do atendimento.
Todos os fluxos prontos
Outros agents completos para importar e adaptar.
Esta página foi útil?