Vigilae Connect

Ένα API που το διαβάζετε πριν υπογράψετε.

Η προδιαγραφή είναι δημόσια, οι επιφάνειες ουδέτερες, η υπογραφή των webhooks επαληθεύεται σε δέκα γραμμές από την πλευρά σας. Αυτή η σελίδα τεκμηριώνει ό,τι εκθέτει το API σήμερα — τίποτα περισσότερο, και αυτό είναι εσκεμμένο: ό,τι δεν έχει παραδοθεί δεν τεκμηριώνεται.

Προδιαγραφή OpenAPI αναγνώσιμη χωρίς κλειδί ή λογαριασμό
Ποτέ αναφορά ύποπτης συναλλαγής, ποτέ αυτούσια δεδομένα πελατών
Υπογεγραμμένα webhooks, επαληθεύσιμα εκτός Vigilae

Διαβάστε την προδιαγραφή Αναφορά σφαλμάτων

Σερβίρεται από το ίδιο το API: η σύμβαση που διαβάζετε είναι αυτή που εκτελείται.

Η περίμετρος

Ουδέτερες επιφάνειες, εκ κατασκευής.

Το API εκθέτει ό,τι μπορεί να καταναλώσει ένας integrator χωρίς να αγγίξει το απόρρητο των φακέλων: το ημερολόγιο παρακολούθησης και μετρητές. Το περιεχόμενο ενός φακέλου επαγρύπνησης, τα έγγραφα, οι αναφορές ύποπτων συναλλαγών δεν διέρχονται από αυτό το API — όχι περιορισμός πακέτου, αλλά η αρχιτεκτονική.

Ημερολόγιο παρακολούθησης

Τα συμβάντα pKYC του γραφείου — ληγμένο έγγραφο, αλλαγή πραγματικού δικαιούχου, επανέλεγχος (re-screening) προς εξέταση — σε ουδέτερη μορφή: ακολουθία, τύπος, σοβαρότητα, ημερομηνία. Αποκρίσεις πάντοτε με όριο τα 500 συμβάντα.

Συγκεντρωτικά χαρτοφυλακίου

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

Χαρακτηρισμός

Η μόνη εγγραφή: ο χαρακτηρισμός ενός συμβάντος του ημερολογίου (κατάσταση qualifie ή clos, διάθεση planifie, traite ή ecarte). Απαιτεί το scope εγγραφής — το ελάχιστο προνόμιο είναι ο κανόνας, όχι επιλογή.

Το API είναι σχεδιασμένο server-to-server: ένα κλειδί σε κώδικα που φτάνει στον browser είναι δημοσιευμένο κλειδί. Αναθέστε το κλειδί σε server-side proxy, ποτέ στη σελίδα.

Κλειδιά

Κλειδιά με εμβέλειες, εμφανίζονται μία φορά, ανακαλούνται αμέσως.

Μορφή. Κάθε κλειδί ξεκινά με vgk_ και αποστέλλεται ως Authorization: Bearer vgk_…. Το μυστικό εμφανίζεται μόνο κατά τη δημιουργία: δεν κρατάμε τίποτα πέρα από τη σύνοψή του σε SHA-256.
Εμβέλειες (scopes). lecture (ανάγνωση, η προεπιλογή) και ecriture (εγγραφή). Ένα κλειδί χωρίς το απαιτούμενο scope λαμβάνει 403 — βλ. #scopes.
Λήξη. Ένα έτος μετά τη δημιουργία (ορατή στην κονσόλα του γραφείου). Ένα ληγμένο κλειδί λαμβάνει ρητό 401 — βλ. #cle-expiree.
Ρυθμός. 60 αιτήματα/λεπτό ανά κλειδί (παραμετροποιήσιμος ανά κλειδί). Ένα 429 φέρει Retry-After και τις κεφαλίδες X-RateLimit-Limit / -Remaining / -Reset.
Ανάκληση. Άμεση, από την κονσόλα. Η αντιστοίχιση γίνεται μέσω σύνοψης: τα κλειδιά δεν μπορούν να απαριθμηθούν.

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

Τρεις κλήσεις curl και τα έχετε δει όλα.

# Υγεία + πιστοποίηση κλειδιού
curl -s https://vigilae.org/api/v1/sante \
  -H "Authorization: Bearer vgk_your_key"

# Ημερολόγιο παρακολούθησης, από την αρχή, σε σελίδες των 100
curl -s "https://vigilae.org/api/v1/evenements?depuisSeq=0&limite=100" \
  -H "Authorization: Bearer vgk_your_key"

# Χαρακτηρισμός του συμβάντος 42 (scope εγγραφής)
curl -s -X POST https://vigilae.org/api/v1/evenements/42/qualifier \
  -H "Authorization: Bearer vgk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"statut":"qualifie","disposition":"traite"}'

Σελιδοποίηση, σε έναν κανόνα

Περνάτε depuisSeq (0 στην πρώτη κλήση) και limite (με ανώτατο όριο 500): η απόκριση ταξινομείται κατά αύξουσα seq και επιστρέφει prochainSeq, που το ξαναπερνάτε ως έχει στην επόμενη κλήση. Μια σελίδα μικρότερη από το limite σημαίνει το τέλος του ημερολογίου — το prochainSeq μένει τότε σταθερό και χρησιμεύει ως δρομέας polling. Χωρίς depuisSeq, λαμβάνετε την προβολή «τα πιο πρόσφατα πρώτα», με όριο τα 500.

