API

Το Olvano διαθέτει ένα REST API για τη σύνδεση των δικών σας συστημάτων — δημιουργήστε και διαβάστε τιμολόγια, διαχειριστείτε επαφές και παρακολουθήστε συμβάντα μέσω webhooks. Αυτή η σελίδα σας οδηγεί από ένα token μέχρι την πρώτη σας κλήση· η πλήρης, εκτελέσιμη λίστα των endpoints βρίσκεται στη διαδραστική αναφορά.

Πριν ξεκινήσετε

Χρειάζεστε δύο πράγματα:

1. Έναν λογαριασμό στο πλάνο byznys (το πλάνο free δεν έχει API).
2. Ένα API token συνδεδεμένο με αυτόν τον λογαριασμό (δείτε παρακάτω).

Τα tokens δημιουργούνται από τον ιδιοκτήτη του λογαριασμού. Ένα token ανήκει σε ακριβώς έναν λογαριασμό και φέρει τα δικά του δικαιώματα (scopes), ώστε να μπορείτε να εκδίδετε ξεχωριστό token ανά ενσωμάτωση.

Δημιουργία API token

Στην εφαρμογή πηγαίνετε στις Ρυθμίσεις → API tokens (/app/{slug}/settings/api-tokens), επιλέξτε Νέο token, δώστε του όνομα και επιλέξτε τα δικαιώματά του. Το token σε απλό κείμενο εμφανίζεται μόνο μία φορά — αντιγράψτε το αμέσως και φυλάξτε το με ασφάλεια.

Τα tokens έχουν το πρόθεμα sg_. Αποθηκεύεται μόνο ένα HMAC digest, οπότε το token δεν μπορεί να εμφανιστεί ξανά — αν το χάσετε, δημιουργήστε ένα νέο και διαγράψτε το παλιό.

Δικαιώματα (scopes)

Η ανάγνωση (GET) κοινών πόρων δεν απαιτεί scope· η εγγραφή ναι. Οι λειτουργίες μόνο για ιδιοκτήτη (διαχείριση tokens, webhooks και τραπεζικών λογαριασμών) δεν είναι ποτέ διαθέσιμες σε ένα API token — ακόμη και ένα που εκδόθηκε από ιδιοκτήτη επιστρέφει 403.

Ταυτοποίηση και βασικό URL

Ταυτοποιήστε κάθε αίτημα με το token στην κεφαλίδα Authorization:

Authorization: Bearer sg_your_token

Το βασικό URL είναι ο τομέας της εγκατάστασής σας + /api. Τα endpoints λογαριασμού έχουν τη μορφή /api/accounts/{slug}/…. Τα παρακάτω παραδείγματα χρησιμοποιούν μεταβλητές περιβάλλοντος:

export STARGATE="https://app.stargate.app"   # replace with your instance domain (locally http://localhost:3000)
export SLUG="your-account-slug"
export TOKEN="sg_your_token"

Το πρώτο σας αίτημα

Δείτε τη λίστα τιμολογίων ενός λογαριασμού:

curl "$STARGATE/api/accounts/$SLUG/invoices" \
  -H "Authorization: Bearer $TOKEN"

Η απόκριση είναι μια σελιδοποιημένη λίστα:

{
  "invoices": [ { "id": "…", "number": "2026-0001", "status": "open", "total": "3630.00" } ],
  "total": 128,
  "page": 1,
  "pageSize": 40
}

Σελιδοποίηση, ταξινόμηση και αναζήτηση

Τα endpoints λίστας δέχονται τις εξής παραμέτρους ερωτήματος:

Τα τιμολόγια μπορούν επιπλέον να φιλτραριστούν κατά status, documentType και subjectId. Μια μη έγκυρη παράμετρος δεν χαλάει ποτέ τη λίστα — αντ' αυτού χρησιμοποιείται η προεπιλογή (π.χ. ?page=abc → 1). Κάθε απόκριση φέρει total, page και pageSize, ώστε ο αριθμός των σελίδων να υπολογίζεται εύκολα.

Δημιουργία τιμολογίου

curl -X POST "$STARGATE/api/accounts/$SLUG/invoices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectId": "CUSTOMER_ID",
    "lines": [
      { "name": "Consulting", "quantity": 2, "unitPrice": "1500", "vatRate": 21 }
    ]
  }'

