Savrsoft API — τεκμηρίωση για προγραμματιστές

Πιστοποίηση

Όλα τα αιτήματα API χρησιμοποιούν ένα API key ως bearer token. Δημιουργήστε ένα στην εφαρμογή, στο Developer → API keys. Τα κλειδιά είναι είτε μόνο για ανάγνωση είτε ανάγνωση/εγγραφή.

curl https://savrsoft.com/api/v1/events \
  -H "Authorization: Bearer savr_live_your_key_here"

Base URL: https://savrsoft.com/api/v1 · Όλες οι απαντήσεις είναι σε μορφή JSON. Τα σφάλματα επιστρέφουν { "error": "…" } με κατάσταση 4xx/5xx.

Κωδικοί κατάστασης

Κωδικός	Πότε τον λαμβάνετε
`200`	Επιτυχής ανάγνωση.
`201`	Επιτυχής δημιουργία. Το σώμα είναι `{ "id": 42 }` — ανακτήστε την εγγραφή αν χρειάζεστε τα υπόλοιπα στοιχεία της.
`400`	Λείπει ένα υποχρεωτικό πεδίο, π.χ. `{ "error": "name is required" }`, ή δεν ήταν δυνατή η ανάγνωση ενός cursor σελιδοποίησης.
`401`	Δεν υπάρχει κλειδί API, είναι κακοδιατυπωμένο ή έχει ανακληθεί.
`403`	Χρησιμοποιήθηκε κλειδί μόνο για ανάγνωση σε λειτουργία εγγραφής. Δημιουργήστε κλειδί ανάγνωσης/εγγραφής στο Developer → API keys.
`404`	Η εγγραφή δεν υπάρχει ή ανήκει σε άλλον οργανισμό — τα δύο αυτά είναι σκόπιμα μη διακριτά. Επιστρέφεται επίσης για μη αναγνωρισμένη διαδρομή ή μέθοδο.

Εύρος αυτού του API

Το API είναι μόνο για ανάγνωση και δημιουργία. Δεν υπάρχουν DELETE, PUT ή PATCH endpoints — ένα αίτημα που χρησιμοποιεί κάποιο από αυτά επιστρέφει 404 Unknown endpoint, όπως κάθε μη αναγνωρισμένη διαδρομή. Η διαγραφή και η επεξεργασία γίνονται μέσα στην εφαρμογή, ώστε μια ενσωμάτωση να μην μπορεί να καταστρέψει τα αρχεία ενός καφετιέρη. Αν χρειάζεστε πρόσβαση εγγραφής πέρα από τη δημιουργία, πείτε μας τι φτιάχνετε.

Σελιδοποίηση

Κάθε endpoint λίστας είναι σελιδοποιημένο. Περάστε το limit (προεπιλογή 100, μέγιστο 500) και ακολουθήστε το next_cursor μέχρι το has_more να είναι false:

{
  "data": [ ... ],
  "has_more": true,
  "next_cursor": "eyJuYW1lIjoiQWNtZSIsImlkIjo0Mn0"
}

Περάστε τον δείκτη (cursor) αυτούσιο για να πάρετε την επόμενη σελίδα. Αντιμετωπίστε τον ως αδιαφανή — η κωδικοποίηση μπορεί να αλλάξει:

curl "https://savrsoft.com/api/v1/clients?limit=100&cursor=eyJuYW1lIjoiQWNtZSIsImlkIjo0Mn0" \
  -H "Authorization: Bearer savr_live_your_key_here"

Η σελιδοποίηση είναι αγκυρωμένη στην τελευταία γραμμή που παραλάβατε, όχι σε μετατόπιση (offset), οπότε οι γραμμές που δημιουργούνται ή διαγράφονται ενόσω σελιδοποιείτε δεν θα σας κάνουν να παραλείψετε ή να επαναλάβετε μια εγγραφή. Ένας δείκτης (cursor) παραμένει έγκυρος επ' αόριστον.

Παράμετρος Συμπεριφορά

limit 1–500. Αν απουσιάζει, είναι μηδέν, αρνητικό ή μη αριθμητικό, επανέρχεται στο 100· οτιδήποτε πάνω από 500 περιορίζεται στο 500.

cursor next_cursor από την προηγούμενη σελίδα. Παραλείψτε το για την πρώτη σελίδα. Ένας δείκτης (cursor) που δεν μπορεί να αναγνωστεί — κατεστραμμένος ή από διαφορετικό endpoint — επιστρέφει 400 Invalid cursor αντί να επανεκκινεί σιωπηλά από την αρχή.

