Referência da API - Desenvolvedores hoastnow

Visão geral

Base URL https://www.hoastnow.com/api/v1

Content type application/json

Authentication Bearer token (Authorization header)

Códigos de status HTTP

Código	Significado
`200`	OK — request succeeded, response body contains the result
`201`	Created — resource created successfully (e.g. new booking)
`204`	No Content — request succeeded, no response body (e.g. DELETE)
`400`	Bad Request — missing or malformed request body / query parameter
`401`	Unauthorized — API key missing or invalid
`403`	Forbidden — key does not have the required permission for this endpoint
`404`	Not Found — resource does not exist or is not accessible to this key
`422`	Unprocessable Entity — business rule violation (e.g. slot no longer available)
`500`	Internal Server Error — unexpected server-side failure

Autenticação

A API do hoastnow suporta dois mecanismos de autenticação: OAuth 2.1 (recomendado para agentes de IA, integrações de marketplace e clientes dinâmicos) e API keys de longa duração (recomendado para integrações fixas servidor a servidor). Ambos usam o mesmo modelo de permissões — cada endpoint aplica os mesmos indicadores ApiPermissions independentemente do método de autenticação.

HTTP Header

Authorization: Bearer <token>

OAuth 2.1

OAuth 2.1 / OIDC é o caminho recomendado para qualquer cliente que autentica em nome de um usuário, se registra dinamicamente ou opera em um contexto de marketplace. O aplicativo web do hoastnow é o servidor de autorização; os tokens são JWTs validados pelo JWKS publicado.

PKCE (S256) is required on the authorization-code flow.
Refresh-token rotation on every use; refresh tokens are bound to the original client.
Dynamic Client Registration (RFC 7591) at /connect/register.
Resource indicators (RFC 8707) bind tokens to one audience — api or mcp.
JWT access tokens validated via JWKS — no introspection round-trip required.

Descoberta

Issuer https://www.hoastnow.com

OIDC config /.well-known/openid-configuration

JWKS /.well-known/jwks

MCP resource /.well-known/oauth-protected-resource/mcp

Endpoints

Caminho	Método	Finalidade
`/connect/authorize`	GET	Authorization-code entry point (browser redirect)
`/connect/token`	POST	Exchange auth code, refresh token, or client credentials for an access token
`/connect/register`	POST	Dynamic Client Registration (RFC 7591)
`/connect/userinfo`	GET	OIDC user claims for the bearer token
`/connect/revoke`	POST	Revoke an access or refresh token
`/connect/introspect`	POST	Inspect a token's active state and metadata
`/connect/logout`	GET / POST	End the user's session at the authorization server

Escopos

Escopo	Permissões concedidas
`openid`	Required for OIDC; identifies the user
`profile`, `email`	Standard OIDC claims for `userinfo`
`offline_access`	Issues a refresh token
`hoastnow.api.read`	ReadAvailability, ReadBookings, ReadReviews
`hoastnow.api.write`	WriteBookings
`hoastnow.api.webhooks`	Webhooks
`hoastnow.mcp`	MCP tool access (use with `resource=mcp`)

Indicadores de recurso são obrigatórios. Cada requisição de token deve incluir resource=api (REST) ou resource=mcp (servidor MCP). Um token emitido para um audience não pode ser usado no outro — uso cruzado é rejeitado pelos servidores de recursos.

Validade dos tokens

Token	Validade
Authorization code	5 minutes
Access token	60 minutes
Refresh token	30 days (rotates on use)

cURL — token exchange

curl -X POST https://www.hoastnow.com/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=$AUTH_CODE" \
  -d "client_id=$CLIENT_ID" \
  -d "code_verifier=$PKCE_VERIFIER" \
  -d "redirect_uri=https://your-app.com/callback" \
  -d "resource=api"

cURL — refresh token

curl -X POST https://www.hoastnow.com/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=$REFRESH_TOKEN" \
  -d "client_id=$CLIENT_ID" \
  -d "resource=api"

Calling the API

Authorization: Bearer <access_token>

API Keys

