Recursos

Relatos de agentes

Agentes e apps podem relatar uma espera que o usuário acabou de ter. Os relatos cobrem lugares sem espera publicada ao vivo, sempre aparecem como relatados e nunca são aceitos para pronto-socorro ou pronto atendimento.

O que é

POST /v1/places/{id}/reports e a ferramenta report_wait guardam uma espera que alguém realmente viveu. Os relatos ficam separados das esperas publicadas: têm seu próprio nível, agent, e nunca se misturam a um número oficial ou publicado pelo lugar.

Como relatar

Envie os minutos que o usuário esperou, logo depois da visita. Um relato precisa de uma chave de API e conta como uma chamada.

• wait_min: minutos, de 0 a 600. Obrigatório.
• observed_at: quando o usuário teve a espera, ISO 8601 com fuso, nas últimas 2 horas. Padrão: agora.
• kind: in_line enquanto ainda está na fila (a espera até agora), ou done para a espera inteira, que acabou de terminar.

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"}'

Um relato guardado responde 201 com seu report.id e shown. Quando não é mostrado, reason diz por quê: needs_more_reports, official_wait, closed, too_old ou out_of_range.

A ferramenta MCP

report_wait recebe os mesmos campos mais o id do lugar. É a única ferramenta MCP que escreve, então suas anotações dizem que ela não é só de leitura.

Quando os relatos aparecem

• Só quando o lugar não tem uma espera oficial ou publicada pelo lugar que possa ser usada e não está fechado. Uma espera publicada ao vivo sempre vence; o relato fica no histórico.
• Só quando pelo menos 2 pessoas diferentes relataram ou confirmaram nos últimos 45 minutos, ou uma pessoa de confiança relatou (outras confirmaram os relatos anteriores dela).
• A espera mostrada é a mediana do último relato de cada pessoa. Ela deixa de aparecer quando restam menos de 2 pessoas na janela.

Como são identificados

Uma espera relatada tem now.tier: "agent", now.basis: "reported" e now.source.name: "people", com seu próprio now.source.short. O resumo diz que pessoas a relataram (“reported by 2 people”) e que o lugar não a publicou.

Minutos relatados nunca são comparados com publicados: uma lista com os dois avisa, e instead nunca oferece um como mais curto que o outro.

Nunca para pronto-socorro ou pronto atendimento

Um relato ali é recusado com 422 reports_not_accepted, e nada é guardado.

Limites e privacidade

• Chamadas sem chave recebem 401 key_required; elas não contam.
• Um relato por relator e lugar a cada 30 minutos (429 report_too_soon, com Retry-After).
• 200 relatos por relator por dia (429 report_limit, até a meia-noite UTC).
• Com um relato, só o id da chave é guardado. Não envie nomes, telefones nem outros dados pessoais.

Parceiros de relatos, como um serviço por SMS que relata por muitas pessoas com uma só chave, podem enviar reporter: um hash estável de mão única de cada pessoa, nunca um telefone ou e-mail sem tratamento. O Waity configura as chaves de parceiro; o reporter de qualquer outra chave é ignorado.

No histórico

Os relatos ficam no histórico com tier=agent: cada relato em raw, e números por hora ou por dia calculados como para as esperas publicadas.

Relacionado

Como ler uma resposta explica cada campo de now, e cada campo da rota de relatos está na Referência da API.