Ειδοποιήσεις προς το λογισμικό διαχείρισης

Αν χρησιμοποιείς κάποιο λογισμικό διαχείρισης ή εργαλεία αυτοματισμού όπως το Zapier ή το Make, μπορείς να τα ενημερώνεις αμέσως μόλις δημιουργείται, αλλάζει ή ακυρώνεται μια κράτηση, καθώς και όταν ο επισκέπτης φτάνει ή αναχωρεί. Τέρμα οι χειροκίνητες καταχωρήσεις ημερομηνιών.

Σε τι χρησιμεύουν οι ειδοποιήσεις

Κάθε φορά που μια κράτηση αλλάζει κατάσταση, το Roraima στέλνει ένα σύντομο μήνυμα στη διεύθυνση που έχεις ορίσει. Το λογισμικό διαχείρισής σου το λαμβάνει και ενημερώνεται αυτόματα: σημειώνει το δωμάτιο ως κατειλημμένο, προετοιμάζει τον καθαρισμό, στέλνει μήνυμα στον επισκέπτη, ενημερώνει τα οικονομικά στοιχεία. Όλα όσα έκανες πριν κοιτάζοντας τον πίνακα και αντιγράφοντας δεδομένα, τα κάνει πλέον το πρόγραμμα που ήδη χρησιμοποιείς.

Πού ενεργοποιούνται

Στον πίνακα ελέγχου άνοιξε το μενού Συνδέσεις και επίλεξε Ειδοποιήσεις προς το λογισμικό διαχείρισης. Εκεί επικολλάς τη διεύθυνση που σου έδωσε το λογισμικό σου (συνήθως τη βρίσκεις στις ρυθμίσεις του, στην ενότητα για εισερχόμενες συνδέσεις), της δίνεις ένα όνομα για να την αναγνωρίζεις και επιλέγεις ποιες ειδοποιήσεις θα στέλνονται: Η κράτηση επιβεβαιώθηκε, Η κράτηση άλλαξε, Η κράτηση ακυρώθηκε, Καταχωρίστηκε η άφιξη, Καταχωρίστηκε η αναχώρηση, Ο επισκέπτης δεν εμφανίστηκε. Μόλις αποθηκεύσεις, το Roraima ελέγχει αμέσως αν η διεύθυνση είναι σωστή και προσβάσιμη από το Internet. Μπορείς να συνδέσεις έως και πέντε διευθύνσεις, για παράδειγμα το λογισμικό διαχείρισης και ένα υπολογιστικό φύλλο που διαχειρίζεται το Zapier.

Κάθε διεύθυνση έχει το δικό της κλειδί υπογραφής, το οποίο βλέπεις όποτε θέλεις: άνοιξε το «Κλειδί υπογραφής» κάτω από τη διεύθυνση και πάτησε «Προβολή», και το κλειδί εμφανίζεται σε ξεχωριστή σελίδα. Πρέπει να παραδοθεί στο λογισμικό διαχείρισης ή σε όποιον το ρυθμίζει: χρησιμεύει για να αναγνωρίζει ότι το μήνυμα προέρχεται όντως από το Roraima. Αντιμετώπισέ το σαν κωδικό πρόσβασης. Αν υποψιάζεσαι ότι έχει διαρρεύσει, πάτησε «Δημιουργία νέου κλειδιού»: το παλιό σταματά αμέσως να λειτουργεί και το νέο, που το βλέπεις πάλι με «Προβολή», πρέπει να εισαχθεί στο λογισμικό διαχείρισης.

Αν έχεις αναθέσει το σπίτι σε έναν διαχειριστή με ενεργή εξουσιοδότηση, μπορεί και εκείνος να συνδέσει το δικό του λογισμικό διαχείρισης και να λαμβάνει τις ειδοποιήσεις για τις κρατήσεις που διαχειρίζεται για εσένα.

Τα στοιχεία του επισκέπτη, μόνο αν χρειάζονται

Εξ ορισμού, το μήνυμα περιέχει όλα όσα χρειάζονται για την οργάνωση της διαμονής: κατάλυμα ή χώρος, ημερομηνίες, ώρα, αριθμός ατόμων, ποσό και κατάσταση της κράτησης. Το όνομα, το email και το τηλέφωνο του επισκέπτη δεν περιλαμβάνονται.

Αν το λογισμικό σου τα χρειάζεται, για παράδειγμα για να στείλει μήνυμα καλωσορίσματος ή για να συμπληρώσει την καρτέλα του επισκέπτη, ενεργοποίησε το πλαίσιο Να περιλαμβάνονται το όνομα, το email και το τηλέφωνο του επισκέπτη στη συγκεκριμένη διεύθυνση. Είναι απενεργοποιημένο από προεπιλογή: το ενεργοποιείς εσύ, ανά διεύθυνση, μόνο εκεί που πραγματικά χρειάζεται.