API keys de longa duração são ideais para integrações fixas servidor a servidor onde o sistema integrado já gerencia sua própria identidade. As chaves têm escopo para uma única Comunidade ou Marca no momento da emissão, não expiram até serem revogadas e usam o mesmo cabeçalho Authorization: Bearer do OAuth.

Escopos das chaves

Escopo	Descrição
Community	Emitida para uma comunidade. Acessa reservas e disponibilidade dos espaços pertencentes a essa comunidade.
Brand	Emitida para uma conta de marca. Pode criar solicitações de reserva e ler apenas suas próprias reservas.

Indicadores de permissão

Permissão	Valor	Descrição
`ReadAvailability`	1	Consultar horários disponíveis para espaços
`ReadBookings`	2	Listar reservas (com escopo por tipo de chave)
`WriteBookings`	4	Criar solicitações de reserva (apenas chaves de marca)
`ReadReviews`	8	Ler avaliações de comunidades e espaços
`Webhooks`	16	Registrar e gerenciar endpoints de webhook

API keys são aceitas apenas pela API REST. O servidor MCP requer OAuth 2.1 — consulte a página MCP para detalhes.

HTTP Header

Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx

cURL

curl https://www.hoastnow.com/api/v1/spaces/42/availability \
  -H "Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx" \
  -G --data-urlencode "date=2026-04-15"

Disponibilidade

GET /spaces/{spaceId}/availability ReadAvailability

Retorna os horários disponíveis para um espaço em uma data específica. A resposta inclui a janela de reserva da comunidade, a duração por evento e um array de slots por hora indicando disponibilidade.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`date`	string	required	Date to check in `YYYY-MM-DD` format. Must be today or a future date.

Modelo de resposta — `AvailabilityResponse`

Campo	Tipo	Descrição
`spaceId`	integer	Unique identifier of the space
`spaceName`	string	Display name of the space
`date`	string (date)	The queried date in YYYY-MM-DD format
`windowStart`	integer (0–23)	Earliest available hour for this space
`windowEnd`	integer (0–23)	Latest hour in the booking window
`durationHours`	number	Fixed event duration defined by the community
`timeSlots`	array	Array of `TimeSlot` objects (see below)

Objeto TimeSlot

Campo	Tipo	Descrição
`hour`	integer (0–23)	The starting hour in 24-hour format
`label`	string	Human-readable label, e.g. `"9:00 AM"`
`isAvailable`	boolean	Whether this slot is open for booking

cURL

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

JSON — 200 OK

{
  "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 },
    { "hour": 12, "label": "12:00 PM", "isAvailable": true  },
    { "hour": 13, "label": "1:00 PM",  "isAvailable": true  },
    { "hour": 14, "label": "2:00 PM",  "isAvailable": false },
    { "hour": 15, "label": "3:00 PM",  "isAvailable": true  }
  ]
}

Reservas

GET /bookings ReadBookings

Retorna uma lista de reservas visíveis para a chave autenticada. Chaves de comunidade veem todas as reservas dos seus espaços. Chaves de marca veem apenas as reservas que criaram.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`startDate`	string	optional	Filter bookings on or after this date (`YYYY-MM-DD`)
`endDate`	string	optional	Filter bookings on or before this date (`YYYY-MM-DD`)
`status`	string	optional	Filter by status: `Pending`, `Approved`, `Cancelled`, `Completed`

cURL

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

JSON — 200 OK

[
  {
    "id": 1001,
    "spaceId": 42,
    "spaceName": "Sunset Clubhouse",
    "date": "2026-04-15",
    "startHour": 10,
    "endHour": 13,
    "status": "Approved",
    "totalPrice": 345.00,
    "createdAt": "2026-04-01T14:22:00Z"
  }
]

POST /bookings WriteBookings

Envia uma solicitação de reserva para um espaço em nome da chave de Marca autenticada. A reserva entra em estado Pendente e deve ser aprovada pela comunidade. Este endpoint está disponível apenas para chaves com escopo de Marca.

