Documentation — γιατί OS + πώς συνδέεσαι

Η αρχιτεκτονική με μία ματιά

τα δικά σας συστήματα (ERP, DMS, CRM, πανεπιστήμια, φορείς)
        │
        │  X-TenderSense-Key / webhooks (HMAC)
        ▼
┌──────────────────────── TenderSense OS ────────────────────────┐
│  Public API v1          — /api/v1/...        (REST, versioned) │
│  Action Protocol v1.0   — typed actions      (η γλώσσα = ABI)  │
│  Webhook dispatcher     — event.*            (push, signed)    │
│  Immutable event ledger — append-only        (provenance)      │
│  Replay engine          — χρονολόγιο ανά έργο (audit)          │
│  Tenants                — απομόνωση δεδομένων ανά οργανισμό    │
└────────────────────────────────────────────────────────────────┘
        ▲
        │  εμείς: οι εφαρμογές Revenue OS + Authority OS
        │  (Bid Room, Contract Room, Cockpit, Project Twin, Command Center)

Ο πυρήνας είναι append-only: τίποτα δεν διαγράφεται, κάθε γεγονός έχει χρονοσφραγίδα, προέλευση και fingerprint. Οι όψεις (UI) ξαναχτίζονται από τα γεγονότα — γι' αυτό μπορούμε να αναπαράγουμε το ιστορικό κάθε έργου ακριβώς όπως έγινε (replay).

Quickstart — πρώτη σύνδεση σε 3 βήματα

curl -X POST https://tendersense.gr/api/v1/keys \
  -H "Authorization: Bearer $TS_SESSION" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-erp", "scopes": ["read:events", "write:feedback"]}'

→ { "id": "...", "name": "my-erp", "secret": "ts_…", "scopes": [...], ... }

curl https://tendersense.gr/api/v1/health
→ { "api": "tendersense-v1", "version": "1.0.0", "status": "ok" }

curl -H "X-TenderSense-Key: ts_…" \
  "https://tendersense.gr/api/v1/external/events?since_hours=24"
→ { "api_version": "1.0.0", "since": "…", "stats": {...}, "events": [...] }

curl -X POST https://tendersense.gr/api/v1/external/feedback \
  -H "X-TenderSense-Key: ts_…" \
  -H "Content-Type: application/json" \
  -d '{"entity": "PROJECT-123", "reason": "Η δαπάνη έχει εγκριθεί από το ΔΣ",
       "evidence": ["DECISION-44"]}'
→ 202 { "accepted": true, "action_id": "…" }

Πιστοποίηση (Authentication)

Λάθος ή ανακλημένο key: 401 με κεφαλίδα WWW-Authenticate: X-TenderSense-Key.

Scopes

API Reference — Public API v1 (1.0.0)

Webhooks — push συμβάντων με υπογραφή (replay-safe)

Καταχωρείτε URL + λίστα συμβάντων + secret. Κάθε delivery φέρει τέσσερις κεφαλίδες — η υπογραφή καλύπτει timestamp + delivery-id + body, ώστε ένα παλιό delivery να μην μπορεί να επαναπαιχθεί:

event.created
tender.published
contract.expiring
approval.requested
payment.recorded
authority.feedback
stage_transition
typed_action_proposal

import hmac, hashlib, time

def verify(secret, headers, raw_body):
    ts = headers.get("X-TenderSense-Timestamp", "")
    did = headers.get("X-TenderSense-Delivery-Id", "")
    sig = headers.get("X-TenderSense-Signature", "")
    if not ts.isdigit() or abs(int(time.time()) - int(ts)) > 300:
        return False  # replay: πολύ παλιό delivery
    material = f"{ts}.{did}.".encode() + raw_body
    expected = hmac.new(secret.encode(), material,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)
    # + κρατήστε τα delivery-id που έχετε δει (dedup)

Action Protocol v1.0 — το ABI

Κανένα πρόγραμμα δεν αλλάζει κρίσιμα δεδομένα — υποβάλλει δομημένη πρόταση. Ο άνθρωπος εγκρίνει.

