API de dados somente leitura e deep-link de ativação do parceiro para integrar os agentes de IA da Host Logic ao seu PMS ou plataforma de gestão de propriedades. Esta página documenta apenas o que está ativo hoje — uma seção Roadmap claramente identificada cobre o que vem a seguir.
Obtenha sua chave de API → consulte o uso de assentos e os sinais de preço → incorpore o link de ativação do host na sua interface. Esse é o fluxo completo de integração disponível hoje.
Obtenha sua chave de API
Torne-se um parceiro. Após a aprovação, a Host Logic cria a sua conta de parceiro e envia um link de revelação única contendo a sua chave de API hlk_. Armazene-a com segurança — ela não pode ser exibida novamente após a revelação.
Consulte uso & sinais de preço
Chame GET /partner-api/v1/usage para monitorar o consumo de assentos e GET /partner-api/v1/properties/{id}/pricing-signals para exibir os dados de preços do Marcus na sua plataforma.
Incorpore o link de ativação
Adicione um botão na sua interface que abra o deep-link assinado com HMAC https://hostlogic.io/partner/{slug}/activate?token=…. O host escolhe os produtos, a conta Host Logic dele é provisionada e a Laura fica pronta.
curl https://api.hostlogic.io/partner-api/v1/usage \
-H "Authorization: Bearer hlk_your_key_here" \
-H "Accept: application/json"
# 200 OK — a chave é válida, a resposta contém o uso dos seus assentos
# 401 Unauthorized — chave ausente ou inválida
# 403 Forbidden — chave válida, mas sem o escopo necessário
# 429 Too Many Requests — limite de taxa (120 req/min)Todas as solicitações da API exigem um token Bearer no cabeçalho Authorization. Você recebe sua chave de API após a aprovação como parceiro por meio de um link de revelação única — a chave em texto simples nunca é armazenada no servidor e não pode ser exibida novamente.
As chaves de API têm o prefixo hlk_, são vinculadas à sua conta de parceiro e podem ser rotacionadas sem indisponibilidade. Cada chave possui um conjunto de escopos que determina quais endpoints ela pode chamar. Os primeiros 12 caracteres de cada chave (o prefixo da chave) são armazenados em texto simples para identificação nos logs — o restante é hash.
https://api.hostlogic.io/partner-api/v1
Sandbox / DEV:https://api-dev.hostlogic.io/partner-api/v1
120 solicitações/minuto por chave de API. Ao exceder, retorna 429 Too Many Requests.
metrics:read — sempre concedido; cobre o endpoint de uso.marcus:read — concedido quando o seu contrato de parceria inclui dados do Marcus (Revenue Manager); cobre os endpoints de propriedades e pricing-signals.
| Código | Significado |
|---|---|
401 | Chave de API ausente ou inválida |
403 | Chave válida, mas sem o escopo necessário para este endpoint |
404 | Recurso não encontrado ou não pertencente à sua conta de parceiro |
429 | Limite de taxa excedido — 120 req/min |
curl https://api.hostlogic.io/partner-api/v1/usage \
-H "Authorization: Bearer hlk_a8f3c2e1b4d5..." \
-H "Accept: application/json"curl https://api.hostlogic.io/partner-api/v1/usage \
-H "X-Enterprise-Key: hlk_a8f3c2e1b4d5..." \
-H "Accept: application/json"Os endpoints e padrões de integração abaixo já estão em produção. Tudo o que está listado aqui é real e pode ser chamado com uma chave de API válida.
/usage
Uso de assentos da sua conta de parceiro. Escopo: metrics:read (sempre concedido). Consulte a referência completa abaixo.
/properties
Lista as propriedades pertencentes aos seus hosts patrocinados. Escopo: marcus:read. Consulte a referência completa abaixo.
/properties/{propertyId}/pricing-signals
Sinais de preços do Marcus e ocupação futura de uma propriedade patrocinada. Escopo: marcus:read. Consulte a referência completa abaixo.
Deep link de ativação de parceiro
URL assinada com HMAC que provisiona uma conta de host patrocinado. Incorporada na sua interface como um botão. Consulte a referência completa abaixo.
Retorna a contagem de assentos ativos do parceiro autenticado, com detalhamento por host. Útil para conciliar faturamento ou criar um painel de uso dentro da sua plataforma.
metrics:read — sempre concedido a todas as chaves de parceiro.
Este endpoint retorna dados apenas do parceiro autenticado. Ele nunca aceita um parâmetro de consulta partner_id — a identidade vem inteiramente da sua chave de API.
O detalhamento usa IDs opacos de usuários host e contagens de assentos. Os e-mails dos hosts são intencionalmente excluídos.
curl https://api.hostlogic.io/partner-api/v1/usage \
-H "Authorization: Bearer hlk_a8f3c2e1b4d5..." \
-H "Accept: application/json"{
"partner_id": 1,
"generated_at": "2026-06-01T10:30:00Z",
"active_seats": 7,
"hosts": [
{ "host_user_id": 42, "active_seats": 4 },
{ "host_user_id": 67, "active_seats": 3 }
]
}Retorna todas as propriedades pertencentes aos hosts patrocinados pela sua conta de parceiro. Use isto para descobrir quais propriedades você pode consultar para obter sinais de preços.
marcus:read — concedido quando o seu contrato de parceiro inclui o data plane do Marcus Revenue Manager.
Cada entrada contém o id interno da propriedade (necessário para o endpoint de pricing-signals) e o name da propriedade. Dados pessoais do host além do nome da propriedade são excluídos.
curl https://api.hostlogic.io/partner-api/v1/properties \
-H "Authorization: Bearer hlk_a8f3c2e1b4d5..." \
-H "Accept: application/json"{
"partner_id": 1,
"generated_at": "2026-06-01T10:30:00Z",
"properties": [
{ "id": 12, "name": "Harbour View Apartment" },
{ "id": 17, "name": "Old Town Studio" }
]
}Retorna os sinais de preços do Marcus e a ocupação futura de uma única propriedade patrocinada. Use os valores de id da propriedade retornados por GET /properties. Um 404 é retornado se a propriedade não for encontrada ou não pertencer à sua conta de parceiro.
marcus:read
lookback_days (inteiro, padrão 90) — janela do histórico de reservas usada para calcular os sinais.
O objeto signals contém indicadores de preços e estatísticas de reservas. O conjunto exato de campos pode evoluir à medida que o Marcus adiciona novas fontes de dados. O exemplo representativo abaixo mostra os campos disponíveis no lançamento — trate quaisquer campos não reconhecidos como aditivos.
curl "https://api.hostlogic.io/partner-api/v1/properties/12/pricing-signals?lookback_days=90" \
-H "Authorization: Bearer hlk_a8f3c2e1b4d5..." \
-H "Accept: application/json"{
"property_id": 12,
"signals": {
"occupancy_today": 0.75,
"avg_lead_time_days": 18.4,
"avg_stay_nights": 3.2,
"source_mix": {
"booking.com": 0.62,
"direct": 0.38
},
"total_reservations": 87
},
"occupancy_30d": {
"2026-06-01": 0.75,
"2026-06-02": 0.80
}
}Em vez de uma chamada REST, os hosts patrocinados pelo parceiro são integrados por meio de um deep-link assinado. O host clica nele, chega a um marketplace sem preços onde escolhe os produtos, e a conta Host Logic é provisionada — patrocinada e sem necessidade de pagamento separado.
https://hostlogic.io/partner/{slug}/activate?token=<hmac-signed-token>
Onde {slug} é o identificador exclusivo da sua conta de parceiro (fornecido no onboarding) e token é uma carga útil curta, assinada com HMAC, que contém declarações de identidade do host.
Os tokens são assinados com HMAC-SHA256 usando o signing_secret do seu parceiro (separado da sua chave de API). O formato é:
<base64url-payload>.<sha256-hmac>
A carga útil contém declarações de identidade do host, um carimbo de data/hora de expiração no lado do servidor (exp) e um nonce aleatório para evitar a reutilização do token.
Padrão: 1 hora. Tokens expirados são rejeitados com uma mensagem de erro clara — os hosts precisam solicitar um novo link. A Host Logic recomenda gerar links sob demanda (por exemplo, quando um host clica em um botão na sua interface) em vez de armazená-los.
Hoje, os tokens de ativação são gerados pela Host Logic, por meio de uma ferramenta administrativa, mediante solicitação. A geração de tokens em self-service pelo parceiro (gerando tokens programaticamente a partir do seu próprio backend) está no Roadmap — veja abaixo.
https://hostlogic.io/partner/previo/activate
?token=eyJjb250YWN0X2VtYWlsIjoiaG9zdEBleGFtcGxlLmNvbSIsImV4cCI6MTc1MDAwMDAwMCwibm9uY2UiOiJhYjEyY2QzNCJ9.a1b2c3d4e5f6...<!-- Simple button — opens in a new tab -->
<a href="{{ $activationUrl }}" target="_blank" class="btn">
Set up AI Receptionist →
</a>{
"contact_email": "[email protected]",
"contact_name": "Hotel Adriatic",
"previo_hotel_id": "779307",
"requested_product_ids": ["laura-receptionist"],
"exp": 1750000000,
"nonce": "ab12cd34"
}| Etapa | O que acontece |
|---|---|
| 1. Token verificado | A Host Logic valida a assinatura HMAC e verifica a expiração. Tokens inválidos ou expirados exibem uma página de erro clara. |
| 2. Marketplace | O host chega a um marketplace de produtos sem preços, delimitado pelo seu contrato de parceria. Ele seleciona quais produtos ativar. |
| 3. Conta provisionada | Uma conta de host patrocinada da Host Logic é criada (ou vinculada, se o e-mail já existir). Os produtos são ativados sem etapa de pagamento. |
| 4. Onboarding | O host é guiado pelo assistente da base de conhecimento da Laura (instruções de check-in, FAQs, ofertas de upsell). A Laura começa a responder aos hóspedes assim que o assistente é enviado. |
As funcionalidades a seguir estão planejadas ou em desenvolvimento. Elas estão listadas aqui por transparência, para que você possa planejar o roadmap da sua integração. Nenhuma delas pode ser chamada hoje — desenvolver com base nelas agora resultará em erros.
Geração de tokens em self-service pelo parceiro
Um endpoint de API ou um trecho de SDK para download que permite ao seu backend gerar tokens de ativação assinados sem envolver a Host Logic. Hoje, os tokens são gerados mediante solicitação por meio de uma ferramenta administrativa.
Escopos de escrita & endpoints de mutação
Escopos como marcus:write e pierre:write e endpoints REST para cadastrar propriedades (POST /properties), ativar ou desativar unidades individuais e atualizar as configurações do parceiro.
Webhooks / eventos em tempo real
Notificações push para onboarding concluído, unidade ativada/desativada e limites de uso. Registre uma URL de webhook e receba cargas úteis assinadas.
Portal de self-service do parceiro
Um portal de self-service controlado por flag para gerenciar chaves de API, visualizar o uso de assentos e configurar origens de embed permitidas. Atualmente em beta privado.
Endpoint de manutenção Pierre
GET /properties/{propertyId}/operational-state — estado de manutenção e operacional de uma propriedade patrocinada. Desenvolvido, mas desativado por uma feature flag; requer o scope pierre:read. Disponível para parceiros selecionados mediante solicitação.
Incorporação do iframe de onboarding
Incorpore o assistente de configuração da Laura como um iframe na interface do seu PMS, com eventos postMessage para progresso e conclusão de cada etapa. Dependente do lançamento do portal de autoatendimento para parceiros.
Servidor MCP hospedado para enterprise
Um endpoint MCP hospedado em mcp.hostlogic.io, fornecendo acesso às ferramentas do Claude Desktop / Cursor para dados com escopo de parceiro. Arquitetura planejada; ainda não está em produção para parceiros enterprise.
Os parceiros enterprise têm um canal dedicado no Slack com a equipe da Host Logic. Entre em contato pelo [email protected] para discutir os seus requisitos de integração e o cronograma.
Conte-nos sobre o seu PMS, channel manager ou produto de software para hospitalidade. Analisamos as candidaturas de parceiros em até 2 dias úteis e fornecemos a sua chave de API e um canal de suporte dedicado.