Preços: O total é a taxa fixa por evento mais a taxa de serviço da marca (nas configurações de pagamento, normalmente 15%). A duração não altera a taxa. O campo totalPrice da resposta é o valor cobrado da marca na aprovação.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`spaceId`	integer	required	The ID of the space to book
`startTime`	string (date)	required	Requested date in `YYYY-MM-DD` format
`startHour`	integer (0–23)	required	Requested start hour in 24-hour format
`message`	string	optional	Optional note to the community (max 500 characters)

cURL

curl -X POST https://www.hoastnow.com/api/v1/bookings \
  -H "Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "spaceId": 42,
    "startTime": "2026-04-15",
    "startHour": 10,
    "message": "Launching our new product line."
  }'

JSON — 201 Created

{
  "id": 1002,
  "spaceId": 42,
  "spaceName": "Sunset Clubhouse",
  "date": "2026-04-15",
  "startHour": 10,
  "endHour": 13,
  "status": "Pending",
  "totalPrice": 345.00,
  "createdAt": "2026-04-02T09:14:00Z"
}

Avaliações

GET /communities/{communityId}/reviews ReadReviews

Retorna todas as avaliações de uma comunidade. Chaves de comunidade só podem acessar avaliações da sua própria comunidade. Chaves de marca podem acessar avaliações de qualquer comunidade com a qual tenham uma reserva concluída.

Parâmetros de caminho

Parâmetro	Tipo	Descrição
`communityId`	integer	The ID of the community whose reviews to retrieve

cURL

curl https://www.hoastnow.com/api/v1/communities/7/reviews \
  -H "Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx"

JSON — 200 OK

[
  {
    "id": 55,
    "propertyId": 7,
    "spaceId": 42,
    "rating": 5,
    "title": "Perfect venue for our product launch",
    "content": "The space was immaculate and the community team was responsive throughout.",
    "isVerifiedBooking": true,
    "createdAt": "2026-03-20T11:30:00Z"
  }
]

Webhooks

Webhooks entregam notificações em tempo real ao seu servidor quando eventos ocorrem no hoastnow. Registre um endpoint HTTPS e selecione quais tipos de evento deseja receber. Cada entrega inclui um cabeçalho de assinatura para verificação.

GET /webhooks Webhooks

Lista todos os endpoints de webhook registrados para esta API key.

cURL

curl https://www.hoastnow.com/api/v1/webhooks \
  -H "Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx"

POST /webhooks Webhooks

Registra um novo endpoint de webhook. A resposta inclui um signingSecret exibido apenas uma vez — armazene-o com segurança. Ele é usado para verificar que as entregas de webhook são originadas do hoastnow.

Tipos de evento (máscara de bits)

Evento	Valor	Descrição
`BookingRequested`	1	A new booking request was submitted
`BookingApproved`	2	A booking request was approved by the community
`BookingCancelled`	4	A booking was cancelled by either party
`ReviewPosted`	8	A new review was submitted for a space

Passe uma soma de máscara de bits para se inscrever em múltiplos eventos. Por exemplo, events: 3 inscreve em BookingRequested (1) e BookingApproved (2). Use 15 para todos os eventos.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`url`	string (URL)	required	Your HTTPS endpoint that will receive webhook deliveries
`events`	integer	required	Bitmask of event types to subscribe to (see table above)

cURL

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

JSON — 201 Created

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

Armazene o segredo de assinatura imediatamente. O signingSecret é exibido apenas uma vez na resposta de criação. Não pode ser recuperado depois. Se perdido, exclua o webhook e crie um novo.

DELETE /webhooks/{id} Webhooks

Remove permanentemente um registro de webhook. O hoastnow deixará de entregar eventos à URL associada. Retorna 204 No Content em caso de sucesso.

cURL

curl -X DELETE https://www.hoastnow.com/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx"

Verificação de assinatura

Cada entrega de webhook inclui um cabeçalho X-Hoastnow-Signature com uma assinatura HMAC-SHA256 do corpo bruto da requisição, calculada com seu segredo de assinatura. Sempre verifique essa assinatura antes de processar um payload.