{
  "action": "REQUEST_PRICING_APPROVAL",
  "entity": "OPP-2048",
  "reason": "...",
  "evidence": ["PRICE-12", "COST-44"],
  "confidence": 0.91,
  "requires_human_approval": true
}

REQUEST_PRICING_APPROVAL
REQUEST_COMPLIANCE_REVIEW
REQUEST_LEGAL_REVIEW
REQUEST_BID_APPROVAL
SUBMIT_OFFER
LOG_DECISION
NOTIFY_OWNER
AUTHORITY_CONFIRM_TENDER
EXTERNAL_FEEDBACK

Module manifest — για ό,τι χτίζετε πάνω στο OS

Το action_protocol_version δηλώνει ποια έκδοση του ABI μιλάει (τρέχουσα: 1.0). Το slug είναι δικό σας — κανείς άλλος δεν μπορεί να το πάρει.

{
  "slug": "my-invoicing-bridge",
  "name": "Invoicing Bridge",
  "description": "Στέλνει πληρωμές ΚΗΜΔΗΣ στο ERP μας",
  "author": "My Company",
  "version": "0.1.0",
  "action_protocol_version": "1.0",
  "actions": [
    {"action": "NOTIFY_OWNER"},
    {"action": "LOG_DECISION"}
  ],
  "webhook_url": "https://mycompany.example/hooks/ts"
}

Κανόνες: slug αλφαριθμητικό (a-z0-9-_), name υποχρεωτικό, τουλάχιστον μία action, max 50 actions, description ≤ 500, version ≤ 30 χαρακτήρες, webhook_url ≤ 300.

Ο πυρήνας — immutable event ledger + replay

OpenAPI specification & SDK

Το πλήρες μηχαναγνώσιμο σχήμα του API είναι δημοσιευμένο — για codegen (openapi-generator, Postman, client libraries):

from tendersense_sdk import TenderSenseClient

ts = TenderSenseClient(api_key="ts_...")

ts.health()                                   # { "api": "tendersense-v1", "version": "1.0.0", "status": "ok" }
ts.external_events(since_hours=24)            # η ροή γεγονότων του πυρήνα
ts.external_feedback("PROJECT-123",
                     "Η δαπάνη εγκρίθηκε", ["DECISION-44"])   # → typed action

# Webhook επαλήθευση με replay protection:
TenderSenseClient.verify_webhook_request(
    secret, request_headers, raw_body, max_age_seconds=300)

# Με session χρήστη (για keys / webhooks / modules):
ts2 = TenderSenseClient(session_token="<bearer>")
ts2.create_key("my-erp", ["read:events", "write:feedback"])
ts2.register_webhook("https://my.example/hook", ["payment.recorded"])
ts2.register_module({...})                    # manifest — βλέπε παραπάνω

Το SDK είναι μόνο stdlib — αντιγράφεται, ενσωματώνεται και διανέμεται ελεύθερα. Πλήρης τεκμηρίωση στο docstring.

Ασφάλεια — αρχιτεκτονική, όχι υπόσχεση

• Immutable ledger — append-only + SHA-256 hash chain: κάθε γεγονός δεσμεύει το προηγούμενο (tamper-evident, ελέγξιμο).
• Action Protocol — καμία ευαίσθητη ενέργεια χωρίς ανθρώπινη έγκριση· confidence 1.0 μόνο για ντετερμινιστικές συνδέσεις κωδικών.
• Tenant απομόνωση — κάθε οργανισμός βλέπει μόνο τα δεδομένα του· το API δεν μπορεί να διαρρεύσει δεδομένα άλλου.
• API keys — μόνο hash αποθηκεύεται· ανάκληση = soft (audit διατηρείται).
• Webhooks — HMAC-SHA256 πάνω σε timestamp+delivery-id+body· replay-safe.
• Υποδομή — εντός Ευρωπαϊκής Ένωσης, GDPR, αντίγραφα ασφαλείας.