REST API · v1

Comarine Family API

Δημόσιο REST API για POS συστήματα και τρίτα εργαλεία. JSON, over HTTPS, με σταθερή δομή απαντήσεων.

Authentication

Όλα τα endpoints (εκτός /health) απαιτούν header:

x-api-key: <COMARINE_POS_API_KEY>

Το κλειδί εκδίδεται από τη διαχείριση Comarine Family. Ποτέ σε client-side κώδικα — μόνο από backend/POS.

GET/api/public/v1/health

Health check

Έλεγχος διαθεσιμότητας. Δεν απαιτείται κλειδί.

Παράδειγμα

curl https://YOUR-DOMAIN/api/public/v1/health

Απάντηση

{ "ok": true, "service": "comarine-family-api", "version": "1", "time": "..." }

GET/api/public/v1/members/{memberId}

Στοιχεία μέλους

Επιστρέφει το προφίλ και την εγκυρότητα της κάρτας.

Παράδειγμα

curl -H "x-api-key: $KEY" \
  https://YOUR-DOMAIN/api/public/v1/members/CF-2026-000123

Απάντηση

{ "member": { "member_id": "CF-2026-000123", "status": "active", ... },
  "valid": true }

GET/api/public/v1/members/{memberId}/summary

Σύνοψη μέλους (πόντοι + ιστορικό)

Υπόλοιπο πόντων (1 πόντος / €1, −100/εξαργύρωση) και τελευταία δραστηριότητα.

Παράδειγμα

curl -H "x-api-key: $KEY" \
  https://YOUR-DOMAIN/api/public/v1/members/CF-2026-000123/summary

Απάντηση

{ "member": {...}, "valid": true,
  "points": { "balance": 340, "earned": 540, "spent": 200, "rule": "..." },
  "recent": { "transactions": [...], "redemptions": [...] } }

GET/api/public/v1/benefits

Λίστα προνομίων

Ενεργά προνόμια. Query: company_slug, active=true|false.

Παράδειγμα

curl -H "x-api-key: $KEY" \
  "https://YOUR-DOMAIN/api/public/v1/benefits?company_slug=cooptravel"

Απάντηση

{ "benefits": [ { "id": "...", "title": "...", "discount_percent": 10 } ] }

POST/api/public/v1/transactions

Καταχώρηση συναλλαγής

Καταχωρεί συναλλαγή στο μέλος (POS). Ανανεώνει την 48μηνη εγκυρότητα.

Body

{
  "member_id": "CF-2026-000123",
  "company_slug": "cooptravel",
  "amount": 129.90,
  "reference": "INV-45912",
  "description": "Πληρωμή κράτησης"
}

Παράδειγμα

curl -X POST -H "x-api-key: $KEY" -H "content-type: application/json" \
  -d @body.json https://YOUR-DOMAIN/api/public/v1/transactions

Απάντηση

{ "ok": true, "transaction": { "id": "...", "amount": 129.9, ... } }

POST/api/public/v1/redemptions

Εξαργύρωση προνομίου

Καταγράφει εξαργύρωση συγκεκριμένου benefit από το μέλος.

Body

{
  "member_id": "CF-2026-000123",
  "benefit_id": "b7f2...-uuid",
  "reference": "POS-778",
  "notes": "Δωρεάν espresso"
}

Παράδειγμα

curl -X POST -H "x-api-key: $KEY" -H "content-type: application/json" \
  -d @body.json https://YOUR-DOMAIN/api/public/v1/redemptions

Απάντηση

{ "ok": true, "redemption": { "id": "...", "benefit_id": "...", ... } }

Σφάλματα

HTTP	Κωδικός	Περιγραφή
401	unauthorized	Λάθος ή απόν x-api-key.
400	invalid_json / invalid_payload	Μη έγκυρο σώμα αίτησης.
404	member_not_found / benefit_not_found / company_not_found	Ο πόρος δεν βρέθηκε.
409	member_not_active / benefit_inactive	Ο πόρος υπάρχει αλλά δεν είναι διαθέσιμος.
500	internal error / api_not_configured	Σφάλμα διακομιστή ή απόν κλειδί.

CORS & Rate limits

CORS ανοιχτό (*) — προβλεπόμενο για server-to-server κλήσεις.
Timing-safe έλεγχος κλειδιού. Rotate μέσω admin.
Καλή πρακτική: το κλειδί μόνο σε server, ποτέ σε browser bundle.