JSON payload

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

cURL

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

Modelos

Fichas de referência de esquema para todos os objetos retornados pela API.

BookingDto

Field	Type	Description
`id`	integer	Unique booking identifier
`spaceId`	integer	ID of the booked space
`spaceName`	string	Display name of the space
`date`	string (date)	Booking date in YYYY-MM-DD format
`startHour`	integer (0–23)	Event start time in 24-hour format
`endHour`	integer (0–23)	Event end time in 24-hour format
`status`	string	`Pending` \| `Approved` \| `Cancelled` \| `Completed`
`totalPrice`	number	Total amount charged (flat event fee plus brand service fee; duration does not change the fee)
`createdAt`	string (ISO 8601)	UTC timestamp when the booking was created

AvailabilityResponse

Field	Type	Description
`spaceId`	integer	Space identifier
`spaceName`	string	Space display name
`date`	string (date)	Queried date
`windowStart`	integer	Community booking window open hour
`windowEnd`	integer	Community booking window close hour
`durationHours`	number	Fixed event duration defined by the community
`timeSlots`	array<TimeSlot>	Start-slot availability array

ReviewDto

Field	Type	Description
`id`	integer	Review identifier
`propertyId`	integer	Community (property) the review belongs to
`spaceId`	integer	Specific space reviewed
`rating`	integer (1–5)	Star rating
`title`	string	Review headline
`content`	string	Full review body text
`isVerifiedBooking`	boolean	Whether the reviewer completed a booking
`createdAt`	string (ISO 8601)	UTC timestamp of submission

WebhookDto

Field	Type	Description
`id`	string	Webhook registration identifier
`url`	string	Registered HTTPS endpoint URL
`events`	integer	Subscribed events bitmask
`createdAt`	string (ISO 8601)	UTC registration timestamp

WebhookCreatedDto

Retornado apenas em POST /webhooks. Estende WebhookDto com o segredo de assinatura de uso único.

Field	Type	Description
`id`	string	Webhook identifier
`url`	string	Registered endpoint URL
`events`	integer	Events bitmask
`signingSecret`	string	HMAC-SHA256 secret for signature verification. Shown once only.
`createdAt`	string (ISO 8601)	UTC registration timestamp

Erros

Todas as respostas de erro usam um corpo JSON consistente. Verifique primeiro o código de status HTTP, depois inspecione o campo error para uma mensagem legível por máquina e details para contexto adicional.

Códigos de erro comuns

Código de erro	Status HTTP	Descrição
`InvalidApiKey`	401	API key is missing, malformed, or revoked
`InsufficientPermissions`	403	Key exists but lacks the required permission flag
`ResourceNotFound`	404	The requested resource does not exist or is not accessible to this key
`ValidationError`	400	Required field missing or parameter value is invalid
`SlotUnavailable`	422	The requested time slot is already booked or outside the booking window
`BookingNotAllowed`	422	Business rule prevents the booking (e.g. space inactive, date in the past)
`ScopeViolation`	403	Brand key attempted an action only available to Community keys, or vice versa
`InternalError`	500	Unexpected server error — safe to retry with exponential backoff

JSON — 422 Unprocessable Entity

{
  "error": "SlotUnavailable",
  "details": "The requested time slot (hour 10) on 2026-04-15 is no longer available."
}

Visão geral

Códigos de status HTTP

Autenticação

OAuth 2.1

Descoberta

Endpoints

Escopos

Validade dos tokens

API Keys

Escopos das chaves

Indicadores de permissão

Disponibilidade

Parâmetros de consulta

Modelo de resposta — AvailabilityResponse

Objeto TimeSlot

Reservas

Parâmetros de consulta

Corpo da requisição

Avaliações

Parâmetros de caminho

Webhooks

Tipos de evento (máscara de bits)

Corpo da requisição

Verificação de assinatura

Modelos

BookingDto

AvailabilityResponse

ReviewDto

WebhookDto

WebhookCreatedDto

Erros

Códigos de erro comuns

Modelo de resposta — `AvailabilityResponse`