Μια δοκιμή πριν ξεκινήσεις

Δίπλα σε κάθε ενεργή διεύθυνση υπάρχει το κουμπί Αποστολή δοκιμής. Το Roraima στέλνει αμέσως ένα δοκιμαστικό μήνυμα, με την ίδια μορφή με τα πραγματικά αλλά με πλασματικά δεδομένα, και το αποτέλεσμα εμφανίζεται αμέσως στο πάνω μέρος της σελίδας και στη λίστα των τελευταίων αποστολών. Καμία πραγματική κράτηση δεν επηρεάζεται και μπορείς να επαναλάβεις τη δοκιμή όσες φορές θέλεις όσο ρυθμίζεις τη σύνδεση.

Αν το λογισμικό διαχείρισης δεν αποκρίνεται

Συμβαίνει: ο διακομιστής του λογισμικού είναι υπό συντήρηση, η σύνδεση διακόπτεται, κάποιος άλλαξε μια ρύθμιση. Το Roraima δεν χάνει την ειδοποίηση και ξαναπροσπαθεί αυτόματα, σε όλο και μεγαλύτερα χρονικά διαστήματα, από ένα λεπτό έως και μία ολόκληρη ημέρα, για σχεδόν δύο ημέρες.

Αν όμως για είκοσι τέσσερις συνεχόμενες ώρες η διεύθυνση αποκρίνεται μόνο με σφάλματα, το Roraima την αναστέλλει και σου στέλνει ένα email για να σε ενημερώσει. Όταν το λογισμικό γίνει ξανά προσβάσιμο, πάτησε Επανενεργοποίηση δίπλα στη διεύθυνση και οι ειδοποιήσεις θα ξεκινήσουν ξανά. Το ίδιο κουμπί χρησιμοποιείται μετά την Παύση, την οποία επιλέγεις όταν θέλεις να σταματήσεις τις αποστολές για λίγο, για παράδειγμα όσο αλλάζεις λογισμικό διαχείρισης: οι ειδοποιήσεις για τις κρατήσεις που αλλάζουν κατά τη διάρκεια της παύσης δεν αποστέλλονται και όλα συνεχίζουν από τη στιγμή που θα κάνεις επανενεργοποίηση.

Στη λίστα Τελευταίες αποστολές θα βρεις τις τελευταίες είκοσι ειδοποιήσεις από όλες τις διευθύνσεις σου, με ημερομηνία, ειδοποίηση, κράτηση, διεύθυνση και αποτέλεσμα: Παραδόθηκε, Αναμένεται νέα προσπάθεια ή Δεν παραδόθηκε, και στη δεύτερη περίπτωση αναφέρεται και ο λόγος.

Για όποιον κατασκευάζει τη σύνδεση

Κάθε ειδοποίηση είναι ένα αίτημα POST με σώμα JSON, ένα συμβάν ανά αίτημα, που αποστέλλεται στη διεύθυνση που έχει καταχωρίσει ο ιδιοκτήτης. Αυτές είναι οι κεφαλίδες που φτάνουν κάθε φορά:

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 είναι η ίδια τιμή με το πεδίο id στο σώμα, και το Roraima-Event-Type είναι το ίδιο με το πεδίο type: μπορείς να αποφασίσεις τι θα κάνεις με μια ειδοποίηση ακόμα και πριν διαβάσεις το σώμα της.

Τα συμβάντα

• booking.confirmed: μια κράτηση επιβεβαιώθηκε. Ισχύει και για όσες ήρθαν από άλλα συνδεδεμένα κανάλια και για όσες καταχωρήθηκαν χειροκίνητα. Μπορεί να φτάσει και για μια κράτηση που το σύστημά σου γνωρίζει ήδη: όταν το κανάλι προέλευσης την κάνει ξανά έγκυρη αφού την είχε ακυρώσει, ή όταν γίνεται ξανά έγκυρη αφού ο ιδιοκτήτης έχει επιλύσει μια επικάλυψη με άλλη κράτηση. Σε αυτές τις περιπτώσεις το previous_status δείχνει από ποια κατάσταση επιστρέφει: ενημέρωσε την κράτηση με το ίδιο booking.id, χωρίς να δημιουργήσεις νέα.
• booking.modified: άλλαξαν οι ημερομηνίες, η ώρα ή ο αριθμός των ατόμων. Το πεδίο changes δείχνει τι ακριβώς.
• booking.cancelled: η κράτηση ακυρώθηκε. Το cancelled_by δείχνει αν η ακύρωση προήλθε από το Roraima ή από το κανάλι προέλευσης.
• booking.checked_in: ο επισκέπτης έφτασε.
• booking.checked_out: ο επισκέπτης αναχώρησε. Αν η αναχώρηση έκλεισε αυτόματα κατά τη λήξη, το closed_automatically έχει τιμή true.
• booking.no_show: ο επισκέπτης δεν εμφανίστηκε.

