O número do pedido é suficiente?

Não. Configure pelo menos dois valores obrigatórios e confira os dois juntos no servidor. Não exponha uma consulta que permita enumerar pedidos.

A IA pode cancelar ou reembolsar um pedido com essa ferramenta?

Esta integração é para consultas GET somente para leitura. O endpoint não deve cancelar, reembolsar, confirmar pagamentos nem executar operações de processamento ou entrega.

Por que um JSON válido não retorna campos mapeados?

Confira os caminhos exatos da resposta e os tipos dos valores. Use order.status, não $.order.status, e mapeie valores escalares em vez de objetos.

Posso usar um túnel local ou um endpoint workers.dev?

Não use um túnel para contornar as restrições de host. Use um domínio HTTPS público e fixo sob seu controle; endpoints workers.dev precisam de um domínio personalizado permitido.

Guia de API para comerciantes

Permita que clientes consultem pedidos pela sua API

A Ouviro pode chamar sua API somente para leitura durante uma conversa. Seu servidor deve decidir se o número do pedido e o e-mail fornecidos autorizam o acesso àquele pedido.

Ouviro · Publicado 2026-10-07

1. Prepare uma consulta somente para leitura

Prepare uma conta de proprietário ou administrador, um canal de site e um endpoint que retorne JSON sem alterar pedidos, pagamentos ou processamento de entregas. Use dados fictícios: DEMO-1042 e ana@example.com.

Instalar o widget ou incorporar o painel administrativo não concede acesso aos pedidos. Esta integração de API personalizada não é um conector nativo de Shopify ou WooCommerce.

2. Use um host HTTPS público e fixo

Configure uma URL HTTPS absoluta na porta padrão. A Ouviro envia requisições GET e não segue redirecionamentos. Valores do visitante podem preencher parâmetros de caminho ou de consulta, nunca o host.

Localhost, endereços IP literais, hosts com formato privado, ouviro.com, workers.dev e pages.dev são recusados. Para uma API hospedada no Cloudflare Workers, configure seu próprio domínio público personalizado; não tente contornar as restrições de host.

3. Exija o número do pedido e o e-mail

Exija pelo menos order_id e email. Inclua os dois no modelo de URL, com email na query string. O exemplo permite 64 caracteres para order_id e 200 para email; nenhum parâmetro pode ultrapassar 200.

Seu servidor deve validar os dois juntos antes de retornar campos do pedido. As verificações de formato da Ouviro não comprovam a titularidade. Aplique seus próprios controles de autorização e prevenção de abuso.

4. Mantenha as credenciais no servidor

Configure o nome permitido do cabeçalho e o segredo da credencial de serviço nos ajustes da ferramenta. A Ouviro o adiciona no servidor. Nunca coloque o segredo no widget, HTML, URL ou arquivos de conhecimento.

Essa credencial autoriza quem chama a API; sua API ainda precisa conferir o número do pedido e o e-mail do visitante.

5. Configure a ferramenta para seu canal

Crie a ferramenta, escolha o canal e adapte esta definição. Configure um tempo limite entre 1 e 5 segundos.

Os hosts e dados de clientes do exemplo são fictícios. Forneça seu próprio endpoint e guarde o segredo separadamente; este exemplo não é um serviço de comércio em funcionamento.

Este JSON documenta os campos de configuração. Preencha-os no formulário do painel; ele não aceita colar o JSON inteiro. Os limites de comprimento fazem parte da definição da API e não podem ser editados nesse formulário.

{
  "name": "get_order",
  "description": "Look up order status and shipping details using the order number and the email used at checkout.",
  "urlTemplate": "https://api.example.com/verified-orders/{order_id}?email={email}",
  "params": [
    {
      "name": "order_id",
      "description": "The order number provided by the visitor.",
      "required": true,
      "pattern": null,
      "maxLength": 64
    },
    {
      "name": "email",
      "description": "The email used at checkout, provided by the visitor.",
      "required": true,
      "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$",
      "maxLength": 200
    }
  ],
  "responseMap": [
    {
      "path": "order.status",
      "label": "Order status"
    },
    {
      "path": "shipping.carrier",
      "label": "Carrier"
    },
    {
      "path": "shipping.eta",
      "label": "Estimated arrival"
    }
  ],
  "authHeaderName": "Authorization",
  "timeoutMs": 5000
}

JSON · Exemplo ilustrativo

{
  "order": {
    "status": "shipped"
  },
  "shipping": {
    "carrier": "Example Carrier",
    "eta": "3–5 business days"
  }
}

6. Mapeie apenas os campos necessários ao cliente

Use caminhos separados por pontos, como order.status ou order.shipment.status, sem adicionar $. no início. Eles devem corresponder ao JSON real do servidor.

Somente campos escalares mapeados chegam ao modelo que redige a resposta; campos ausentes e objetos não se tornam fatos. Exclua notas internas, endereços, credenciais de pagamento e registros de outros clientes.

Exemplo ilustrativo — Captura da ilustração do site em inglês, com dados fictícios. Não é o painel nem o resultado de um pedido real de um lojista.

7. Confira a primeira resposta válida

No painel, teste um pedido fictício com o e-mail correspondente. Confira a requisição, os campos e o status. Depois consulte o pedido no widget, fornecendo os dois valores.

Compare a resposta com a da API e revise o registro de chamadas de ferramentas da conversa. Um teste do endpoint sozinho não comprova o comportamento da conversa.

8. Teste recusas, pedidos ausentes e tempos limite

Teste um e-mail incorreto, um pedido desconhecido, um parâmetro ausente, JSON inválido e um endpoint lento. Um e-mail incorreto não deve revelar nenhum campo do pedido. Resultados de não encontrado, erros HTTP e tempos limite nunca devem virar detalhes inventados de envio ou pagamento.

Se a consulta falhar, peça a correção dos dados ou encaminhe ao atendimento humano. Um tempo limite não significa que o pedido não existe, foi cancelado ou está sem pagamento.

Para lojas virtuais com acesso aos dados dos pedidos Preços

Começar o teste grátis