Παράμετρος	Συμπεριφορά
`limit`	1–500. Αν απουσιάζει, είναι μηδέν, αρνητικό ή μη αριθμητικό, επανέρχεται στο 100· οτιδήποτε πάνω από 500 περιορίζεται στο 500.
`cursor`	`next_cursor` από την προηγούμενη σελίδα. Παραλείψτε το για την πρώτη σελίδα. Ένας δείκτης (cursor) που δεν μπορεί να αναγνωστεί — κατεστραμμένος ή από διαφορετικό endpoint — επιστρέφει `400 Invalid cursor` αντί να επανεκκινεί σιωπηλά από την αρχή.

Σειρά ταξινόμησης: /events και /invoices πρώτα τα πιο πρόσφατα· /recipes και /clients κατά όνομα, με ισοπαλίες που επιλύονται βάσει id ώστε η σελιδοποίηση να παραμένει σταθερή όταν τα ονόματα επαναλαμβάνονται.

Endpoints

GET/v1/me

Ο οργανισμός σας (id, όνομα, νόμισμα).

GET/v1/events

Λίστα εκδηλώσεων, πρώτα οι πιο πρόσφατες. Σελιδοποιημένο — δείτε Σελιδοποίηση παραπάνω.

GET/v1/events/{id}

Μία εκδήλωση με τα πιάτα της.

POST/v1/events · απαιτεί δικαιώματα ανάγνωσης/εγγραφής

Δημιουργία εκδήλωσης. Σώμα αιτήματος:

{ "name": "Acme holiday party", "event_date": "2026-12-18",
  "guests": 120, "price_per_head": 55, "event_type": "corporate" }

GET/v1/recipes · GET/v1/recipes/{id}

Λίστα συνταγών (με αλλεργιογόνα & διατροφικές σημάνσεις), ή μία συνταγή με τα υλικά της. Η λίστα είναι σελιδοποιημένη και ταξινομημένη κατά όνομα.

GET/v1/clients · POST/v1/clients

Λίστα πελατών (σελιδοποιημένη, κατά όνομα) ή δημιουργία νέου. Σώμα δημιουργίας: { "name": "...", "email": "...", "phone": "...", "company": "..." }

GET/v1/invoices · GET/v1/invoices/{id}

Λίστα τιμολογίων με υπολογισμένα σύνολα, με τα πιο πρόσφατα πρώτα, ή ένα τιμολόγιο με τις γραμμές του. Η λίστα είναι σελιδοποιημένη.

Webhooks

Καταχωρίστε ένα endpoint στο Developer → Webhooks. Στέλνουμε POST ένα JSON payload όταν συμβαίνουν συμβάντα:

{
  "id": "evt_abc123",
  "type": "event.inquiry",
  "created_at": "2026-07-17T18:20:00.000Z",
  "data": { "id": 42, "name": "Corporate lunch — Dana Ruiz", ... }
}

Τύποι συμβάντων

Τύπος	Ενεργοποιείται όταν
`event.created`	Δημιουργείται μια εκδήλωση
`event.inquiry`	Φτάνει ένα νέο online αίτημα catering
`invoice.sent`	Ένα τιμολόγιο επισημαίνεται ως απεσταλμένο
`invoice.paid`	Ένα τιμολόγιο επισημαίνεται ως εξοφλημένο
`proposal.approved`	Ένας πελάτης εγκρίνει μια πρόταση
`client.created`	Δημιουργείται ένας πελάτης

Επαλήθευση υπογραφών

Κάθε παράδοση περιλαμβάνει μια κεφαλίδα x-savrsoft-signature : το HMAC-SHA256 του ακατέργαστου σώματος του αιτήματος, με κλειδί το μυστικό υπογραφής του webhook σας. Υπολογίστε το ίδιο και συγκρίνετε:

// Node.js
const crypto = require('crypto');
const sig = crypto.createHmac('sha256', SIGNING_SECRET)
  .update(rawBody).digest('hex');
if (sig !== req.headers['x-savrsoft-signature']) reject();

Απόρρητο · Ασφάλεια · Όροι · Ερωτήσεις; savrsoft.com · Δημιουργήστε ενσωματώσεις catering σε λίγα λεπτά.