Ο ιδιοκτήτης επιλέγει στον πίνακα ελέγχου ποια συμβάντα θα στέλνονται σε κάθε διεύθυνση: αν κάποιος τύπος δεν σου είναι χρήσιμος, μπορείς να του ζητήσεις να τον αφήσει απενεργοποιημένο.

Ένα πλήρες παράδειγμα

Το σώμα φτάνει συμπαγές, σε μία μόνο γραμμή· εδώ είναι σελιδοποιημένο για καλύτερη ανάγνωση. Τα πεδία μπορεί να αυξηθούν με τον καιρό, αλλά τα υπάρχοντα δεν αλλάζουν όνομα ή σημασία όσο παραμένει η ίδια api_version: αγνόησε όσα δεν γνωρίζεις.

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

Για ένα booking.modified, το changes περιέχει μόνο τα πεδία που άλλαξαν, το καθένα με την προηγούμενη και την τωρινή τιμή:

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

Η σημασία των πεδίων του booking:

• status και previous_status: η κατάσταση μετά το συμβάν και αυτή που ίσχυε πριν. Σε ένα booking.modified, όπου η κατάσταση δεν αλλάζει, τα δύο συμπίπτουν. Το previous_status έχει τιμή null μόνο για μια κράτηση που δημιουργήθηκε ήδη επιβεβαιωμένη, καταχωρημένη χειροκίνητα ή προερχόμενη από συνδεδεμένο ημερολόγιο.
• source: από πού προήλθε η κράτηση. native από το κατάστημα Roraima, manual καταχωρημένη χειροκίνητα, ical_airbnb, ical_booking_com, ical_vrbo ή ical_generic από συνδεδεμένο ημερολόγιο.
• external_id: για τις κρατήσεις από συνδεδεμένο ημερολόγιο, το αναγνωριστικό που τους έδωσε το ημερολόγιο· διαφορετικά null.
• check_in και check_out: οι ημερομηνίες, σε μορφή ΕΕΕΕ-ΜΜ-ΗΗ. Για κρατήσεις ανά ώρα, το booking_mode έχει τιμή hourly και το time_slot φέρει την ώρα, για παράδειγμα {"from": "10:00", "to": "12:00"}.
• guests: τα άτομα που δηλώθηκαν για τη διαμονή.
• amount και currency: το ποσό ως κείμενο με δύο δεκαδικά ψηφία και το νόμισμα· και τα δύο null όταν η κράτηση δεν έχει ποσό, όπως συμβαίνει συχνά με όσες προέρχονται από ημερολόγια.
• actor: ποιος προκάλεσε το συμβάν. guest, buyer, vendor (ο ιδιοκτήτης), manager (διαχειριστής με εξουσιοδότηση), admin, channel (συνδεδεμένο ημερολόγιο) ή system.
• guest: όνομα, email και τηλέφωνο του επισκέπτη, μόνο αν ο ιδιοκτήτης έχει ενεργοποιήσει το πλαίσιο στη διεύθυνση· διαφορετικά null.

Επαλήθευση της υπογραφής

Κάθε αίτημα υπογράφεται με το κλειδί υπογραφής της διεύθυνσης, αυτό που ξεκινά με whsec_. Η κεφαλίδα Roraima-Signature έχει τη μορφή t=<timestamp>,v1=<hex>, όπου το v1 είναι το HMAC-SHA256 του t, μιας τελείας και του σώματος του αιτήματος, υπολογισμένο με το πλήρες κλειδί, συμπεριλαμβανομένου του προθέματος.

Τρεις προσεκτικές κινήσεις κάνουν τη διαφορά: υπολόγισε την υπογραφή στο ακατέργαστο σώμα (raw body), όπως ακριβώς έφτασε, και ποτέ σε ένα JSON που έχει διαβαστεί και ξαναγραφτεί· σύγκρινε τις δύο υπογραφές σε σταθερό χρόνο (constant time)· απέρριψε το αίτημα αν το t απέχει περισσότερο από 300 δευτερόλεπτα από το ρολόι σου. Σε 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);

Σε Node, χωρίς εξωτερικές βιβλιοθήκες:

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);

Διπλότυπα και σειρά άφιξης

Η ίδια ειδοποίηση μπορεί να φτάσει περισσότερες από μία φορές, για παράδειγμα όταν η απόκρισή σου χάνεται στη διαδρομή και το Roraima ξαναπροσπαθεί. Κατάγραψε το id κάθε συμβάντος που έχεις ήδη επεξεργαστεί και αγνόησε όσα επαναλαμβάνονται.

