Aller au contenu

Chegada de um visitante (público, com token)

POST/api/attendance/kiosk/check-in

Auth
Jeton requis
Clé d’API:
attendance:write
Les descriptions des endpoints viennent directement de la spécification de l’API et sont en portugais pour l’instant. L’interface autour est traduite.

Abre a visita do visitante (método `KIOSK`). **Dois caminhos, exatamente um:** `hostMemberId` (visitante sem cadastro prévio) ou `invitationId` (convidado cadastrado, vindo de `GET /api/attendance/kiosk/expected`; vale o 400 com `errors` se vierem os dois ou nenhum). Com `invitationId`, o servidor confere que o cadastro é desta comunidade e deste space (404), que o `guestName` digitado começa o nome cadastrado (duas palavras de 3+ letras; senão 400), e que está esperado hoje (409 se cancelado, já chegado por outro meio ou de outro dia); a chegada marca o cadastro (`ARRIVED`) sobre a visita, sem duplicar, usa o nome cadastrado e avisa o anfitrião (`hostNotified`). Tocar de novo no mesmo quiosque devolve 200 com `alreadyCheckedIn: true`. `guestName` é obrigatório; `guestCompany` e `guestPhone` valem conforme `guestFields` da sessão (`required` exige, `off` ignora). `hostMemberId` precisa ser um membro da comunidade **do token** com acesso ao space (senão 404). O corpo nunca aceita `communityId` nem `spaceId`. **Idempotente** por nome normalizado + anfitrião + space: o segundo pedido devolve a visita aberta (`200`, `alreadyCheckedIn: true`). Cria: `201`. Se o space tem `notifyHost`, o e-mail ao anfitrião vai para a fila (nunca na requisição), com teto de 10 por hora por anfitrião; passando do teto a visita é registrada e o e-mail não sai. Limite: 10 por minuto por token.

En-têtes

NomTypeDescription
X-Kiosk-TokenobligatoirestringToken do quiosque. A comunidade e o space saem dele; nunca vão no corpo nem no caminho.

Corps de la requête application/json

NomTypeDescription
guestNameobligatoirestringmax 100
guestCompanyfacultatifstringmax 100
guestPhonefacultatifstringmax 30
hostMemberIdfacultatifstring (uuid)Anfitrião (caminho sem cadastro prévio). Exclusivo com `invitationId`.
invitationIdfacultatifstring (uuid)Convidado cadastrado (`expectedId`). Exclusivo com `hostMemberId`.

Réponses

StatutDescription
200Já havia visita aberta deste visitante com este anfitrião.
201Visita aberta.
400Requisição inválida — falha de validação.
401Token ausente, inválido ou revogado, ou space apagado.
403Autenticado, mas sem permissão para esta operação.
404Recurso não encontrado.
409Conflito com o estado atual do recurso.
429Limite de taxa (por token e por IP). Traz `Retry-After` (segundos) e `errors`.
500Erro interno do servidor.

Exemple curl

curl -X POST "https://api.memberfy.net/api/attendance/kiosk/check-in" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"guestName":"Maria Souza"}'