Especificación de conversión para reservas en restaurantes

Objetivo

Nuestro objetivo es que ChatGPT pueda invocar directamente los complementos de los socios cuando el usuario tiene una intención clara, como reservar una mesa en un restaurante.

Una vez que los socios nos proporcionan un feed de datos para las búsquedas, podemos conectar sus servidores MCP para ejecutar acciones de conversión en la etapa final del proceso. Para ello, los complementos de los socios deben seguir un contrato estándar que define el nombre del widget, el nombre de la herramienta y los datos de entrada de la herramienta.

Si quieres crear un complemento que cumpla con esta especificación, solicita acceso mediante el formulario de ChatGPT para comercios.

Experiencia de usuario

Cuando los usuarios buscan restaurantes cercanos, tanto la ficha del restaurante como la barra lateral incluyen un botón Reservar que permite abrir la interfaz del proveedor que gestiona las reservas del restaurante.

Botón Reservar en la interfaz del restaurante:

Ventana modal de reservas que se abre desde ese botón:

Requisitos actuales del contrato

La integración actual de reservas solo requiere lo siguiente:

• Nombre del widget: ui://widget/restaurant-reservation.html
• Nombre de la herramienta: restaurant_reservation

restaurant_reservation debe establecer el siguiente valor:

_meta.ui.resourceUri = "ui://widget/restaurant-reservation.html";

Toda herramienta que se invoque directamente desde un widget debe establecer el siguiente valor:

_meta["openai/widgetAccessible"] = true;

Datos de entrada de restaurant_reservation

Datos mínimos que se envían siempre:

{
  "restaurant_id": "string"
}

También podríamos enviar los siguientes datos. Puedes usarlos para el renderizado optimista de la ventana modal (por ejemplo, para evitar que se muestre un esquema provisional o un indicador de carga durante la hidratación de los datos):

{
  "restaurant_name": "string",
  "restaurant_image": "string",
  "restaurant_address": {
    "address": "string",
    "city": "string",
    "state": "string",
    "zipcode": "string",
    "country": "string"
  }
}

Feed de datos requerido para integrar la búsqueda

Para que el botón Reservar dirija al usuario al proveedor correspondiente, incorporamos un feed con datos de los comercios que nos proporcionan los socios.

Objetivo y alcance

El contrato del feed define lo siguiente:

• Los datos mínimos de cada comercio para identificar coincidencias y ordenar los resultados por relevancia.
• Una API para listar los comercios con paginación.
• Un mecanismo para detectar cambios y evitar descargas completas innecesarias.

Registro de un comercio (campos mínimos obligatorios)

Cada objeto Business debe incluir lo siguiente:

• id (string): identificador estable y único dentro del conjunto de comercios del proveedor.
• name (string)
• address (object o string con formato)
• location (object con latitud y longitud)
• phone_number (string, preferiblemente en formato E.164)
• website_url (string, URL)
• platform_url (string, URL de la ficha canónica del comercio en tu plataforma)

Estructura mínima recomendada:

{
  "id": "biz_123",
  "name": "Acme Coffee",
  "address": {
    "line1": "123 Market St",
    "line2": "Suite 5",
    "locality": "San Francisco",
    "region": "CA",
    "postal_code": "94105",
    "country": "US",
    "formatted": "123 Market St, Suite 5, San Francisco, CA 94105, US"
  },
  "location": {
    "latitude": 37.793,
    "longitude": -122.396
  },
  "phone_number": "+14155551234",
  "website_url": "https://acmecoffee.example",
  "platform_url": "https://provider.example/biz/biz_123"
}

Si no dispones de los componentes de la dirección en campos separados, address puede ser una sola cadena con formato. El formato debe ser uniforme y la dirección debe ser fácil de leer.

Punto de acceso para listar comercios con paginación

Ejemplo de punto de acceso:

• GET /v1/businesses

Parámetros de consulta:

• Paginación: elige un solo método
• page + page_size
• offset + limit
• o next_page_token (token opaco, preferible si se admite)
• changes_token (string, opcional): indica si los datos cambiaron desde el último punto de control de la sincronización.

La respuesta debe incluir lo siguiente:

• checksum (boolean): indica si hubo cambios desde el punto de control identificado por el changes_token proporcionado. Si no se proporcionó ningún token, el valor debe ser true.
• businesses (Business[]): datos de los comercios de la página actual.
• Metadatos de paginación según el método elegido:
• page, page_size, total_pages (opcional), o
• offset, limit, total (opcional), o
• next_page_token (string | null)

Ejemplo de solicitud y respuesta

Solicitud:

GET /v1/businesses?page=1&page_size=2&changes_token=sync_2026_03_10

Respuesta:

{
  "checksum": true,
  "page": 1,
  "page_size": 2,
  "total_pages": 120,
  "businesses": [
    {
      "id": "biz_123",
      "name": "Acme Coffee",
      "address": {
        "line1": "123 Market St",
        "locality": "San Francisco",
        "region": "CA",
        "postal_code": "94105",
        "country": "US",
        "formatted": "123 Market St, San Francisco, CA 94105, US"
      },
      "location": {
        "latitude": 37.793,
        "longitude": -122.396
      },
      "phone_number": "+14155551234",
      "website_url": "https://acmecoffee.example",
      "platform_url": "https://provider.example/biz/biz_123"
    },
    {
      "id": "biz_124",
      "name": "Golden Diner",
      "address": "200 Howard St, San Francisco, CA 94105, US",
      "location": {
        "latitude": 37.789,
        "longitude": -122.391
      },
      "phone_number": "+14155559876",
      "website_url": "https://goldendiner.example",
      "platform_url": "https://provider.example/biz/biz_124"
    }
  ]
}

Cómo usamos el feed en las búsquedas

Usamos el feed de comercios como índice de búsqueda. En cada consulta, buscamos coincidencias aproximadas por nombre y por ubicación o dirección. Luego ordenamos los resultados por relevancia y eliminamos los duplicados según la similitud entre los nombres y las direcciones. También usamos la ubicación, el número de teléfono y la URL como señales adicionales.

Funciones adicionales recomendadas (opcionales por ahora)

Para que el usuario pueda completar todo el proceso de reserva en el chat, recomendamos agregar lo siguiente:

• refresh_availability
• make_reservation
• reservation_confirmation