Funciones

Reportes de agentes

Los agentes y las apps pueden reportar una espera que su usuario acaba de tener. Los reportes cubren lugares sin una espera publicada en vivo, siempre se marcan como reportados y nunca se aceptan para urgencias ni atención urgente.

Qué es

POST /v1/places/{id}/reports y la herramienta report_wait guardan una espera que alguien vivió de verdad. Los reportes se guardan aparte de las esperas publicadas: tienen su propio nivel, agent, y nunca se mezclan con una cifra oficial o publicada por el lugar.

Cómo reportar

Envía los minutos que esperó el usuario, justo después de la visita. Un reporte necesita una clave de API y cuenta como una llamada.

• wait_min: minutos, de 0 a 600. Obligatorio.
• observed_at: cuándo tuvo el usuario la espera, ISO 8601 con desfase, dentro de las últimas 2 horas. Por defecto, ahora.
• kind: in_line mientras sigue en la fila (la espera hasta ahora), o done para la espera completa, recién terminada.

curl -X POST "https://api.waity.ai/v1/places/pl_nvk0wkb3ps/reports" \
  -H "X-Api-Key: $WAITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wait_min":25,"kind":"done"}'

Un reporte guardado responde 201 con su report.id y shown. Si no se muestra, reason dice por qué: needs_more_reports, official_wait, closed, too_old o out_of_range.

La herramienta MCP

report_wait recibe los mismos campos más el id del lugar. Es la única herramienta MCP que escribe, así que sus anotaciones dicen que no es de solo lectura.

Cuándo se muestran

• Solo cuando el lugar no tiene una espera oficial o publicada por el lugar que se pueda usar, y no está cerrado. Una espera publicada en vivo siempre gana; el reporte queda en el historial.
• Solo cuando al menos 2 personas distintas reportaron o confirmaron en los últimos 45 minutos, o una persona de confianza lo hizo (otras confirmaron sus reportes anteriores).
• La espera mostrada es la mediana del último reporte de cada persona. Deja de mostrarse cuando quedan menos de 2 personas en la ventana.

Cómo se marcan

Una espera reportada tiene now.tier: "agent", now.basis: "reported" y now.source.name: "people", con su propio now.source.short. Su resumen dice que la reportaron personas («reported by 2 people») y que el lugar no la publicó.

Los minutos reportados nunca se comparan con los publicados: una lista con ambos lo dice, y instead nunca ofrece uno como más corto que el otro.

Nunca para urgencias ni atención urgente

Un reporte allí se rechaza con 422 reports_not_accepted y no se guarda nada.

Límites y privacidad

• Las llamadas sin clave reciben 401 key_required; no cuentan.
• Un reporte por informante y lugar cada 30 minutos (429 report_too_soon, con Retry-After).
• 200 reportes por informante al día (429 report_limit, hasta la medianoche UTC).
• Con un reporte solo se guarda el id de la clave. No envíes nombres, teléfonos ni otros datos personales.

Los socios de reportes, como un servicio de mensajes de texto que reporta por muchas personas con una sola clave, pueden enviar reporter: un hash estable de un solo sentido de cada persona, nunca un teléfono o correo sin procesar. Waity configura las claves de socio; el reporter de cualquier otra clave se ignora.

En el historial

Los reportes están en el historial con tier=agent: cada reporte en raw, y cifras por hora o por día calculadas igual que para las esperas publicadas.

Relacionado

Cómo leer una respuesta explica cada campo de now, y cada campo de la ruta de reportes está en la Referencia de la API.