Avisos ao software de gestão

Se trabalha com um software de gestão, ou com uma ferramenta de automação como o Zapier ou o Make, pode notificá-los no momento exato em que uma reserva é criada, alterada ou cancelada, assim como quando o hóspede chega ou parte. Chega de copiar datas manualmente.

Para que servem os avisos

Sempre que uma reserva muda de estado, o Roraima envia uma breve mensagem para o endereço que indicou. O seu software de gestão recebe-a e atualiza-se sozinho: marca o quarto como ocupado, prepara a limpeza, escreve ao hóspede e atualiza as contas. Tudo o que antes fazia manualmente ao olhar para o painel, agora é feito pelo programa que já utiliza.

Onde os ativar

No painel, abra o menu Ligações e escolha Avisos ao software de gestão. Aí, cole o endereço fornecido pelo seu software de gestão (normalmente encontra-o nas definições, na secção dedicada a ligações de entrada), dê-lhe um nome para o identificar facilmente e escolha quais os avisos a enviar: Reserva confirmada, Reserva alterada, Reserva cancelada, Chegada registada, Partida registada, O hóspede não compareceu. Ao guardar, o Roraima verifica de imediato se o endereço está correto e acessível através da Internet. Pode ligar até cinco endereços, por exemplo, o software de gestão e uma folha de cálculo gerida pelo Zapier.

Cada endereço tem a sua chave de assinatura, que pode ver sempre que quiser: abra «Chave de assinatura» por baixo do endereço e prima «Exibir», e a chave aparece numa página à parte. Deve ser entregue ao software de gestão, ou a quem o configura: serve para que o sistema reconheça que a mensagem provém realmente do Roraima. Trate-a como uma palavra-passe. Se suspeitar que foi comprometida, prima «Criar uma nova chave»: a antiga deixa de funcionar imediatamente e a nova, que volta a ver com «Exibir», deve ser inserida no software de gestão.

Se confiou a casa a um gestor com uma delegação ativa, ele também pode ligar o seu próprio software de gestão e receber os avisos das reservas que gere por si.

Dados do hóspede, apenas se necessários

Por defeito, a mensagem contém tudo o que é necessário para organizar a estadia: alojamento ou espaço, datas, hora, número de pessoas, valor e estado da reserva. O nome, email e telefone do hóspede não são incluídos.

Se o seu software de gestão precisar deles, por exemplo para enviar a mensagem de boas-vindas ou preencher a ficha do hóspede, ative a opção Incluir nome, email e telefone do hóspede nesse endereço. Esta opção vem desativada por omissão: é o utilizador que a ativa, endereço a endereço, apenas onde for realmente necessário.

Um teste antes de começar

Ao lado de cada endereço ativo existe o botão Enviar um teste. O Roraima envia imediatamente uma mensagem de exemplo, com o mesmo formato das verdadeiras mas com dados fictícios, e o resultado aparece no momento no topo da página e na lista dos últimos envios. Nenhuma reserva é afetada e pode repetir o teste as vezes que quiser enquanto configura a ligação.

Se o software de gestão não responder

Acontece: o servidor do software de gestão está em manutenção, a ligação falha ou alguém alterou uma definição. O Roraima não perde o aviso e tenta novamente de forma automática, com intervalos cada vez maiores, de um minuto até um dia inteiro, durante quase dois dias.

No entanto, se durante vinte e quatro horas seguidas esse endereço responder apenas com erros, o Roraima suspende-o e envia-lhe um email de aviso. Quando o software de gestão voltar a estar acessível, prima Reativar ao lado do endereço e os avisos recomeçam. O mesmo botão é utilizado após «Pausar», que serve para interromper os envios temporariamente, por exemplo enquanto muda de software de gestão: os avisos das reservas que mudam durante a pausa não são enviados, e tudo recomeça a partir do momento em que reativa.

Na lista Últimos envios encontrará os últimos vinte avisos de todos os seus endereços, com data, tipo de aviso, reserva, endereço e resultado: Entregue, A aguardar nova tentativa ou Não entregue (neste último caso, é indicado o motivo).

Para quem constrói a ligação

Cada aviso é um pedido POST com um corpo JSON, um evento por pedido, enviado para o endereço registado pelo proprietário. Estes são os cabeçalhos que chegam sempre:

Content-Type: application/json
User-Agent: Roraima-Webhooks/1.0
Roraima-Event-Id: evt_5f2c9a1e7b3d4c6f8a0b1c2d3e4f5a6b
Roraima-Event-Type: booking.confirmed
Roraima-Signature: t=1791986607,v1=5d41402abc4b2a76b9719d911017c592ae51ec1e4d1a8c67b2f0d7d8a3e9c410

