ΤΕΚΜΗΡΙΩΣΗ API

Partner API

Το Partner API επιτρέπει σε έναν συνεργάτη να δημιουργεί λογαριασμούς my-data.app για τους πελάτες του, να ελέγχει αν ένα email υπάρχει ήδη και να διαβάζει την κατάσταση κάθε εγγραφής. Η επικοινωνία γίνεται server-to-server με bearer key.

Λήψη openapi.json Το OpenAPI 3.1 έγγραφο παράγεται από το ίδιο συμβόλαιο και περιλαμβάνει όλα τα endpoints, τα σχήματα, τα scopes και τους κωδικούς σφάλματος.

Γρήγορη εκκίνηση

Πέντε βήματα από την ανάγνωση των απαιτήσεων μέχρι την κατάσταση της εγγραφής.

Διαβάστε τις απαιτήσειςΚαλέστε το GET /requirements με scope requirements:read για την τρέχουσα νομική έκδοση, τα έγγραφα, τα scopes και τα όρια.
Ελέγξτε το emailΚαλέστε το POST /users/check με scope users:check για να δείτε αν ο πελάτης χρειάζεται νέο λογαριασμό ή σύνδεση.
Δημιουργήστε την εγγραφήΚαλέστε το POST /registrations με scope registrations:write, στέλνοντας Idempotency-Key και τη συγκατάθεση της τρέχουσας νομικής έκδοσης.
Ολοκληρώστε τη σύνδεση ή την αυτόματη είσοδοΓια υπάρχον email δώστε στον πελάτη το linking_url. Για νέο λογαριασμό με automatic μπορεί να χρησιμοποιηθεί το automatic_sign_in_url.
Παρακολουθήστε την κατάστασηΚαλέστε το GET /registrations/{registration_id} με scope registrations:read μέχρι η κατάσταση να γίνει ready.

Βασικά URL ανά deployment

Production: https://my-data.app/api/partners/v1
Sandbox: https://sandbox.my-data.app/api/partners/v1
Τοπική ανάπτυξη: http://localhost:4321/api/partners/v1

Πιστοποίηση και scopes

Κάθε αίτημα στέλνει Authorization: Bearer με το partner key. Τα κλειδιά δημιουργούνται και περιστρέφονται από τον διαχειριστή του my-data.app, εμφανίζονται μία φορά και ανακαλούνται αμέσως με την περιστροφή.

Scopes

requirements:read: Ανάγνωση της τρέχουσας νομικής έκδοσης, των εγγράφων, των scopes και των ορίων.
users:check: Έλεγχος αν ένα email ανήκει ήδη σε λογαριασμό my-data.app.
registrations:write: Δημιουργία εγγραφής πελάτη ή αιτήματος σύνδεσης.
registrations:read: Ανάγνωση της κατάστασης εγγραφής που ανήκει στον ίδιο συνεργάτη.

Δυνατότητες συνεργάτη

verified_email: Επιτρέπει την αποδοχή του πεδίου verified_email. Χωρίς αυτό, οι εγγραφές απορρίπτονται με partner_capability_required.
legal_acceptance: Επιτρέπει την αποδοχή της τρέχουσας νομικής έκδοσης για λογαριασμό του πελάτη.
automatic_login: Επιτρέπει το login_mode: automatic και την έκδοση automatic_sign_in_url για νέους λογαριασμούς.

Όρια

Αιτήματα ανά key: 60 ανά λεπτό
Μέγεθος σώματος: 16 KiB JSON
Ισχύς αυτόματης σύνδεσης: 5 λεπτά, έκδοση εντός 10 λεπτών
Ισχύς συνδέσμου σύνδεσης: 15 λεπτά

Απαιτήσεις και νομική έκδοση

GET/api/partners/v1/requirements

Scope: requirements:read

Επιστρέφει την τρέχουσα νομική έκδοση, τα νομικά έγγραφα που πρέπει να αποδεχθεί ο πελάτης, τα διαθέσιμα scopes και τα όρια.

Παράδειγμα cURL

curl -sS \
  "$MY_DATA_BASE_URL/requirements" \
  -H "Authorization: Bearer $MY_DATA_PARTNER_KEY"

Απαντήσεις

200Επιτυχία
401 / 403Άκυρο key ή έλλειψη scope
405Η μέθοδος δεν υποστηρίζεται. Χρησιμοποιήστε τη μέθοδο που ορίζει το endpoint.
429Υπέρβαση ορίου. Δείτε το header Retry-After.
503Προσωρινά μη διαθέσιμο

Παράδειγμα απάντησης

Επιτυχία

