Guia rápido

Acesse a página Obter API Keys para gerar uma chave para sua comunidade ou marca. Selecione as permissões necessárias para sua integração e copie a chave — ela começa com hoa_live_.

Use o endpoint de disponibilidade para ver quais horários estão disponíveis em um espaço para uma data específica. Você precisa do spaceId, que pode ser encontrado na URL ao visualizar um espaço no hoastnow.

curl "https://www.hoastnow.com/api/v1/spaces/42/availability?date=2026-04-15" \
  -H "Authorization: Bearer $HOASTNOW_API_KEY"

A resposta descreve a janela de reserva da comunidade e lista cada hora disponível dentro dela. O campo durationHours indica quanto tempo cada evento dura — é definido pela comunidade e não pode ser alterado ao reservar.

{
  "spaceId": 42,
  "spaceName": "Sunset Clubhouse",
  "date": "2026-04-15",
  "windowStart": 9,
  "windowEnd": 21,
  "durationHours": 3,
  "timeSlots": [
    { "hour": 9,  "label": "9:00 AM",  "isAvailable": true  },
    { "hour": 10, "label": "10:00 AM", "isAvailable": true  },
    { "hour": 11, "label": "11:00 AM", "isAvailable": false }
  ]
}

Um slot com isAvailable: false já está reservado. Ao selecionar um horário de início, certifique-se de que startHour + durationHours esteja dentro de windowEnd. O hoastnow permitirá a reserva mesmo que o evento se estenda ligeiramente além da janela, mas indicará o tempo de uso reduzido.

Busque disponibilidade para o espaço e a data que deseja reservar. Analise o array timeSlots para encontrar quais horários estão disponíveis.

curl "https://www.hoastnow.com/api/v1/spaces/42/availability?date=2026-04-15" \
  -H "Authorization: Bearer $HOASTNOW_API_KEY"

Passe o spaceId, o startTime (data) e o startHour do slot selecionado. Inclua uma message opcional para a comunidade. Trate o caso 422 SlotUnavailable — outra reserva pode ter ocupado o slot entre sua verificação e esta chamada.

curl -X POST https://www.hoastnow.com/api/v1/bookings \
  -H "Authorization: Bearer $HOASTNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "spaceId": 42,
    "startTime": "2026-04-15",
    "startHour": 10,
    "message": "Brand activation event — approximately 50 attendees."
  }'

Um POST /bookings bem-sucedido retorna 201 Created com a reserva em status Pendente. A comunidade deve aprovar antes de confirmar a reserva. Armazene o id para consultar atualizações de status, ou configure um webhook para ser notificado quando o status mudar.

Use startDate e endDate para limitar a resposta a uma janela relevante. Para um job de sincronização diário, passe a data de hoje como startDate para buscar apenas as próximas reservas.

curl "https://www.hoastnow.com/api/v1/bookings?startDate=2026-04-01&status=Approved" \
  -H "Authorization: Bearer $HOASTNOW_API_KEY"

Mapeie os status do hoastnow para os do seu sistema interno — por exemplo, um app de calendário pode exibir apenas reservas Aprovadas e Pendentes.

# Filter to approved bookings only
curl "https://www.hoastnow.com/api/v1/bookings?startDate=2026-04-01&status=Approved" \
  -H "Authorization: Bearer $HOASTNOW_API_KEY"

A API atual não pagina — todas as reservas correspondentes são retornadas em uma única resposta. Porém, use filtros de intervalo de datas para limitar o tamanho da resposta e evitar payloads grandes conforme o volume de reservas crescer.

Registre sua URL HTTPS e selecione os eventos para se inscrever usando uma soma de máscara de bits: BookingRequested=1, BookingApproved=2, BookingCancelled=4, ReviewPosted=8. Use 15 para todos os eventos.

curl -X POST https://www.hoastnow.com/api/v1/webhooks \
  -H "Authorization: Bearer $HOASTNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/hooks/hoastnow",
    "events": 15
  }'

{
  "id": "wh_abc123",
  "url": "https://your-server.com/hooks/hoastnow",
  "events": 15,
  "signingSecret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "createdAt": "2026-04-01T10:00:00Z"
}

Cada entrega inclui um cabeçalho X-Hoastnow-Signature com um resumo HMAC-SHA256 do corpo bruto da requisição. Sempre verifique antes de processar o payload — rejeite requisições que falhem com 401.

# Manually compute the expected signature for testing:
echo -n '{"event":"BookingApproved",...}' \
  | openssl dgst -sha256 -hmac "$HOASTNOW_WEBHOOK_SECRET"

Despache com base no campo event. Cada payload inclui um timestamp e um objeto data com os detalhes relevantes.

# Webhook payloads look like this:
# {
#   "event": "BookingApproved",
#   "timestamp": "2026-04-15T10:30:00Z",
#   "data": {
#     "bookingId": 1002, "spaceId": 42, "spaceName": "Sunset Clubhouse",
#     "date": "2026-04-15", "startHour": 10, "endHour": 13,
#     "status": "Approved", "totalPrice": 345.00
#   }
# }

• Idempotência: o hoastnow pode retentar entregas em caso de respostas não 2xx ou timeouts. Use bookingId como chave de idempotência para evitar processar o mesmo evento duas vezes.
• Responda rapidamente: Retorne 200 em até 5 segundos. Coloque envios de e-mail, gravações no banco de dados e chamadas a terceiros em uma fila de background.
• Sempre verifique assinaturas: Nunca pule a verificação, nem em desenvolvimento. Use ngrok para expor um endpoint local durante os testes.
• Registre os payloads brutos: Armazene o JSON bruto antes de processar para poder reproduzir eventos se seu handler tiver um bug.
• Trate eventos desconhecidos com elegância: Retorne 200 para tipos de evento que não reconhecer — novos tipos podem ser adicionados no futuro.