Guía de API para comercios
Permite consultar el estado de pedidos mediante tu API
Ouviro puede llamar a tu API de solo lectura durante una conversación. Tu servidor debe decidir si el número de pedido y el correo proporcionados autorizan el acceso a ese pedido.
Ouviro · Publicado
1. Prepara una consulta de solo lectura
Prepara una cuenta de propietario o administrador, un canal web y un endpoint que devuelva JSON sin modificar pedidos, pagos ni la preparación o el envío. Usa datos ficticios: DEMO-1042 y ana@example.com.
Instalar el widget o integrar el panel de administración no concede acceso a pedidos. Esta integración API personalizada no es un conector nativo de Shopify o WooCommerce.
2. Utiliza un host HTTPS público y fijo
Configura una URL HTTPS absoluta con el puerto predeterminado. Ouviro envía solicitudes GET y no sigue redirecciones. Los valores del visitante pueden completar parámetros de ruta o consulta, nunca el host.
Se rechazan localhost, direcciones IP literales, hosts con apariencia privada, ouviro.com, workers.dev y pages.dev. Si alojas la API en Cloudflare Workers, configura tu propio dominio público personalizado; no intentes eludir estas restricciones.
3. Exige el número de pedido y el correo
Exige al menos order_id y email. Incluye ambos en la plantilla de URL, con email en la cadena de consulta. El ejemplo permite 64 caracteres para order_id y 200 para email; ningún parámetro puede superar 200.
Tu servidor debe validar los dos juntos antes de devolver campos del pedido. Las comprobaciones de formato de Ouviro no prueban la titularidad. Aplica tus propios controles de autorización y prevención de abusos.
4. Mantén las credenciales en el servidor
Configura el nombre permitido de la cabecera y el secreto de la credencial de servicio en los ajustes de la herramienta. Ouviro lo añade desde el servidor. Nunca pongas el secreto en el widget, HTML, URL ni archivos de conocimiento.
Esta credencial autoriza a quien llama a la API; tu API debe seguir comprobando el número de pedido y el correo del visitante.
5. Configura la herramienta para tu canal
Crea la herramienta, elige su canal y adapta esta definición. Configura un tiempo de espera de entre 1 y 5 segundos.
Los hosts y los datos de clientes del ejemplo son ficticios. Proporciona tu propio endpoint y guarda el secreto por separado; este ejemplo no es un servicio de comercio operativo.
Este JSON documenta los campos de configuración. Introdúcelos en el formulario del panel; no admite pegar todo el JSON. Los límites de longitud pertenecen a la definición de la API y no se pueden editar en ese formulario.
{
"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 · Ejemplo ilustrativo
{
"order": {
"status": "shipped"
},
"shipping": {
"carrier": "Example Carrier",
"eta": "3–5 business days"
}
}6. Mapea solo los campos necesarios para el cliente
Utiliza rutas separadas por puntos, como order.status u order.shipment.status, sin añadir $. al principio. Deben coincidir con el JSON real de tu servidor.
Solo los campos escalares mapeados llegan al modelo que redacta la respuesta; los campos ausentes y los objetos no se convierten en hechos. Excluye notas internas, direcciones, credenciales de pago y registros de otros clientes.
7. Comprueba la primera respuesta válida
Prueba en el panel un pedido ficticio y su correo correspondiente. Revisa la solicitud, los campos y el estado. Después consulta ese pedido en el widget, proporcionando ambos valores.
Compara la respuesta con la de tu API y revisa el registro de llamadas a herramientas de la conversación. Una prueba del endpoint no demuestra por sí sola el comportamiento de la conversación.
8. Prueba denegaciones, pedidos inexistentes y tiempos de espera
Prueba un correo incorrecto, un pedido desconocido, un parámetro ausente, JSON no válido y un endpoint lento. Un correo incorrecto no debe revelar ningún campo del pedido. Un resultado no encontrado, un error HTTP o un tiempo de espera agotado nunca deben transformarse en detalles inventados de envío o pago.
Si la consulta falla, pide corregir los datos o deriva a atención humana. Un tiempo de espera agotado no significa que el pedido no exista, esté cancelado o esté pendiente de pago.