{
  "legal_version": "2026-07-12",
  "legal_documents": {
    "terms": "https://my-data.app/terms",
    "privacy": "https://my-data.app/privacy",
    "data_processing_addendum": "https://my-data.app/data-processing-addendum"
  },
  "scopes": [
    "requirements:read",
    "users:check",
    "registrations:write",
    "registrations:read"
  ],
  "limits": {
    "bodyBytes": 16384,
    "requestsPerMinute": 60,
    "loginSeconds": 300,
    "loginWindowSeconds": 600,
    "linkSeconds": 900,
    "leaseSeconds": 120
  }
}

Το legal_version που επιστρέφεται στέλνεται στο legal_acceptance.version της εγγραφής. Η αποδοχή παλαιότερης έκδοσης απορρίπτεται με legal_version_outdated.

Έλεγχος email

POST/api/partners/v1/users/check

Scope: users:check

Ελέγχει αν το email ανήκει ήδη σε λογαριασμό my-data.app και αν υπάρχει ήδη εγγραφή για αυτόν τον συνεργάτη.

Σώμα αιτήματος

{
  "email": "merchant@example.com"
}

Παράδειγμα cURL

curl -sS \
  "$MY_DATA_BASE_URL/users/check" \
  -H "Authorization: Bearer $MY_DATA_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"merchant@example.com"}'

Απαντήσεις

200Επιτυχία
400Μη έγκυρα δεδομένα
401 / 403Άκυρο key ή έλλειψη scope
405Η μέθοδος δεν υποστηρίζεται. Χρησιμοποιήστε τη μέθοδο που ορίζει το endpoint.
429 / 503Υπέρβαση ορίου. Δείτε το header Retry-After. / Προσωρινά μη διαθέσιμο

Παράδειγμα απάντησης

Επιτυχία

{
  "exists": true,
  "registration": {
    "registration_id": "pr_00000000-0000-4000-8000-000000000000",
    "status": "ready"
  }
}

Επιτυχία

{
  "exists": false,
  "registration": null
}

Η ενέργεια είναι μόνο ανάγνωση και δεν δημιουργεί ή αλλάζει λογαριασμό. Χρησιμοποιείται για να επιλεγεί νέος λογαριασμός ή σύνδεση.

Δημιουργία εγγραφής

POST/api/partners/v1/registrations

Scope: registrations:write

Δημιουργεί λογαριασμό για νέο email ή αίτημα σύνδεσης για email που υπάρχει ήδη. Το ίδιο email και password χρησιμοποιούνται μόνο όταν το email είναι νέο.

Σώμα αιτήματος

{
  "customer_id": "customer_123",
  "email": "merchant@example.com",
  "password": "EXAMPLE_PASSWORD_REPLACE_ME",
  "locale": "en",
  "login_mode": "password",
  "verified_email": {
    "verified_at": "2026-10-01T10:00:00Z",
    "reference": "verification_123"
  },
  "legal_acceptance": {
    "version": "2026-07-12",
    "accepted_at": "2026-10-01T10:01:00Z",
    "reference": "consent_123"
  }
}

Παράδειγμα cURL

curl -sS \
  "$MY_DATA_BASE_URL/registrations" \
  -H "Authorization: Bearer $MY_DATA_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_example_7c4a1d" \
  -d @registration.json

Απαντήσεις

201Η εγγραφή δημιουργήθηκε
200Επανάληψη του ίδιου Idempotency-Key
400 / 422Μη έγκυρα δεδομένα / Απόρριψη κωδικού ή στοιχείων
405Η μέθοδος δεν υποστηρίζεται. Χρησιμοποιήστε τη μέθοδο που ορίζει το endpoint.
409Σύγκρουση ταυτότητας, απασχολημένη εγγραφή ή παρωχημένη νομική έκδοση
429 / 503Υπέρβαση ορίου. Δείτε το header Retry-After. / Προσωρινά μη διαθέσιμο

Παράδειγμα απάντησης

Έτοιμο με σύνδεση κωδικού

{
  "registration_id": "pr_00000000-0000-4000-8000-000000000000",
  "sign_in_url": "https://my-data.app/sign-in?lang=en",
  "status": "ready"
}

Έτοιμο με αυτόματη σύνδεση

{
  "registration_id": "pr_00000000-0000-4000-8000-000000000000",
  "sign_in_url": "https://my-data.app/sign-in?lang=en",
  "status": "ready",
  "automatic_sign_in_url": "https://my-data.app/connect/partner#ticket=EXAMPLE_TICKET",
  "expires_at": "2026-10-01T10:06:00Z"
}

