Για προγραμματιστές
API συνεργατών
Στείλτε μας τον πελάτη με δικό σας ψευδωνυμοποιημένο αναγνωριστικό, χωρίς email, όνομα και άλλα δεδομένα προσωπικού χαρακτήρα, και διαβάστε οποιαδήποτε στιγμή την κατάσταση της εκπαίδευσής του. Χρησιμεύει ως έλεγχος κανονιστικής συμμόρφωσης πριν από τη σύμβαση, την κατάθεση ή την πληρωμή.
Έκδοση 1.3.2 · JSON μέσω HTTPS · OpenAPI
Πώς λειτουργεί
Το API είναι ίδιο για όλους τους συνεργάτες. Σε πέντε βήματα:
- Ενεργοποιούμε το API για την επιχείρησή σας· στο περιβάλλον διαχείρισής σας, στην καρτέλα API, δημιουργείτε κλειδί API.
- Όταν ένας πελάτης πρέπει να εκπαιδευτεί, το σύστημά σας καλεί POST /v1/users με το δικό σας αναγνωριστικό πελάτη.
- Δημιουργούμε προφίλ χωρίς email και επιστρέφουμε σύνδεσμο εισόδου (entryUrl)· τον εμφανίζετε στον πελάτη ως κουμπί.
- Ο πελάτης κάνει κλικ σε αυτόν και βρίσκεται αμέσως στο μάθημα.
- Την κατάσταση τη διαβάζετε οποιαδήποτε στιγμή μέσω GET /v1/users/{identifier} ή την ανακοινώνουμε στον διακομιστή σας με webhook.
Υπεύθυνος επεξεργασίας του αναγνωριστικού είστε εσείς, εμείς επεξεργαζόμαστε μόνο ψευδωνυμοποιημένα δεδομένα. Ως αναγνωριστικό μην στέλνετε ποτέ email ή όνομα: τη διεύθυνση email το API την απορρίπτει με σφάλμα 422.
Διεύθυνση και αυθεντικοποίηση
Κάθε κλήση γίνεται μέσω HTTPS στη διεύθυνση παρακάτω και φέρει το κλειδί API σας στην κεφαλίδα Authorization.
https://api.responsiblo.com Authorization: Bearer rsb_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
- Το rsb_live_... ανοίγει το παραγωγικό σας πρόγραμμα, το rsb_test_... το δοκιμαστικό σας πρόγραμμα (sandbox).
- Το κλειδί εμφανίζεται μόνο μία φορά, κατά τη δημιουργία· εμείς αποθηκεύουμε μόνο το αποτύπωμά του. Φυλάξτε το ως μυστικό στον διακομιστή σας, ποτέ στο πρόγραμμα περιήγησης ή σε εφαρμογή.
- Το κλειδί έχει δικαιώματα: read (κατάσταση και κατάλογος ατόμων, πιστοποιητικό) και write (αποστολή και ανωνυμοποίηση ατόμων). Μπορεί να περιορίζεται στις διευθύνσεις IP σας και να έχει διάρκεια ισχύος.
- Αντικατάσταση: δημιουργείτε νέο κλειδί, το παλιό ισχύει ακόμη 7 ημέρες και μετά λήγει.
- Οι απαντήσεις δεν αποθηκεύονται ποτέ στην κρυφή μνήμη (Cache-Control: no-store) και το API δεν δέχεται κλήσεις από πρόγραμμα περιήγησης (χωρίς CORS).
POST /v1/users
Στέλνει ένα άτομο στο πρόγραμμα του κλειδιού (δικαίωμα write).
curl -X POST https://api.responsiblo.com/v1/users \
-H "Authorization: Bearer $RSB_KEY" \
-H "Content-Type: application/json" \
-d '{"identifier":"client-48213","language":"cs","label":"campaign-2026-10"}'
| Πεδίο | Υποχρεωτικό | Σημασία |
|---|---|---|
identifier |
ναι | Το δικό σας ψευδώνυμο του ατόμου, 1 έως 64 χαρακτήρες A-Z a-z 0-9 . _ : @ -· ποτέ διεύθυνση email (απορρίπτεται με σφάλμα 422). |
program |
όχι | Κωδικός προγράμματος· αν τον δηλώσετε, πρέπει να είναι το πρόγραμμα του κλειδιού. |
language |
όχι | Γλώσσα του μαθήματος (cs, en, ...)· προεπιλογή είναι η πρώτη γλώσσα του προγράμματος. |
label |
όχι | Η δική σας ετικέτα, κοόρτη ή καμπάνια, 1 έως 64 χαρακτήρες, ποτέ δεδομένα προσωπικού χαρακτήρα. |
expiresAt |
όχι | Τελευταία ημέρα πρόσβασης, ΕΕΕΕ-ΜΜ-ΗΗ. |
201 Created για νέο άτομο, 200 OK όταν το αναγνωριστικό υπάρχει ήδη: τίποτα δεν αλλάζει και η κλήση μπορεί να επαναληφθεί με ασφάλεια. Το σώμα είναι η κατάσταση παρακάτω μαζί με το entryUrl. Εξαντλημένο όριο ατόμων ή άδειας χρήσης του προγράμματος επιστρέφει 403.
GET /v1/users/{identifier}
Κατάσταση του ατόμου (δικαίωμα read): ό,τι χρειάζεται ο έλεγχος κανονιστικής συμμόρφωσης, τίποτα παραπάνω.
curl https://api.responsiblo.com/v1/users/client-48213 -H "Authorization: Bearer $RSB_KEY"
{
"identifier": "client-48213",
"program": "your-program",
"status": "in_progress",
"progress": 43,
"lessonsCompleted": 3,
"lessonsTotal": 7,
"quizScore": null,
"label": "campaign-2026-10",
"createdAt": "2026-10-20T10:02:11Z",
"startedAt": "2026-10-20T10:05:40Z",
"completedAt": null,
"lastActivityAt": "2026-10-20T10:31:40Z",
"expiresAt": null,
"certificate": null,
"entryUrl": "https://your-company.responsiblo.com/entry/..."
}
status | Σημασία |
|---|---|
enrolled |
στάλθηκε, δεν έχει μπει ακόμη |
started |
μπήκε, δεν έχει ολοκληρώσει τίποτα ακόμη |
in_progress |
έχει ολοκληρωμένες ενότητες, το πρόγραμμα όχι ακόμη |
completed |
το πρόγραμμα ολοκληρώθηκε (completedAt) |
expired |
η πρόσβαση έληξε (πέρασε το expiresAt· ένα άτομο στο sandbox λήγει μετά από 7 ημέρες) |
Το quizScore είναι το αποτέλεσμα του τελικού κουίζ σε %, μόλις ολοκληρωθεί. Οι χρόνοι είναι σε UTC με ακρίβεια δευτερολέπτου. Το πεδίο certificate φέρει το πιστοποιητικό του ατόμου (βλ. παρακάτω)· όσο δεν το έχει, είναι null.
?include=detail
Προσθέτει την πρόοδο σε κάθε μάθημα και το αποτέλεσμα κάθε κουίζ, ποτέ τις μεμονωμένες απαντήσεις.
"courses": [{"id": "733db340-...", "name": "Introduction", "progress": 40, "lessonsCompleted": 2, "lessonsTotal": 5, "completed": false}],
"quizzes": [{"id": "d2e72fd7-...", "name": "Quiz of the introduction", "score": 85, "completedAt": "2026-10-20T10:31:40Z"}]
GET /v1/users
Κατάλογος των ατόμων που στείλατε στο πρόγραμμα του κλειδιού (δικαίωμα read), ανά σελίδες: κάθε στοιχείο έχει τη μορφή της κατάστασης παραπάνω. Προαιρετικά status (μόνο άτομα σε αυτή την κατάσταση), limit (1 έως 500, προεπιλογή 100) και cursor.
curl "https://api.responsiblo.com/v1/users?status=completed&limit=100" -H "Authorization: Bearer $RSB_KEY"
{
"items": [{ "identifier": "client-48213", "status": "completed", "...": "the state of GET /v1/users/{identifier}" }],
"nextCursor": "MjAyNi0xMC0yMFQxMDowMjoxMVp8...",
"limit": 100
}
curl "https://api.responsiblo.com/v1/users?status=completed&limit=100&cursor=MjAyNi0xMC0yMFQxMDowMjoxMVp8..." -H "Authorization: Bearer $RSB_KEY"
- Συνεχίστε με cursor = nextCursor, όσο το nextCursor δεν είναι null· ο δείκτης είναι αδιαφανές κείμενο, μην τον συνθέτετε ποτέ μόνοι σας.
- Τα άτομα εμφανίζονται κατά τη στιγμή αποστολής σε σταθερή σειρά (ακόμη και με την ίδια στιγμή), κανένα δύο φορές· τα ανωνυμοποιημένα άτομα δεν περιλαμβάνονται στον κατάλογο.
- Με το φίλτρο status εξετάζουμε για μία σελίδα το πολύ 2000 άτομα, γι’ αυτό μια σελίδα μπορεί να έχει λιγότερα στοιχεία από το limit ή και κανένα: συνεχίστε όσο υπάρχει nextCursor.
Πιστοποιητικό του ατόμου
Μόλις το άτομο ολοκληρώσει το πρόγραμμα, το μάθημα τού εκδίδει πιστοποιητικό, με το ψευδώνυμό του (ψευδώνυμο προφίλ ID XXXXXX), χωρίς όνομα και χωρίς email. Τίποτα δεν αποστέλλεται με email· στην κατάσταση του ατόμου υπάρχει το πεδίο certificate με τον αριθμό, τους χρόνους και τη δημόσια σελίδα επαλήθευσης, και το PDF το κατεβάζετε μέσω GET /v1/users/{identifier}/certificate.
"certificate": {
"number": "RSP-7KQ2-M4XH-9TWB",
"issuedAt": "2026-10-20T10:39:15Z",
"expiresAt": "2028-10-20T10:39:12Z",
"verifyUrl": "https://responsiblo.com/verify/RSP-7KQ2-M4XH-9TWB"
}
curl https://api.responsiblo.com/v1/users/client-48213/certificate -H "Authorization: Bearer $RSB_KEY" -o client-48213.pdf
- Η σελίδα επαλήθευσης verifyUrl δείχνει μόνο το ψευδώνυμο, το πρόγραμμα, τον συνεργάτη και την ισχύ, ποτέ το αναγνωριστικό σας.
- Το PDF επιστρέφει application/pdf (δικαίωμα read). Χωρίς πιστοποιητικό η απάντηση είναι 404 certificateNotFound, ενώ όταν το PDF δημιουργείται ακόμη, 404 certificatePdfNotReady με Retry-After.
- Ανακλημένο πιστοποιητικό δεν επιστρέφεται ποτέ (το πεδίο certificate είναι τότε null, το PDF 404)· πιστοποιητικό που έχει λήξει παραμένει αληθές τεκμήριο και επιστρέφεται.
- Το webhook ανακοινώνει το πιστοποιητικό με το συμβάν certificate.issued (αμέσως μετά το user.completed).
DELETE /v1/users/{identifier}
Ανωνυμοποιεί το άτομο (δικαίωμα write): από το προφίλ εξαφανίζονται το αναγνωριστικό σας, η ετικέτα και κάθε μήνυμα webhook που το αναφέρει· οι σύνδεσμοι εισόδου παύουν να ισχύουν. Το πιστοποιητικό και το αποτέλεσμα του μαθήματος παραμένουν με τον αριθμό του πιστοποιητικού, ως τεκμήριο κανονιστικής συμμόρφωσης.
curl -X DELETE https://api.responsiblo.com/v1/users/client-48213 -H "Authorization: Bearer $RSB_KEY" HTTP/1.1 204 No Content
Απάντηση 204 χωρίς σώμα· κάθε επόμενη κλήση για το ίδιο αναγνωριστικό επιστρέφει 404 userNotFound, οπότε η επανάληψη είναι ασφαλής. Το ίδιο αναγνωριστικό μπορείτε στη συνέχεια να το στείλετε ξανά ως νέο άτομο.
Σύνδεσμος εισόδου
Δείξτε το entryUrl στο άτομο (κουμπί Έναρξη μαθήματος στο σύστημά σας). Το συνδέει στο μάθημα χωρίς email και χωρίς κωδικό πρόσβασης.
Ο σύνδεσμος ισχύει 30 ημέρες και μπορεί να χρησιμοποιηθεί επανειλημμένα· κάθε κλήση GET /v1/users/{identifier} επιστρέφει νέο. Μην τον στέλνετε ποτέ σε κανέναν άλλο: όποιος έχει τον σύνδεσμο, μπαίνει ως αυτό το άτομο.
Webhooks
Στην καρτέλα API του περιβάλλοντος διαχείρισής σας ορίζετε ένα webhook για κάθε πρόγραμμα: τη δημόσια διεύθυνση HTTPS του διακομιστή σας και τα συμβάντα. Στη συνέχεια σας στέλνουμε POST με JSON, μόνο αναγνωριστικά και καταστάσεις, ποτέ τον σύνδεσμο εισόδου.
| Συμβάν | Πότε |
|---|---|
user.enrolled |
το άτομο στάλθηκε (την πρώτη φορά που το γνωρίζει το webhook σας) |
user.started |
το άτομο μπήκε στο μάθημα |
user.completed |
το άτομο ολοκλήρωσε το πρόγραμμα |
certificate.issued |
το άτομο απέκτησε πιστοποιητικό· τα data φέρουν το certificate (αριθμός, χρόνοι, verifyUrl) |
user.expired |
η πρόσβαση του ατόμου έληξε |
POST https://your-server.example/responsiblo/webhook
Content-Type: application/json
X-Responsiblo-Event: user.completed
X-Responsiblo-Delivery: 5b0c1f9e-2d1a-4a57-9a3e-0d6c9c1f2b77
X-Responsiblo-Signature: t=1792492800,v1=3f1c...e9
{
"id": "5b0c1f9e-2d1a-4a57-9a3e-0d6c9c1f2b77",
"type": "user.completed",
"createdAt": "2026-10-20T10:40:00Z",
"apiVersion": "1.3.2",
"program": "your-program",
"data": {
"identifier": "client-48213",
"status": "completed",
"progress": 100,
"lessonsCompleted": 7,
"lessonsTotal": 7,
"quizScore": 85,
"label": "campaign-2026-10",
"startedAt": "2026-10-20T10:05:40Z",
"completedAt": "2026-10-20T10:39:12Z",
"expiresAt": null
}
}
Υπογραφή
Κάθε μήνυμα φέρει την κεφαλίδα X-Responsiblo-Signature: t=<χρόνος unix>,v1=<HMAC-SHA256 του κειμένου t.σώμα με το μυστικό του webhook, hex>. Το μυστικό (whsec_...) εμφανίζεται μία φορά κατά τη δημιουργία του webhook. Πριν εμπιστευτείτε ένα μήνυμα, επαληθεύστε την υπογραφή και την ηλικία του t· ως κλειδί idempotency χρησιμοποιήστε το X-Responsiblo-Delivery.
// PHP: $secret = "whsec_...", $header = X-Responsiblo-Signature, $body = the raw body
preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $header, $m);
$valid = $m
&& abs(time() - (int) $m[1]) <= 300
&& hash_equals(hash_hmac('sha256', $m[1] . '.' . $body, $secret), $m[2]);
Παράδοση και επαναλήψεις
Παραδόθηκε = απάντηση 2xx μέσα σε 10 δευτερόλεπτα. Διαφορετικά δοκιμάζουμε ξανά μετά από 1 λεπτό, 5 λεπτά, 30 λεπτά, 2 ώρες και 12 ώρες και μετά σταματάμε. Ανακατευθύνσεις δεν ακολουθούμε.
20 διαδοχικά μη παραδοθέντα μηνύματα απενεργοποιούν το webhook, μέχρι να το ενεργοποιήσετε ξανά· τα μηνύματα αυτού του διαστήματος περιμένουν. Το κουμπί Δοκιμή στέλνει ping· το αρχείο καταγραφής παραδόσεων το βρίσκετε στο περιβάλλον διαχείρισής σας.
Το συμβάν certificate.issued το προσθέτετε στο webhook στις ρυθμίσεις του· webhook που δημιουργήθηκε πριν από την έκδοση 1.2 δεν το λαμβάνει αυτόματα.
Σφάλματα
Κάθε σφάλμα έχει μία μορφή: status, code, reason και message· το σφάλμα 422 προσθέτει errors (πεδίο: τι είναι λάθος).
{ "status": "error", "code": 422, "reason": "invalidBody", "message": "The body is not valid.",
"errors": { "identifier": "identifier must be a pseudonym of the partner, never an e-mail address" } }
| HTTP | reason | Τι να κάνετε |
|---|---|---|
| 400 | invalidJson |
στείλτε ένα αντικείμενο JSON |
| 401 | missingToken, invalidToken |
στείλτε έγκυρο κλειδί (ανακλημένο και ληγμένο κλειδί φαίνονται ίδια)· η κεφαλίδα WWW-Authenticate λέει Bearer |
| 403 | scopeDenied, ipNotAllowed, apiDisabled, partnerInactive, spaceUnavailable, httpsRequired, userLimitReached, seatsExhausted |
το κλειδί δεν επιτρέπεται να το κάνει αυτό, το API είναι απενεργοποιημένο για την επιχείρησή σας ή το πρόγραμμα είναι πλήρες |
| 404 | userNotFound, notFound |
στο πρόγραμμα του κλειδιού δεν υπάρχει άτομο με αυτό το αναγνωριστικό (ούτε ανωνυμοποιημένο) |
| 404 | certificateNotFound, certificatePdfNotReady |
το άτομο δεν έχει ακόμη πιστοποιητικό ή το PDF του δημιουργείται: δοκιμάστε ξανά μετά το Retry-After |
| 409 | identifierTaken |
το αναγνωριστικό ανήκει σε άτομο άλλου προγράμματος |
| 422 | invalidBody, invalidParameter |
βλ. errors (πεδίο του σώματος ή παράμετρος του ερωτήματος: τι είναι λάθος) |
| 429 | rateLimited |
περιμένετε Retry-After δευτερόλεπτα |
| 500 | internalError |
δοκιμάστε ξανά αργότερα· στην υποστήριξή μας αναφέρετε το incidentId |
Για προγράμματα και πράκτορες
- Αποφασίζετε με βάση το code και το reason, ποτέ με βάση το κείμενο του message· το errors είναι αντικείμενο πεδίο -> τι είναι λάθος.
- Επαναλαμβάνετε μόνο τα 429, 500 και certificatePdfNotReady, και μάλιστα μετά από Retry-After δευτερόλεπτα (διαφορετικά με αυξανόμενο διάστημα)· τα 4xx εκτός του 429 μην τα επαναλαμβάνετε χωρίς διόρθωση της κλήσης.
- Το POST /v1/users είναι idempotent ως προς το identifier (201 την πρώτη φορά, μετά 200)· το DELETE επιστρέφει 204 την πρώτη φορά και 404 μετά: και τα δύο μπορούν να επαναληφθούν με ασφάλεια.
- Τα webhooks τα αποδιπλασιάζετε με βάση το X-Responsiblo-Delivery· η σειρά των μηνυμάτων δεν είναι εγγυημένη, αποφασίζει η κατάσταση στο data.
Οδηγός δανείου
Ο οδηγός δανείου είναι σύντομο μάθημα για τον αιτούντα σε πάροχο δανείων: πριν από την υπογραφή της σύμβασης περνά από τρεις ενότητες, οκτώ πρακτικές καταστάσεις και ενδεχομένως κουίζ, όλα με τους αριθμούς της δικής του προσφοράς, και στο τέλος επιβεβαιώνει την προσφορά. Σε κάθε οθόνη μπορεί να ζητήσει εξήγηση. Την προσφορά τη στέλνετε μέσω του API, λαμβάνετε σύνδεσμο εισόδου και το αποτέλεσμα σας το ανακοινώνει το webhook.
Τον οδηγό δανείου τον ενεργοποιούμε κατόπιν συμφωνίας μαζί σας.
Ο αιτών είναι και εδώ μόνο το ψευδωνυμοποιημένο προφίλ σας από το POST /v1/users. Την προσφορά την προσδιορίζουν οι δικές σας αναφορές (externalApplicationId, offerReference) και τα έγγραφα μόνο σύνδεσμος με αποτύπωμα SHA-256, ποτέ όνομα, email, προσωπικός αριθμός, αριθμός λογαριασμού ή τηλέφωνο. Η responsiblo δεν εγκρίνει το δάνειο, δεν κατεβάζει ούτε αποθηκεύει τα έγγραφα, δεν επαληθεύει την ταυτότητα και δεν εκδίδει πιστοποιητικό για τον οδηγό.
- Δημιουργείτε το προφίλ του αιτούντος: POST /v1/users με το ψευδώνυμό σας.
- Στέλνετε την προσφορά: POST /v1/users/{identifier}/loan-offers· η απάντηση 201 φέρει το entryUrl.
- Το entryUrl το παραδίδετε στον αιτούντα μέσω του δικού σας επαληθευμένου καναλιού. Ο σύνδεσμος ισχύει 30 ημέρες και μπορεί να χρησιμοποιηθεί επανειλημμένα· ο οδηγός δείχνει τους αριθμούς της προσφοράς του.
- Το τέλος το μαθαίνετε μέσω webhook (loanGuide.completed, loanGuide.assistanceRequested και άλλα).
- Την κατάσταση τη διαβάζετε μέσω GET …/loan-offers/{offerReference}, την εγγραφή για τον φάκελό σας μέσω GET …/evidence. Τροποποιημένη προσφορά = νέα προσφορά με supersedes, ανακληθείσα αίτηση = POST …/cancel.
Μέχρι την ενεργοποίηση οι λειτουργίες του οδηγού απαντούν 404 notFound ή 409 loanGuideNotConfigured. Το δικαίωμα write στέλνει και ακυρώνει την προσφορά, το read διαβάζει την κατάσταση και το αρχείο τεκμηρίωσης.
POST /v1/users/{identifier}/loan-offers
Στέλνει προσφορά στο προφίλ του αιτούντος (δικαίωμα write). Η προαιρετική κεφαλίδα Idempotency-Key έχει 1 έως 255 ορατούς χαρακτήρες ASCII. Παράδειγμα: δάνειο 10 000 CZK, πληρωτέα 10 800 CZK με μία πληρωμή 30 ημέρες μετά την εκταμίευση, ΣΕΠΠΠ 155,10 %.
curl -X POST https://api.responsiblo.com/v1/users/applicant-30417/loan-offers \
-H "Authorization: Bearer $RSB_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: offer-30417-1" \
-d '{
"externalApplicationId": "APP-30417",
"offerReference": "OFF-30417-1",
"locale": "cs-CZ",
"currency": "CZK",
"principalMinor": 1000000,
"disbursedAmountMinor": 1000000,
"totalPayableMinor": 1080000,
"aprPercent": "155.10",
"interestRate": { "percent": "8", "period": "month" },
"repayment": {
"type": "singlePayment",
"amountMinor": 1080000,
"due": { "kind": "relative", "days": 30, "anchor": "disbursement" }
},
"documents": [
{ "role": "precontract_information", "reference": "DOC-PRE-30417", "title": "Předsmluvní informace",
"url": "https://documents.lender.example/pre/30417.pdf",
"sha256": "623f4a37e444268c076896d6c2f389b46f568d1a26539b013f2ba25d03846f72" },
{ "role": "contract_package", "reference": "DOC-CON-30417", "title": "Smlouva a podmínky",
"url": "https://documents.lender.example/contract/30417.pdf",
"sha256": "9c7bfe0077d1189914f0e1c483c961f4c5b36e9892385f3d2ab6168e0c088aa6" }
],
"validUntil": "2026-11-22T18:00:00Z"
}'
HTTP/1.1 201 Created
{
"offerReference": "OFF-30417-1",
"externalApplicationId": "APP-30417",
"offerStatus": "active",
"guideStatus": "created",
"validUntil": "2026-11-22T18:00:00Z",
"snapshotSha256": "8055bfa3c5f2c163691b85785eaf61221169a123bed67aff2c1dbaf2a8e44e7e",
"entryUrl": "https://your-company.responsiblo.com/entry/...",
"createdAt": "2026-11-17T09:14:05Z"
}
| Πεδίο | Υποχρεωτικό | Σημασία |
|---|---|---|
externalApplicationId |
ναι | Ο δικός σας αριθμός αίτησης, 1 έως 128 χαρακτήρες A-Z a-z 0-9 . _ : -· ποτέ διεύθυνση email. |
offerReference |
ναι | Η δική σας αναφορά προσφοράς, ίδιοι κανόνες με το externalApplicationId. |
locale |
ναι | Γλώσσα και χώρα του οδηγού: cs-CZ. |
currency |
ναι | Νόμισμα: CZK. |
principalMinor |
ναι | Ποσό του δανείου σε χαλέρ (εκατοστά της κορώνας), ακέραιος αριθμός από 1 έως 10 000 000 000. |
disbursedAmountMinor |
ναι | Ποσό εκταμίευσης σε χαλέρ· πρέπει να ισούται με το ποσό του δανείου. |
totalPayableMinor |
ναι | Συνολικό πληρωτέο ποσό σε χαλέρ· τουλάχιστον το ποσό του δανείου και ακριβώς το άθροισμα των πληρωμών. |
aprPercent |
ναι | ΣΕΠΠΠ σε ποσοστό ως κείμενο ("155.10"), υπολογισμένο και εγγυημένο από εσάς. Θετικό κόστος με ΣΕΠΠΠ 0 το API το απορρίπτει. |
interestRate |
όχι | Επιτόκιο {percent, period}, period = year, month ή day. |
repayment |
ναι | Αποπληρωμή: singlePayment {amountMinor, due} με ημερομηνία (kind date) ή αριθμό ημερών από την εκταμίευση (kind relative, 1 έως 365) ή installments {schedule: [{date, amountMinor}]} με 1 έως 360 δόσεις σε αύξουσα σειρά, καμία στο παρελθόν. Ο τύπος πρέπει να αντιστοιχεί στο προϊόν που έχει οριστεί για τον οδηγό σας. |
documents |
ναι | 2 έως 10 έγγραφα {role, reference, title, url, sha256}· καλυμμένοι ρόλοι που απαιτούν οι ρυθμίσεις του οδηγού σας (προεπιλογή precontract_information και contract_package). Το url μόνο HTTPS σε host που επιτρέπεται στις ρυθμίσεις του οδηγού σας, το πολύ 2 048 χαρακτήρες, χωρίς διαπιστευτήρια σύνδεσης· sha256 = 64 δεκαεξαδικοί χαρακτήρες που δηλώνετε εσείς. |
validUntil |
ναι | Ισχύς της προσφοράς, RFC 3339 με χρονική μετατόπιση, στο μέλλον και το πολύ 7 ημέρες μπροστά. |
supersedes |
όχι | offerReference ενεργής προσφοράς του ίδιου προφίλ, την οποία αντικαθιστά η νέα προσφορά. |
returnUrl |
όχι | Προαιρετικό: διεύθυνση στην οποία η σελίδα Ολοκληρώθηκε επιστρέφει τον αιτούντα μετά την ολοκλήρωση του οδηγού. Μόνο απόλυτη HTTPS, το πολύ 2 048 χαρακτήρες, χωρίς διαπιστευτήρια σύνδεσης· τα σύμβολα {offerReference} και {externalApplicationId} τα αντικαθιστούμε με τις αναφορές της προσφοράς. Χωρίς αυτήν ισχύει η διεύθυνση επιστροφής από τις ρυθμίσεις του οδηγού σας. |
Το ίδιο σώμα ξανά (με τις ίδιες αναφορές ή το ίδιο Idempotency-Key) επιστρέφει 200 με την υπάρχουσα προσφορά και νέο entryUrl· διαφορετικό σώμα με αυτές επιστρέφει 409 offerConflict. Το προφίλ έχει μία ενεργή προσφορά: επόμενη χωρίς supersedes επιστρέφει 409 activeOfferExists, λανθασμένο supersedes 409 notSupersedable. Οι ρυθμίσεις του οδηγού σας (κουίζ, επικοινωνία) κλειδώνονται εκείνη τη στιγμή στην προσφορά.
Κατάσταση, αρχείο τεκμηρίωσης και ακύρωση
GET /v1/users/{identifier}/loan-offers/{offerReference}- κατάσταση (δικαίωμα read): offerStatus (active, expired, superseded, cancelled), guideStatus (created, in_progress, completed), ολοκληρωμένες ενότητες, πρακτικό μέρος, κουίζ (null όταν είναι απενεργοποιημένο) και οι στιγμές της παρουσίασης της προσφοράς, της επιβεβαίωσης και του αιτήματος εξήγησης. Ποτέ απαντήσεις, τιμές της προσφοράς ή ο σύνδεσμος. Η ολοκλήρωση παραμένει, ακόμη κι αν η προσφορά λήξει αργότερα.GET /v1/users/{identifier}/loan-offers/{offerReference}/evidence- εγγραφή για τον φάκελό σας (δικαίωμα read): schemaVersion loan-guide-evidence/1, στιγμιότυπο της προσφοράς σας με αποτύπωμα snapshotSha256, έκδοση του μαθήματος με τα αποτυπώματα των ενοτήτων, τα συμβάντα με τη σειρά sequence, κάθε απάντηση με όλες τις προσπάθειες, η επιβεβαίωση και τα limitations, δηλαδή τι δεν αποδεικνύει η εγγραφή (παρουσιάστηκε δεν σημαίνει διαβάστηκε, την ταυτότητα τη βεβαιώνετε εσείς, τα έγγραφα μόνο μέσω συνδέσμου, κανένα πιστοποιητικό, καμία έγκριση δανείου).POST /v1/users/{identifier}/loan-offers/{offerReference}/cancel- ακυρώνει ενεργή προσφορά (δικαίωμα write), reasonCode = withdrawn_by_provider ή application_closed· το 200 επιστρέφει την κατάσταση, προσφορά που δεν είναι ενεργή ή έχει ολοκληρωμένο οδηγό επιστρέφει 409 notActive.
curl https://api.responsiblo.com/v1/users/applicant-30417/loan-offers/OFF-30417-1 -H "Authorization: Bearer $RSB_KEY"
{
"offerReference": "OFF-30417-1",
"externalApplicationId": "APP-30417",
"offerStatus": "active",
"guideStatus": "completed",
"quizEnabled": true,
"lessonsCompleted": 3,
"lessonsTotal": 3,
"practiceCompleted": true,
"quizPassed": true,
"offerPresentedAt": "2026-11-17T18:32:47Z",
"confirmedAt": "2026-11-17T18:34:02Z",
"completedAt": "2026-11-17T18:34:02Z",
"assistanceRequested": false,
"assistanceRequestedAt": null,
"validUntil": "2026-11-22T18:00:00Z",
"evidenceErased": false,
"...": "..."
}
curl -X POST https://api.responsiblo.com/v1/users/applicant-30417/loan-offers/OFF-30417-1/cancel \
-H "Authorization: Bearer $RSB_KEY" \
-H "Content-Type: application/json" \
-d '{"reasonCode":"withdrawn_by_provider"}'
Το ?externalApplicationId= χρειάζεται μόνο όταν μία offerReference ανήκει σε περισσότερες αιτήσεις του προφίλ (διαφορετικά 409 ambiguousOfferReference).
Webhooks του οδηγού
Το webhook του προγράμματος (βλ. Webhooks) λαμβάνει τα συμβάντα του οδηγού χωρίς ξεχωριστή συνδρομή. Η υπογραφή, η παράδοση και οι επαναλήψεις είναι ίδιες με τα υπόλοιπα συμβάντα· τα data φέρουν identifier, offerReference, externalApplicationId, guideStatus, occurredAt και sequence (σειρά των συμβάντων μίας προσφοράς), ποτέ το αρχείο τεκμηρίωσης, τιμές της προσφοράς ή τον σύνδεσμο εισόδου.
| Συμβάν | Πότε |
|---|---|
loanGuide.completed |
ο αιτών ολοκλήρωσε τον οδηγό και επιβεβαίωσε την προσφορά |
loanGuide.assistanceRequested |
ο αιτών ζήτησε εξήγηση (τηλεφωνήστε του) |
loanGuide.expired |
το validUntil της προσφοράς πέρασε |
loanGuide.superseded |
την προσφορά την αντικατέστησε νέα (supersedes) |
loanGuide.cancelled |
ακυρώσατε την προσφορά |
POST https://your-server.example/responsiblo/webhook
Content-Type: application/json
X-Responsiblo-Event: loanGuide.completed
X-Responsiblo-Delivery: 0f6e2a4c-91d3-4b8e-a7c5-3e2d1b9f6a08
X-Responsiblo-Signature: t=1794940447,v1=8b2d...4c
{
"id": "0f6e2a4c-91d3-4b8e-a7c5-3e2d1b9f6a08",
"type": "loanGuide.completed",
"createdAt": "2026-11-17T18:34:07Z",
"apiVersion": "1.3.2",
"program": "your-program",
"data": {
"identifier": "applicant-30417",
"offerReference": "OFF-30417-1",
"externalApplicationId": "APP-30417",
"guideStatus": "completed",
"occurredAt": "2026-11-17T18:34:02Z",
"sequence": 23
}
}
Κάθε συμβάν φτάνει σε ένα webhook το πολύ μία φορά (κλειδί idempotency = X-Responsiblo-Delivery). Webhook που δημιουργήθηκε αργότερα δεν αναπαράγει παλαιότερα συμβάντα και συμβάντα παλαιότερα των 28 ημερών δεν ανακοινώνονται πλέον.
Διατήρηση του αρχείου τεκμηρίωσης
Όταν η διαδρομή της προσφοράς τελειώσει (ολοκληρωμένη, ακυρωμένη, ληγμένη ή αντικατεστημένη προσφορά), ξεκινά η περίοδος διατήρησης από τις ρυθμίσεις του οδηγού σας (προεπιλογή 30 ημέρες). Στη συνέχεια το αρχείο τεκμηρίωσης διαγράφεται: το GET …/evidence επιστρέφει 410 evidenceErased και η κατάσταση συνεχίζει να απαντά με evidenceErased: true, τις αναφορές και τις στιγμές. Ενεργή προσφορά δεν διαγράφεται ποτέ. Το αρχείο τεκμηρίωσης που πρέπει να διατηρήσετε κατεβάστε το αμέσως μετά το loanGuide.completed.
Σφάλματα του οδηγού
Τα σφάλματα έχουν τη μορφή του API παραπάνω. Επιπλέον για τον οδηγό:
| HTTP | reason | Τι να κάνετε |
|---|---|---|
| 404 | offerNotFound |
το προφίλ δεν έχει τέτοια προσφορά (userNotFound = το προφίλ δεν υπάρχει) |
| 409 | offerConflict, activeOfferExists, notSupersedable |
οι αναφορές ή το Idempotency-Key ανήκουν ήδη σε άλλο σώμα ή το προφίλ έχει άλλη ενεργή προσφορά: στείλτε supersedes |
| 409 | loanGuideNotConfigured |
ο οδηγός δεν είναι ενεργοποιημένος για το πρόγραμμά σας: γράψτε μας |
| 409 | ambiguousOfferReference |
προσθέστε ?externalApplicationId= |
| 409 | notActive |
η προσφορά δεν είναι ενεργή ή έχει ολοκληρωμένο οδηγό |
| 410 | evidenceErased |
το αρχείο τεκμηρίωσης διαγράφηκε μετά την περίοδο διατήρησης, η κατάσταση παραμένει |
| 422 | invalidOffer |
errors = {διαδρομή: κωδικός[,κωδικός]} με τη διαδρομή στο σώμα (repayment.schedule[2].date, documents[0].url)· οι κωδικοί στον πίνακα παρακάτω |
| 422 | invalidBody |
supersedes, Idempotency-Key ή σώμα της ακύρωσης |
errors | Κωδικοί του σφάλματος invalidOffer |
|---|---|
required |
το πεδίο λείπει |
invalidFormat |
λανθασμένη μορφή (τύπος, μοτίβο, μήκος, σύνδεσμος χωρίς HTTPS ή με διαπιστευτήρια σύνδεσης) |
outOfRange |
εκτός του επιτρεπόμενου εύρους (ποσό, αριθμός εγγράφων, δόσεων ή ημερών) |
notEqualPrincipal |
το ποσό εκταμίευσης δεν ισούται με το ποσό του δανείου |
sumMismatch |
το άθροισμα των πληρωμών δεν ισούται με το συνολικό πληρωτέο ποσό |
belowPrincipal |
το συνολικό πληρωτέο ποσό είναι μικρότερο από το ποσό του δανείου |
aprContradiction |
ΣΕΠΠΠ 0 με θετικό κόστος |
typeMismatch |
ο τύπος αποπληρωμής δεν αντιστοιχεί στο προϊόν που έχει οριστεί για τον οδηγό σας |
missingRole |
λείπει έγγραφο με ρόλο που απαιτούν οι ρυθμίσεις του οδηγού σας |
hostNotAllowed |
ο σύνδεσμος του εγγράφου οδηγεί σε host που δεν επιτρέπουν οι ρυθμίσεις του οδηγού σας |
notAscending |
οι ημερομηνίες των δόσεων δεν είναι σε αύξουσα σειρά ή επαναλαμβάνονται |
inPast |
η ημερομηνία δόσης ή το validUntil βρίσκεται στο παρελθόν |
tooFar |
το validUntil είναι περισσότερο από 7 ημέρες μπροστά |
unsupported |
μη υποστηριζόμενη τιμή (locale, currency, type, period, kind) |
unknownField |
πεδίο που το API δεν γνωρίζει |
looksLikeEmail |
η αναφορά μοιάζει με διεύθυνση email |
Το σφάλμα δεν επαναλαμβάνει ποτέ την τιμή που στείλατε. Παράδειγμα: η ίδια προσφορά με πληρωμή 10 700 CZK αντί για 10 800 CZK και ισχύ 9 ημερών:
"repayment": { "type": "singlePayment", "amountMinor": 1070000, "due": { "kind": "relative", "days": 30, "anchor": "disbursement" } },
"validUntil": "2026-11-26T18:00:00Z"
HTTP/1.1 422 Unprocessable Entity
{
"status": "error",
"code": 422,
"reason": "invalidOffer",
"message": "The offer contains invalid data.",
"errors": {
"repayment.amountMinor": "sumMismatch",
"validUntil": "tooFar"
}
}
Όρια
120 κλήσεις ανά λεπτό ανά κλειδί. Μετά από 30 απορριφθέντα κλειδιά από μία διεύθυνση μέσα σε δέκα λεπτά η διεύθυνση περιμένει 10 λεπτά.
Το αρχείο καταγραφής κλήσεων (χωρίς σώματα, το αναγνωριστικό μόνο ως αποτύπωμα SHA-256) το διατηρούμε 180 ημέρες, τα παραδοθέντα και τα εγκαταλειμμένα μηνύματα webhooks 30 ημέρες.
Κατάσταση και σύμβαση διεπαφής
GET /v1/status- χωρίς κλειδί, επιστρέφει {"status":"ok","version":"1.3.2"}GET /openapi- χωρίς κλειδί, έγγραφο OpenAPI 3 του API συνεργατών
Sandbox (περιβάλλον δοκιμών)
Το δοκιμαστικό κλειδί rsb_test_... ανοίγει το δοκιμαστικό σας πρόγραμμα με το ίδιο μάθημα. Τα άτομα σε αυτό λήγουν μετά από 7 ημέρες· το webhook του δοκιμαστικού προγράμματος είναι χωριστό από το παραγωγικό.
Ιστορικό εκδόσεων
- 1.3.2 (2026-11) - Κάθε λειτουργία του εγγράφου OpenAPI έχει όνομα και περιγραφή και οι λειτουργίες είναι χωρισμένες σε ομάδες. Το /v1/status και τα webhooks αναφέρουν την έκδοση 1.3.2. Οι μορφές των αιτημάτων και των απαντήσεων δεν αλλάζουν.
- 1.3.1 (2026-10) - Διορθώσεις χωρίς αλλαγή των endpoints και των απαντήσεών τους.
- 1.3.0 (2026-10) - Οδηγός δανείου: POST /v1/users/{identifier}/loan-offers, κατάσταση, αρχείο τεκμηρίωσης και ακύρωση της προσφοράς, webhooks loanGuide.*, διατήρηση του αρχείου τεκμηρίωσης. Προαιρετική διεύθυνση επιστροφής returnUrl στην προσφορά.
- 1.2.0 (2026-10) - GET /v1/users με σελιδοποίηση, πιστοποιητικό του ατόμου (πεδίο certificate, GET /v1/users/{identifier}/certificate, συμβάν certificate.issued), DELETE /v1/users/{identifier} (ανωνυμοποίηση), αναγνωριστικό το πολύ 64 χαρακτήρων, διατήρηση του αρχείου καταγραφής.
- 1.1.0 (2026-10) - Κλειδιά API, POST /v1/users, GET /v1/users/{identifier} με ?include=detail, σύνδεσμος εισόδου, webhooks, ενιαία μορφή σφαλμάτων, δημόσια κατάσταση και OpenAPI, όρια.
- 1.0.0 (2024) - GET /v1/user/{identifier} με JWT κλειδιού συνεργάτη.
Θέλετε το API για την επιχείρησή σας; Γράψτε μας