Επιπλέον, με τις επαναπροσπάθειες, δύο ειδοποιήσεις της ίδιας κράτησης μπορεί να φτάσουν με διαφορετική σειρά από αυτήν που συνέβησαν: ένα booking.modified πριν από το booking.confirmed. Για να βάλεις τα πράγματα σε σειρά υπάρχει το booking.sequence, ένας αριθμός που αυξάνεται σε κάθε ειδοποίηση της ίδιας κράτησης προς την ίδια διεύθυνση. Κράτα τον τελευταίο αριθμό που κατέγραψες για κάθε κράτηση και απόρριψε τις ειδοποιήσεις με χαμηλότερο αριθμό. Οι αριθμοί δεν είναι συνεχόμενοι: ανάμεσα σε δύο ειδοποιήσεις μπορεί να λείπουν πολλοί.

Αποκρίσεις και επαναπροσπάθειες

Μια ειδοποίηση θεωρείται παραδοθείσα όταν η διεύθυνσή σου αποκρίνεται με κωδικό 2xx εντός 5 δευτερολέπτων. Το περιεχόμενο της απόκρισης δεν διαβάζεται. Οποιοδήποτε άλλο αποτέλεσμα μετράει ως αποτυχημένη προσπάθεια, συμπεριλαμβανομένης της ανακατεύθυνσης σε άλλη διεύθυνση (3xx): καταχώρισε την οριστική διεύθυνση στον πίνακα.

Μετά από μια αποτυχημένη προσπάθεια, το Roraima ξαναπροσπαθεί μετά από 1 λεπτό, μετά μετά από 5 λεπτά, 15 λεπτά, 1 ώρα, 3 ώρες, 6 ώρες, 12 ώρες και 24 ώρες. Αν και η τελευταία προσπάθεια αποτύχει, η ειδοποίηση κλείνει ως μη παραδοθείσα. Αν η διεύθυνση αποκρίνεται μόνο με σφάλματα για 24 ώρες συνεχόμενα, αναστέλλεται, οι ειδοποιήσεις σε αναμονή σταματούν και ο ιδιοκτήτης λαμβάνει ένα email· η λειτουργία συνεχίζεται όταν ο ιδιοκτήτης πατήσει «Επανενεργοποίηση». Οι ειδοποιήσεις που δημιουργούνται ενώ μια διεύθυνση είναι σε αναστολή ή σε παύση από τον ιδιοκτήτη δεν αποστέλλονται.

Για να παραμείνεις εντός των 5 δευτερολέπτων, ο πιο ασφαλής τρόπος είναι να αποκρίνεσαι αμέσως αφού ελέγξεις την υπογραφή και καταγράψεις το συμβάν, και να εκτελείς τη χρονοβόρα εργασία σε δεύτερο χρόνο.

Η δοκιμαστική ειδοποίηση

Το κουμπί «Αποστολή δοκιμής», διαθέσιμο στις ενεργές διευθύνσεις, στέλνει ένα booking.confirmed με την ίδια μορφή με τα πραγματικά, υπογεγραμμένο με τον ίδιο τρόπο, με "test": true, booking.id ίσο με 0 και πλασματικά δεδομένα. Αν στη διεύθυνση είναι ενεργοποιημένα τα στοιχεία του επισκέπτη, και αυτά είναι πλασματικά. Η δοκιμή επιχειρείται μία φορά και το αποτέλεσμα εμφανίζεται αμέσως στον πίνακα. Έλεγξε το test πριν δημιουργήσεις οτιδήποτε στο σύστημά σου.

Αναγνώριση όσων προέρχονται από το ίδιο το λογισμικό διαχείρισής σου

Αν το λογισμικό σου στέλνει ήδη τις κρατήσεις του στο Roraima μέσω συνδεδεμένου ημερολογίου, οι ειδοποιήσεις για αυτές τις κρατήσεις επιστρέφουν και σε αυτό. Για να τις αναγνωρίσεις χρησιμοποίησε το source και το external_id: το external_id είναι το αναγνωριστικό που έδωσε το ημερολόγιό σου στην κράτηση, το ίδιο που ήδη γνωρίζεις.

Απαιτήσεις της διεύθυνσης

Ο πίνακας ελέγχου τις ελέγχει ήδη κατά την αποθήκευση και το Roraima τις επανελέγχει σε κάθε αποστολή:

• Ξεκινά με https://, με έγκυρο πιστοποιητικό, στη θύρα 443.
• Περιέχει μόνο το όνομα του ιστότοπου και τη διαδρομή, χωρίς όνομα χρήστη και κωδικό πρόσβασης εντός αυτής.
• Το όνομα του ιστότοπου είναι δημόσιο και προσβάσιμο από το Internet.