Το χαρτοφυλάκιο ερωτάται στο /api/v1/portefeuille/agregats — μετρητές, μία απόκριση, χωρίς σελιδοποίηση.

Webhooks

Υπογεγραμμένα, χρονοσφραγισμένα, παραδιδόμενα τουλάχιστον μία φορά.

Αντί να κάνετε polling στο ημερολόγιο, λάβετέ το: η Vigilae παραδίδει τα συμβάντα στο URL σας, με τη σειρά, σε παρτίδες έως 100. Η παράδοση είναι at-least-once — ο δρομέας προχωρά μόνο με το δικό σας 2xx, παρτίδα προς παρτίδα — και η ταυτοδυναμία βασίζεται στο seq: επεξεργαστείτε κάθε ακολουθία ακριβώς μία φορά (#idempotence).

Επαλήθευση της υπογραφής

Κάθε παράδοση φέρει την κεφαλίδα x-vigilae-signature: t=<unix>,v1=HMAC-SHA256(secret, t + "." + body). Επανυπολογίστε το v1 από το ακατέργαστο σώμα που λάβατε, και απορρίψτε κάθε χρονοσφραγίδα t πέραν των 5 λεπτών: αυτή είναι η προστασία anti-replay. Κατά τη διάρκεια εναλλαγής μυστικού, η κεφαλίδα φέρει ένα v1 ανά ακόμη-έγκυρο μυστικό (επικάλυψη 24 ωρών): αποδεχθείτε αν οποιοδήποτε από αυτά ταιριάζει.

// Node — επαλήθευση υπογραφής (χωρίς εξάρτηση)
import { createHmac, timingSafeEqual } from 'node:crypto';

export function signatureValid(header, rawBody, secrets, toleranceMs = 5 * 60 * 1000) {
  const t = Number((/(?:^|,)t=(\d+)/.exec(header) || [])[1]);
  if (!t || Math.abs(Date.now() - t * 1000) > toleranceMs) return false; // anti-replay
  const received = [...header.matchAll(/v1=([0-9a-f]{64})/g)].map((m) => m[1]);
  return [].concat(secrets).some((secret) => {
    const expected = createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex');
    return received.some((r) => r.length === expected.length
      && timingSafeEqual(Buffer.from(r), Buffer.from(expected)));
  });
}

# Python — η ίδια επαλήθευση
import hmac, hashlib, re, time

def signature_valid(header: str, raw_body: bytes, secrets, tolerance_s: int = 300) -> bool:
    m = re.search(r"(?:^|,)t=(\d+)", header)
    if not m or abs(time.time() - int(m.group(1))) > tolerance_s:
        return False  # anti-replay
    received = re.findall(r"v1=([0-9a-f]{64})", header)
    for secret in secrets:
        expected = hmac.new(secret.encode(), m.group(1).encode() + b"." + raw_body,
                            hashlib.sha256).hexdigest()
        if any(hmac.compare_digest(expected, r) for r in received):
            return True
    return False

Μεταβατικό: η παλαιά μορφή sha256=HMAC(body) εκπέμπεται ακόμη στην κεφαλίδα x-vigilae-signature-legacy για τους δέκτες που είναι ήδη σε λειτουργία· η κατάργησή της προγραμματίζεται με τα webhooks v2. Οι νέοι δέκτες επαληθεύουν το χρονοσφραγισμένο σχήμα παραπάνω, όχι το παλαιό.

Η εναλλαγή ενεργοποιείται από την κονσόλα (POST /connect/webhook/rotation από την πλευρά της εφαρμογής): για 24 ώρες το παλαιό μυστικό εξακολουθεί να υπογράφει — χρόνος για να αναπτύξετε το νέο από την πλευρά σας χωρίς παράθυρο αστοχίας.

Περιβάλλον δοκιμών

Sandbox: κατόπιν αιτήματος.

Δεν υπάρχει ακόμη sandbox αυτόματης πρόσβασης — προτιμούμε να σας το πούμε εδώ παρά να το ανακαλύψετε μόνοι σας. Γράψτε στο contact@vigilae.org (θέμα «API access»): ανοίγουμε ένα δοκιμαστικό γραφείο με πλασματικά δεδομένα για όσο διαρκεί η ενσωμάτωσή σας, και παραμένουμε διαθέσιμοι όσο αυτή προχωρά.

Κάθε κατηγορία σφάλματος του API έχει σταθερή διεύθυνση στην αναφορά σφαλμάτων: #authentification, #scopes, #cloisonnement, #debit, #signature… Οι αποκρίσεις σφάλματος του API θα παραπέμπουν σε αυτές τις άγκυρες.

Το API δεν εκθέτει ούτε αναφορές ύποπτων συναλλαγών ούτε αυτούσια δεδομένα πελατών, εκ κατασκευής (άρθ. L.561-18 του γαλλικού CMF). Καμία απόφαση επαγρύπνησης δεν λαμβάνεται από το API: εκθέτει και χαρακτηρίζει συμβάντα· ο επαγγελματίας αποφασίζει.