ONE FLOW για developers

Κρατήσεις από οποιοδήποτε website

Μια επιχείρηση του ONE FLOW μπορεί να δέχεται κρατήσεις απευθείας από το δικό της website. Δύο τρόποι: το widget (μία γραμμή κώδικα, έτοιμη φόρμα) ή το REST API (δική σου φόρμα, με όποια εμφάνιση και τεχνολογία θέλεις - JavaScript, Laravel, WordPress, οτιδήποτε). Τα ραντεβού μπαίνουν κατευθείαν στο ημερολόγιο της επιχείρησης και ο πελάτης λαμβάνει τα ίδια μηνύματα επιβεβαίωσης/υπενθύμισης με την κανονική σελίδα κράτησης.

1. Widget - χωρίς προγραμματισμό

Η επιχείρηση φτιάχνει ένα publishable κλειδί στο ONE FLOW (Ρυθμίσεις → Website & API), δηλώνει το site της, και βάζει αυτή τη γραμμή στο σημείο της σελίδας όπου θέλει τη φόρμα:

<script src="https://oneflow.gr/widget.js" data-key="pk_live_..." async></script>

Το ύψος προσαρμόζεται αυτόματα. Για να μπει η φόρμα σε συγκεκριμένο σημείο: data-target="#booking". Μετά από κράτηση, το widget στέλνει event στη σελίδα σου (π.χ. για analytics). Κανένα προσωπικό στοιχείο του πελάτη δεν περνάει στη σελίδα σου:

document.addEventListener("oneflow:booked", (e) => {
  // e.detail = { serviceName: "Κούρεμα", start: "2026-10-01T11:00", test: false }
  gtag("event", "booking", { service: e.detail.serviceName });
});

Το widget λειτουργεί μόνο στα sites που έχει δηλώσει η επιχείρηση για το κλειδί. Αν δεις «Η φόρμα δεν επιτρέπεται σε αυτό το site», πρόσθεσε το site στα επιτρεπόμενα.

2. Κλειδιά

  • pk_… Publishable: για κώδικα στον browser (widget, JavaScript). Δεν είναι μυστικό, αλλά δουλεύει μόνο από τα sites (origins) που έχει εγκρίνει η επιχείρηση.
  • sk_… Secret: μόνο για server (Laravel, WordPress, Node κλπ). Φύλαξέ το στο .env. Αν χρησιμοποιηθεί από browser, απορρίπτεται. Εμφανίζεται μία φορά κατά τη δημιουργία.
  • _test_ κλειδιά: όλα λειτουργούν κανονικά (πραγματικά δεδομένα, πραγματικός έλεγχος διαθεσιμότητας), αλλά οι κρατήσεις δεν αποθηκεύονται και δεν στέλνεται κανένα μήνυμα. Χρησιμοποίησέ τα όσο φτιάχνεις τη φόρμα. Οι απαντήσεις έχουν "test": true και header X-OneFlow-Mode: test.

Κάθε κλειδί ανήκει σε μία επιχείρηση. Για πολλούς πελάτες (π.χ. web agency), ένα κλειδί από τον καθένα. Η επιχείρηση μπορεί να ανακαλέσει ένα κλειδί οποιαδήποτε στιγμή.

3. API

Base URL https://oneflow.gr/api/v1. Κάθε αίτημα με header Authorization: Bearer <κλειδί>. Όλες οι ώρες είναι ISO 8601 με ζώνη ώρας της επιχείρησης (π.χ. 2026-10-01T11:00:00+03:00).

EndpointΤι επιστρέφει
GET /businessΌνομα, περιγραφή, επικοινωνία, ζώνη ώρας, ωράριο, link σελίδας κράτησης
GET /servicesΥπηρεσίες που κλείνονται online, με διάρκεια και προσωπικό
GET /staffΠροσωπικό που κλείνεται online και ποιες υπηρεσίες κάνει ο καθένας
GET /availability?serviceId=…&date=YYYY-MM-DD[&staffId=…]Ελεύθερες ώρες της μέρας: [{ start, end }]
GET /availability?serviceId=…&from=…&to=…[&staffId=…]Έως 62 μέρες σε ένα αίτημα: days = [{ date, slots }] (π.χ. ημερολόγιο μήνα)
POST /bookingsΝέα κράτηση
GET https://oneflow.gr/api/v1/availability?serviceId=svc_123&date=2026-10-01