Το subjectId είναι το αναγνωριστικό του πελάτη — βρείτε το από τη λίστα επαφών (GET /api/accounts/$SLUG/subjects) ή δημιουργήστε μία μέσω POST …/subjects. Υποχρεωτικά πεδία είναι το subjectId και τουλάχιστον μία γραμμή στο lines (καθεμία με name και unitPrice). Προαιρετικά μπορείτε να στείλετε documentType, currency, variableSymbol, due, issuedOn και άλλα — πλήρες schema στην interactive reference.

Σε επιτυχία επιστρέφεται 201 και το δημιουργημένο τιμολόγιο:

{ "invoice": { "id": "…", "number": "2026-0002", "status": "open", "total": "3630.00" } }

Σφάλματα

Τα σφάλματα μοιράζονται μια συνεπή δομή — μια κατάσταση HTTP συν JSON με statusMessage και ένα πεδίο data για μηχανική επεξεργασία:

{
  "statusCode": 400,
  "statusMessage": "Invalid invoice",
  "data": { "formErrors": [], "fieldErrors": { "subjectId": ["Required"] } }
}

Για τα σφάλματα πεδίου, το data.code είναι ένας αναγνώσιμος από μηχανή κωδικός (π.χ. subject_not_found) στον οποίο μπορείτε να βασιστείτε περισσότερο απ' ό,τι στο κείμενο του μηνύματος.

Όρια πλάνου

Το πλάνο free δεν κάνει κλήσεις API (όριο 0)· το byznys διαθέτει το API και όλες τις δυνατότητες. Όταν ξεπεραστεί ένα όριο (π.χ. αριθμός επαφών) το API επιστρέφει 402 με plan_limit_reached· για μια δυνατότητα εκτός πλάνου (webhooks, έξοδα…) επιστρέφει 403 με plan_feature_unavailable. Διαβάστε τα τρέχοντα όρια και τη χρήση του λογαριασμού σας μέσω:

curl "$STARGATE/api/accounts/$SLUG/entitlements" -H "Authorization: Bearer $TOKEN"

Webhooks

Ένα webhook σας ειδοποιεί για συμβάντα σε πραγματικό χρόνο, αντί να ρωτάτε διαρκώς (polling) το API. Τα webhooks είναι δυνατότητα του πλάνου byznys και τα διαχειρίζεται ο ιδιοκτήτης του λογαριασμού.

Καταχωρίστε το μέσω του API (ή στις ρυθμίσεις του λογαριασμού):

curl -X POST "$STARGATE/api/accounts/$SLUG/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/hooks/stargate",
    "events": ["invoice_paid", "invoice_sent"],
    "authHeader": "Bearer your-shared-secret"
  }'

Βάλτε συγκεκριμένα ονόματα στο events, ή * για όλα. Διαθέσιμα συμβάντα:

invoice_created, invoice_sent, invoice_paid, invoice_overdue, invoice_cancelled, invoice_uncollectible, invoice_viewed, invoice_reminder_sent, recurring_generator_invoice_created.

Το Olvano στέλνει ένα POST στο URL σας με το σώμα:

{ "event_name": "invoice_paid", "body": { "…": "event data" } }

• Αν ορίσετε το authHeader, αποστέλλεται ως η κεφαλίδα Authorization — χρησιμοποιήστε το για να επαληθεύσετε ότι το αίτημα προήλθε πράγματι από το Olvano.
• Κάθε παράδοση φέρει μια κεφαλίδα Idempotency-Key (UUID) — χρησιμοποιήστε την για απαλοιφή διπλοτύπων.
• Η παράδοση επαναλαμβάνεται έως 5× με εκθετική υποχώρηση (exponential backoff) μέχρι να επιστρέψετε κατάσταση 2xx. Οι αποτυχημένες παραδόσεις εμφανίζονται μέσω GET …/webhooks/{id}/failed_deliveries.

Διαδραστική αναφορά

Η πλήρης, πάντα ενημερωμένη λίστα των endpoints — με παραμέτρους, schemas και τη δυνατότητα να τα καλέσετε απευθείας από τον browser:

• Open the API reference (/api-docs)
• Αναγνώσιμο από μηχανή OpenAPI schema: /api/_openapi.json