Απαιτείται σύνδεση

{
  "registration_id": "pr_00000000-0000-4000-8000-000000000000",
  "sign_in_url": "https://my-data.app/sign-in?lang=en",
  "status": "linking_required",
  "linking_url": "https://my-data.app/connect/partner#link=EXAMPLE_LINK",
  "expires_at": "2026-10-01T10:16:00Z"
}

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

Για υπάρχον email επιστρέφεται linking_url και ο πελάτης ολοκληρώνει ο ίδιος τη συγκατάθεση σύνδεσης. Ο κωδικός δεν αλλάζει και το αίτημα δεν αποκτά πρόσβαση στον λογαριασμό χωρίς τη συγκατάθεση.

Με login_mode automatic και ενεργή τη δυνατότητα automatic_login, επιστρέφεται automatic_sign_in_url μίας χρήσης, με ισχύ πέντε λεπτά και έκδοση εντός δέκα λεπτών από την ολοκλήρωση.

Κατάσταση εγγραφής

GET/api/partners/v1/registrations/{registration_id}

Scope: registrations:read

Επιστρέφει μόνο το αναγνωριστικό, την κατάσταση και το κανονικό sign_in_url για εγγραφή που ανήκει στον ίδιο συνεργάτη.

Παράδειγμα cURL

curl -sS \
  "$MY_DATA_BASE_URL/registrations/pr_00000000-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer $MY_DATA_PARTNER_KEY"

Απαντήσεις

200Επιτυχία
401 / 403Άκυρο key ή έλλειψη scope
404Άγνωστη εγγραφή για αυτόν τον συνεργάτη
405Η μέθοδος δεν υποστηρίζεται. Χρησιμοποιήστε τη μέθοδο που ορίζει το endpoint.
429 / 503Υπέρβαση ορίου. Δείτε το header Retry-After. / Προσωρινά μη διαθέσιμο

Παράδειγμα απάντησης

Επιτυχία

{
  "registration_id": "pr_00000000-0000-4000-8000-000000000000",
  "status": "processing",
  "sign_in_url": "https://my-data.app/sign-in?lang=en"
}

Δεν επιστρέφονται linking ή automatic sign-in σύνδεσμοι από αυτό το endpoint. Επαναλαμβάνετε το αίτημα μέχρι η κατάσταση να γίνει ready.

Ανάκτηση εγγραφής ή συνδέσμου

POST/api/partners/v1/registrations

Scope: registrations:write

Μετά από σφάλμα ή κατάσταση recoverable_failure, επαναλάβετε το ίδιο αίτημα για συμφιλίωση της ίδιας εγγραφής. Αν η κατάσταση είναι linking_required και το linking_url χάθηκε ή έληξε, επαναλάβετε το POST /registrations με το ίδιο Idempotency-Key και σώμα για νέο σύνδεσμο.

Σώμα αιτήματος

{
  "customer_id": "customer_123",
  "email": "merchant@example.com",
  "password": "EXAMPLE_PASSWORD_REPLACE_ME",
  "locale": "en",
  "login_mode": "password",
  "verified_email": {
    "verified_at": "2026-10-01T10:00:00Z",
    "reference": "verification_123"
  },
  "legal_acceptance": {
    "version": "2026-07-12",
    "accepted_at": "2026-10-01T10:01:00Z",
    "reference": "consent_123"
  }
}

Παράδειγμα cURL

curl -sS \
  "$MY_DATA_BASE_URL/registrations" \
  -H "Authorization: Bearer $MY_DATA_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_example_7c4a1d" \
  -d @registration.json

Απαντήσεις

200Επανάληψη του ίδιου Idempotency-Key
201Η εγγραφή δημιουργήθηκε
405Η μέθοδος δεν υποστηρίζεται. Χρησιμοποιήστε τη μέθοδο που ορίζει το endpoint.
409Σύγκρουση ταυτότητας, απασχολημένη εγγραφή ή παρωχημένη νομική έκδοση
503Προσωρινά μη διαθέσιμο

Παράδειγμα απάντησης

503

{
  "error": {
    "code": "identity_unavailable",
    "message": "Η υπηρεσία ταυτότητας δεν είναι διαθέσιμη. Δοκιμάστε ξανά με το ίδιο key."
  }
}

Δεν στέλνεται νέο key και δεν αλλάζει το σώμα. Το 503 μπορεί να δηλώνει αβέβαιη δημιουργία ταυτότητας· η επανάληψη συμφιλιώνει την προηγούμενη προσπάθεια και δεν δημιουργεί τυφλά δεύτερο λογαριασμό. Το GET κατάστασης δεν επιστρέφει νέο linking_url.