{
  "data": {
    "date": "2026-10-01",
    "timezone": "Europe/Athens",
    "serviceId": "svc_123",
    "staffId": null,
    "durationMinutes": 30,
    "slots": [
      { "start": "2026-10-01T10:00:00+03:00", "end": "2026-10-01T10:30:00+03:00" },
      { "start": "2026-10-01T10:30:00+03:00", "end": "2026-10-01T11:00:00+03:00" }
    ]
  }
}

4. Κράτηση

POST https://oneflow.gr/api/v1/bookings
Authorization: Bearer pk_live_...
Content-Type: application/json
Idempotency-Key: 6f1c2e0a-8b7d-4c2e-9e3b-0d5a1f2b3c4d

{
  "serviceId": "svc_123",
  "staffId": null,
  "start": "2026-10-01T10:30:00+03:00",
  "customer": {
    "firstName": "Μαρία",
    "lastName": "Παπαδοπούλου",
    "email": "maria@example.com",
    "phone": "+306912345678"
  },
  "consent": { "privacy": true, "marketing": false },
  "notes": "Μικρό τατουάζ στον καρπό"
}
201 Created
{
  "data": {
    "id": "cm...",
    "status": "CONFIRMED",
    "start": "2026-10-01T10:30:00+03:00",
    "end": "2026-10-01T11:00:00+03:00",
    "serviceId": "svc_123",
    "staffId": "stf_456",
    "manageUrl": "https://oneflow.gr/r/...",
    "test": false
  }
}
  • start: στείλε ακριβώς ένα slot.start από το /availability. staffId: null = οποιοσδήποτε διαθέσιμος.
  • notes (προαιρετικό, έως 2000 χαρακτήρες): ό,τι έγραψε ο πελάτης για το ραντεβού - η επιχείρηση το βλέπει στις σημειώσεις του ραντεβού.
  • couponCode (προαιρετικό): κωδικός κουπονιού της επιχείρησης - μία φορά ανά πελάτη. Λάθος ή ληγμένος κωδικός = invalid_coupon, ήδη χρησιμοποιημένος = coupon_already_used.
  • Υποχρεωτικά: όνομα, επώνυμο, email και κινητό με κωδικό χώρας. Αν ο πελάτης υπάρχει ήδη (ίδιο email ή κινητό), ενημερώνεται αντί να δημιουργηθεί δεύτερος.
  • manageUrl: προσωπικό link του πελάτη για ακύρωση ή αλλαγή ώρας (έως 24 ώρες πριν). Στέλνεται ήδη και στα email του, μπορείς να το δείξεις και στη σελίδα επιβεβαίωσης.
  • Idempotency-Key (προτείνεται, π.χ. ένα UUID ανά υποβολή φόρμας): αν ξαναστείλεις το ίδιο αίτημα (timeout, διπλό κλικ), παίρνεις την ίδια απάντηση με header Idempotent-Replayed: true και δεν γίνεται δεύτερη κράτηση. Ισχύει 24 ώρες.
  • Από server με secret key, στείλε και "customerIp" (το IP του επισκέπτη σου), ώστε το όριο προσπαθειών να μετράει ανά πελάτη και όχι για όλο τον server σου.

5. Σφάλματα & όρια

Κάθε σφάλμα: { "error": { "code": "...", "message": "..." } }. Το code είναι σταθερό (για τον κώδικά σου), το message είναι στα ελληνικά και μπορείς να το δείξεις στον πελάτη.