Roraima-Event-Id é o mesmo valor do campo id no corpo, e Roraima-Event-Type é o mesmo do campo type: pode decidir o que fazer com um aviso antes mesmo de ler o seu conteúdo.

Os eventos

• booking.confirmed: uma reserva foi confirmada. Válido também para as que chegam de outros canais ligados e para as inseridas manualmente. Também pode chegar para uma reserva que o seu sistema já conhece: quando o canal de origem a torna novamente válida depois de a ter cancelado, ou quando volta a ser válida depois de o proprietário ter resolvido uma sobreposição com outra reserva. Nesses casos, previous_status indica de que estado regressa: atualize a reserva com o mesmo booking.id, sem criar uma nova.
• booking.modified: as datas, a hora ou o número de pessoas foram alterados. O campo changes indica o que mudou.
• booking.cancelled: a reserva foi cancelada. cancelled_by indica se o cancelamento partiu do Roraima ou do canal de origem.
• booking.checked_in: o hóspede chegou.
• booking.checked_out: o hóspede partiu. Se a partida foi fechada automaticamente no prazo, closed_automatically tem o valor true.
• booking.no_show: o hóspede não compareceu.

O proprietário escolhe no painel quais os eventos a enviar para cada endereço: se um tipo não for necessário, pode pedir-lhe que o mantenha desativado.

Um exemplo completo

O corpo chega compacto, numa única linha; aqui está formatado para facilitar a leitura. Os campos podem aumentar com o tempo, mas os existentes não mudam de nome nem de significado enquanto a api_version se mantiver: ignore os que não conhece.

{
  "id": "evt_5f2c9a1e7b3d4c6f8a0b1c2d3e4f5a6b",
  "type": "booking.confirmed",
  "created_at": "2026-10-02T14:03:27Z",
  "api_version": "2026-09-30",
  "test": false,
  "data": {
    "booking": {
      "id": 4812,
      "company_id": 37,
      "status": "confirmed",
      "previous_status": "pending",
      "source": "native",
      "external_id": null,
      "product": { "id": 16702211, "name": "Camera Mirto" },
      "structure_id": 12,
      "check_in": "2026-10-16",
      "check_out": "2026-10-19",
      "booking_mode": "daily",
      "time_slot": null,
      "guests": 2,
      "amount": "390.00",
      "currency": "EUR",
      "cancelled_by": null,
      "closed_automatically": false,
      "sequence": 90417
    },
    "changes": null,
    "actor": "buyer",
    "guest": {
      "name": "Anna Keller",
      "email": "[email protected]",
      "phone": "+491701234567"
    }
  }
}

Para um booking.modified, changes contém apenas os campos alterados, cada um com o valor anterior e o atual:

"changes": {
  "check_out": { "from": "2026-10-19", "to": "2026-10-20" },
  "guests": { "from": 2, "to": 3 }
}

O significado dos campos de booking:

• status e previous_status: o estado após o evento e o anterior. Num booking.modified, onde o estado não muda, ambos coincidem. previous_status tem o valor null apenas para uma reserva criada já confirmada, inserida manualmente ou vinda de um calendário ligado.
• source: a origem da reserva. native da loja Roraima, manual inserida manualmente, ical_airbnb, ical_booking_com, ical_vrbo ou ical_generic de um calendário ligado.
• external_id: para reservas vindas de um calendário ligado, o identificador atribuído por esse calendário; caso contrário, null.
• check_in e check_out: as datas, no formato AAAA-MM-DD. Para reservas por hora, booking_mode tem o valor hourly e time_slot indica a hora, por exemplo {"from": "10:00", "to": "12:00"}.
• guests: o número de pessoas declaradas para a estadia.
• amount e currency: o valor como texto com duas casas decimais e a moeda; ambos null quando a reserva não tem valor, como acontece frequentemente com as vindas de calendários.
• actor: quem causou o evento. guest, buyer, vendor (o proprietário), manager (um gestor com delegação), admin, channel (um calendário ligado) ou system.
• guest: nome, email e telefone do hóspede, apenas se o proprietário tiver ativado a opção nesse endereço; caso contrário, null.

Verificar a assinatura

Cada pedido é assinado com a chave de assinatura do endereço, aquela que começa com whsec_. O cabeçalho Roraima-Signature tem o formato t=<timestamp>,v1=<hex>, onde v1 é o HMAC-SHA256 de t, um ponto e o corpo do pedido, calculado com a chave completa, incluindo o prefixo.

Três cuidados fazem a diferença: calcule a assinatura sobre o corpo bruto, tal como chegou, e nunca sobre um JSON lido e reescrito; compare as duas assinaturas com tempo constante; rejeite o pedido se t estiver a mais de 300 segundos do seu relógio. Em PHP:

<?php
$secret = getenv('RORAIMA_WEBHOOK_SECRET'); // whsec_...
$body   = file_get_contents('php://input');
$header = $_SERVER['HTTP_RORAIMA_SIGNATURE'] ?? '';

if (!preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $header, $m)
    || abs(time() - (int) $m[1]) > 300
    || !hash_equals(hash_hmac('sha256', $m[1] . '.' . $body, $secret), $m[2])) {
    http_response_code(400);
    exit;
}

$event = json_decode($body, true);
// Save $event['id'] and skip it if you have already seen it,
// then reply at once and do the slow work afterwards.
http_response_code(200);

Em Node, sem bibliotecas externas:

const http = require('node:http');
const crypto = require('node:crypto');

const SECRET = process.env.RORAIMA_WEBHOOK_SECRET; // whsec_...

function isValid(rawBody, header) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || '');
  if (!m) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(m[1])) > 300) return false;
  const expected = crypto.createHmac('sha256', SECRET)
    .update(m[1] + '.')
    .update(rawBody)
    .digest();
  return crypto.timingSafeEqual(expected, Buffer.from(m[2], 'hex'));
}

http.createServer((req, res) => {
  const chunks = [];
  req.on('data', (c) => chunks.push(c));
  req.on('end', () => {
    const rawBody = Buffer.concat(chunks);
    if (!isValid(rawBody, req.headers['roraima-signature'])) {
      res.writeHead(400).end();
      return;
    }
    const event = JSON.parse(rawBody.toString('utf8'));
    // Save event.id and skip it if you have already seen it,
    // then reply at once and do the slow work afterwards.
    res.writeHead(200).end();
  });
}).listen(3000);

Duplicados e ordem de chegada

O mesmo aviso pode chegar mais do que uma vez, por exemplo quando a sua resposta se perde pelo caminho e o Roraima tenta novamente. Registe o id de cada evento que já processou e ignore os que voltarem a aparecer.

Com as tentativas de reenvio, dois avisos da mesma reserva podem chegar por uma ordem diferente daquela em que ocorreram: um booking.modified antes do seu booking.confirmed. Para colocar as coisas em ordem, existe o booking.sequence, um número que aumenta a cada aviso da mesma reserva para o mesmo endereço. Guarde o último que registou para cada reserva e descarte os avisos com um número inferior. Os números não são consecutivos: entre um aviso e outro podem faltar muitos.

Respostas e tentativas

Um aviso é entregue quando o seu endereço responde com um código 2xx dentro de 5 segundos. O conteúdo da resposta não é lido. Qualquer outro resultado conta como uma tentativa falhada, incluindo um reencaminhamento para outro endereço (3xx): registe o endereço definitivo no painel.

Após uma tentativa falhada, o Roraima tenta novamente após 1 minuto, depois após 5 minutos, 15 minutos, 1 hora, 3 horas, 6 horas, 12 horas e 24 horas. Se a última tentativa também falhar, esse aviso é fechado como não entregue. Se o endereço responder apenas com erros durante 24 horas seguidas, é suspenso, os avisos pendentes param e o proprietário recebe um email; recomeça quando o proprietário premir «Reativar». Os avisos criados enquanto um endereço está suspenso ou pausado pelo proprietário não são enviados.

Para cumprir o limite de 5 segundos, a forma mais segura é responder imediatamente após verificar a assinatura e registar o evento, deixando o processamento mais longo para um momento posterior.

O aviso de teste

O botão «Enviar um teste», disponível nos endereços ativos, envia um booking.confirmed com o mesmo formato dos verdadeiros, assinado da mesma forma, com "test": true, booking.id igual a 0 e dados fictícios. Se estiverem ativos os dados do hóspede no endereço, estes também serão fictícios. O teste é tentado apenas uma vez e o resultado aparece imediatamente no painel. Verifique o campo test antes de criar algo no seu sistema.

Reconhecer o que vem do seu próprio software de gestão

Se o seu software de gestão já envia as suas reservas para o Roraima através de um calendário ligado, os avisos dessas reservas também regressam a ele. Para as reconhecer, utilize source e external_id: external_id é o identificador que o seu calendário atribuiu à reserva, o mesmo que já conhece.

Requisitos do endereço

O painel verifica-os ao guardar, e o Roraima volta a verificá-los a cada envio:

• Deve começar com https://, com um certificado válido, na porta 443.
• Deve conter apenas o nome do site e o caminho, sem nome de utilizador e palavra-passe incluídos.
• O nome do site deve ser público e acessível a partir da Internet.