Πεδία εγγραφής

customer_id: Το δικό σας αναγνωριστικό πελάτη. Επαναχρησιμοποιείται για ανίχνευση διπλότυπων.
email: Email του πελάτη. Ο έλεγχος /users/check αποφασίζει νέο λογαριασμό ή σύνδεση.
password: Απαιτείται μόνο για νέο email. Παραλείπεται για υπάρχοντα λογαριασμό ή ολοκληρωμένη εγγραφή. Δεν αποθηκεύεται ούτε αλλάζει υπάρχοντα κωδικό.
locale: el ή en για τη γλώσσα του πελάτη.
first_name / last_name: Προαιρετικά. Χρησιμοποιούνται κατά τη δημιουργία λογαριασμού.
login_mode: password (προεπιλογή) ή automatic για νέους λογαριασμούς.
verified_email: Αντικείμενο με verified_at (ISO 8601) και reference. Δηλώνει επαληθευμένο email από τον συνεργάτη. Οι μελλοντικές χρονοσημάνσεις επιτρέπονται έως 60 δευτερόλεπτα.
legal_acceptance: Αντικείμενο με version (η τρέχουσα legal_version), accepted_at και reference. Η αποδοχή καταγράφεται ως αποδεικτικό.

Καταστάσεις

processing: Η εγγραφή επεξεργάζεται. Δοκιμάστε ξανά με το ίδιο Idempotency-Key.
ready: Η εγγραφή ολοκληρώθηκε. Ο πελάτης συνδέεται με το sign_in_url.
linking_required: Το email υπάρχει ήδη. Απαιτείται σύνδεση μέσω του linking_url.
recoverable_failure: Η προσπάθεια δεν ολοκληρώθηκε. Υποβάλετε ξανά το αίτημα με το ίδιο key.

Κωδικοί σφάλματος

invalid_partner_key: Το bearer key λείπει, είναι άγνωστο ή έχει ανακληθεί.
partner_scope_required: Το key δεν έχει το απαιτούμενο scope.
partner_capability_required: Ο συνεργάτης δεν έχει ενεργή την απαιτούμενη δυνατότητα.
rate_limited: Ξεπεράστηκε το όριο των 60 αιτημάτων ανά λεπτό.
invalid_json: Το σώμα δεν είναι έγκυρο JSON object με Content-Type application/json.
invalid_input: Κάποιο πεδίο λείπει ή δεν είναι έγκυρο.
payload_too_large: Το σώμα ξεπερνά τα 16 KiB.
legal_version_outdated: Η νομική έκδοση δεν είναι η τρέχουσα. Διαβάστε ξανά τα requirements.
idempotency_conflict: Το ίδιο Idempotency-Key χρησιμοποιήθηκε με διαφορετικά δεδομένα.
registration_busy: Η εγγραφή επεξεργάζεται αυτή τη στιγμή. Δοκιμάστε ξανά με το ίδιο key.
registration_not_found: Δεν υπάρχει τέτοια εγγραφή για τον συνεργάτη.
identity_conflict: Το email ή ο πελάτης ταιριάζει με διαφορετική υπάρχουσα ταυτότητα.
password_rejected: Ο πάροχος ταυτότητας απέρριψε τον κωδικό ή τα στοιχεία.
identity_unavailable: Η υπηρεσία ταυτότητας δεν είναι διαθέσιμη. Δοκιμάστε ξανά με το ίδιο key.
login_window_expired: Το παράθυρο αυτόματης σύνδεσης έληξε. Χρησιμοποιήστε το sign_in_url.
login_unavailable: Δεν ήταν δυνατή η αυτόματη σύνδεση. Χρησιμοποιήστε το sign_in_url.
link_invalid: Ο σύνδεσμος σύνδεσης έληξε ή δεν είναι έγκυρος.
link_email_mismatch: Η σύνδεση απαιτεί το email του λογαριασμού αυτής της εγγραφής.
auth_required: Απαιτείται ταυτοποίηση για αυτή την ενέργεια.
invalid_origin: Απαιτείται HTTPS εκτός τοπικής ανάπτυξης. Τα αιτήματα σύνδεσης από τον browser πρέπει να έχουν την ίδια προέλευση.
method_not_allowed: Η μέθοδος δεν υποστηρίζεται για αυτό το endpoint.
not_found: Το endpoint ή το αναγνωριστικό δεν βρέθηκε.
partner_unavailable: Η υπηρεσία συνεργατών δεν είναι διαθέσιμη. Δοκιμάστε ξανά αργότερα.