401invalid_api_keyΛείπει, είναι άκυρο ή έχει ανακληθεί
403origin_not_allowedPublishable κλειδί από site που δεν έχει εγκριθεί
403secret_key_in_browserSecret κλειδί από browser
404service_not_foundΗ υπηρεσία δεν υπάρχει ή δεν κλείνεται online
409slot_unavailable · staff_unavailableΗ ώρα μόλις κλείστηκε - ξαναφέρε το /availability
409outside_business_hours · no_staff_availableΕκτός ωραρίου / κανείς διαθέσιμος
422invalid_input · invalid_time · invalid_phone · invalid_birthdayΛάθος στοιχεία
422privacy_consent_requiredΛείπει consent.privacy = true
422idempotency_key_reusedΊδιο Idempotency-Key με διαφορετικό αίτημα
429rate_limitedΠολλά αιτήματα - δες το header Retry-After

Όρια: 120 αιτήματα/λεπτό ανά κλειδί. Κρατήσεις: 5 προσπάθειες ανά 15 λεπτά ανά πελάτη (ανά IP επισκέπτη, ή ανά customerIp με secret key). Χωρίς customerIp, ένα secret key έχει 100 προσπάθειες ανά 15 λεπτά συνολικά.

6. Παραδείγματα

JavaScript (browser, publishable key)

const API = "https://oneflow.gr/api/v1";
const headers = { Authorization: "Bearer pk_live_...", "Content-Type": "application/json" };

const { data: services } = await (await fetch(API + "/services", { headers })).json();
const { data: day } = await (await fetch(
  API + "/availability?serviceId=" + services[0].id + "&date=2026-10-01", { headers })).json();

const res = await fetch(API + "/bookings", {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    serviceId: services[0].id,
    start: day.slots[0].start,
    customer: { firstName, lastName, email, phone },
    consent: { privacy: true, marketing: wantsNews },
  }),
});
const json = await res.json();
if (!res.ok) showError(json.error.message);

curl (secret key)

curl https://oneflow.gr/api/v1/services -H "Authorization: Bearer sk_test_..."

Laravel (secret key στο .env ως ONEFLOW_KEY)

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;

$oneflow = Http::withToken(env('ONEFLOW_KEY'))->baseUrl('https://oneflow.gr/api/v1')->acceptJson();

$slots = $oneflow->get('/availability', [
    'serviceId' => $request->service_id,
    'date'      => $request->date,
])->json('data.slots');

$response = $oneflow
    ->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
    ->post('/bookings', [
        'serviceId'  => $request->service_id,
        'start'      => $request->start,          // ένα slot.start από το /availability
        'customer'   => $request->only('firstName', 'lastName', 'email', 'phone'),
        'consent'    => ['privacy' => true, 'marketing' => $request->boolean('marketing')],
        'customerIp' => $request->ip(),
    ]);

if ($response->failed()) {
    return back()->withErrors(['booking' => $response->json('error.message')]);
}
return redirect($response->json('data.manageUrl'));

7. Κανόνες για τη φόρμα σου

  • Προσωπικά δεδομένα (GDPR): ο πελάτης πρέπει να αποδεχτεί ρητά την επεξεργασία των στοιχείων του πριν την κράτηση (consent.privacy: true) - δείξε του την πολιτική απορρήτου της επιχείρησης. Η συναίνεση για προωθητικά (consent.marketing) είναι ξεχωριστή, προαιρετική, και δεν πρέπει να είναι προεπιλεγμένη χωρίς να τη βλέπει ο πελάτης.
  • Bots: αν η φόρμα σου δέχεται spam, πρόσθεσε δικό σου έλεγχο (π.χ. Cloudflare Turnstile ή reCAPTCHA) στο site σου πριν καλέσεις το API. Το API έχει ήδη όρια ανά πελάτη.
  • Ώρες: μην υπολογίζεις ώρες μόνος σου - χρησιμοποίησε πάντα τα slots του /availability και ξαναφέρ' τα αν πάρεις slot_unavailable.

Ερωτήσεις; Η επιχείρηση μπορεί να ανοίξει αίτημα υποστήριξης από το ONE FLOW (Βοήθεια → Αιτήματα). oneflow.gr