API και webhooks

Πού θα το βρείτε

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

Η οθόνη ξεκινά με τις έτοιμες συνδέσεις CRM (Ενσωματώσεις CRM)· τα tokens και τα webhooks που περιγράφονται εδώ βρίσκονται από κάτω, στην ενότητα API και webhooks.

Το token

Πατήστε Δημιουργία token, δώστε του ένα όνομα που θα αναγνωρίζετε αργότερα (ώστε να ξέρετε ποιο σύστημα το χρησιμοποιεί) και επιλέξτε τι επιτρέπεται να κάνει: να διαβάζει πρότυπα, να δημιουργεί έγγραφα, να δουλεύει με υποθέσεις.

Το ίδιο το token εμφανίζεται μία φορά, αμέσως μετά τη δημιουργία του: αποθηκεύουμε μόνο ένα hash του, οπότε το να το εμφανίσουμε δεύτερη φορά είναι κάτι που δεν μπορούμε να κάνουμε ούτε εμείς. Αντιγράψτε το κατευθείαν στις ρυθμίσεις του συστήματός σας.

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

Τι μπορεί να κάνει το API

Το σύστημά σας μπορεί:

• να ανοίξει μια υπόθεση και να ανεβάσει σαρώσεις σε αυτήν·
• να δημιουργήσει ένα έγγραφο από πρότυπο με τις τιμές ήδη συμπληρωμένες·
• να ρωτήσει σε ποιο στάδιο βρίσκεται ένα έγγραφο·
• να πάρει όλες τις τιμές μαζί με τη σάρωση από την οποία διαβάστηκε η καθεμία·
• να λάβει έναν σύνδεσμο σύντομης διάρκειας προς το έτοιμο αρχείο.

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

Webhooks

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

Κάθε αίτημα υπογράφεται με την κεφαλίδα X-DocuTract-Signature, και το μυστικό που επαληθεύει την υπογραφή εμφανίζεται μία φορά, όπως και το token. Το σύστημά σας πρέπει να ελέγξει την υπογραφή και να απαντήσει με κωδικό 2xx. Αν απαντήσει οτιδήποτε άλλο ή δεν απαντήσει καθόλου, δοκιμάζουμε ξανά: μετά από ένα λεπτό, μετά από πέντε, μετά από μισή ώρα, μετά από δύο ώρες και μετά από δέκα, και μετά σταματάμε.

Όταν κάτι δεν έφτασε

Το κουμπί Παραδόσεις δείχνει το ιστορικό: ποιο συμβάν στείλαμε, πότε, πόσες φορές, ποιος κωδικός απάντησης επέστρεψε και την αρχή του σώματος της απάντησης. Αυτή είναι η απάντηση στο «το σύστημά μας δεν έλαβε τίποτα»: είναι καταγεγραμμένο ότι απάντησε 500 τέσσερις φορές στις 14:12.

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

Zapier, Make και n8n

Οι πλατφόρμες no-code (υπηρεσίες όπου μια ενσωμάτωση στήνεται χωρίς προγραμματισμό) εγγράφονται μόνες τους στα συμβάντα μας, μέσω του τμήματος REST hooks του API, οπότε κανείς δεν χρειάζεται να αντιγράψει τις διευθύνσεις τους στο DocuTract. Δώστε στην πλατφόρμα ένα token με τα δικαιώματα webhooks:read και webhooks:write, καθώς και όσα χρειάζονται οι ενέργειές της (για παράδειγμα templates:read και documents:write).

• Το POST /api/v1/hooks με {"event": "document.ready", "target_url": "https://…"} εγγράφει μια διεύθυνση σε ένα συμβάν. Η απάντηση περιέχει το id της συνδρομής και, μία φορά, το secret υπογραφής της.
• Το GET /api/v1/hooks απαριθμεί τις συνδρομές που δημιουργήθηκαν έτσι· το DELETE /api/v1/hooks/{id} αφαιρεί μία.
• Το GET /api/v1/hooks/events απαριθμεί τα συμβάντα: document.ready, document.failed, case.ready, finding.raised, intake.uploaded.
• Το GET /api/v1/hooks/samples/{event} επιστρέφει ένα παράδειγμα περιεχομένου, που η πλατφόρμα δείχνει στον «δοκιμαστικό ενεργοποιητή» της πριν συμβεί οποιοδήποτε πραγματικό συμβάν.

Μια συνδρομή είναι μια κανονική διεύθυνση webhook: υπογράφεται, επαναλαμβάνεται και καταγράφεται με τον ίδιο τρόπο και φαίνεται στη λίστα Webhooks. Σταματά όταν το token που τη δημιούργησε ανακληθεί ή λήξει, ή όταν η πλατφόρμα απαντήσει σε μια παράδοση με 410 Gone.

Έτσι μοιάζει το document.ready:

{
  "document_id": "00000000-0000-4000-8000-000000000001",
  "reference": "DOC-26-0001",
  "template_id": "00000000-0000-4000-8000-000000000002",
  "template_version": 1,
  "event": "document.ready",
  "occurred_at": "2026-01-15T10:30:00+00:00"
}

και έτσι το case.ready:

{
  "case_id": "00000000-0000-4000-8000-000000000003",
  "title": "Sample case",
  "documents": [
    { "id": "00000000-0000-4000-8000-000000000001", "reference": "DOC-26-0001" }
  ],
  "event": "case.ready",
  "occurred_at": "2026-01-15T10:30:00+00:00"
}

Τα πεδία ενός προτύπου

Το GET /api/v1/templates/{id}/fields (δικαίωμα templates:read) απαριθμεί τι χρειάζεται ένα πρότυπο: το key κάθε πεδίου (με βάση το οποίο δίνονται τα values στο POST /api/v1/documents), το label του, από πού συμπληρώνεται, και το fillable, που είναι false για πεδίο που το DocuTract συμπληρώνει μόνο του, όπως μια ημερομηνία. Μια φόρμα στο Zapier ή στο Make χτίζεται από αυτή τη λίστα, οπότε ταιριάζει πάντα με το πρότυπο όπως είναι τώρα.

Αναζητήσεις

Μερικές κλήσεις υπάρχουν ώστε ένα σύστημα, ή μια πλατφόρμα no-code, να βρίσκει ό,τι χρειάζεται χωρίς να μαντεύει:

• GET /api/v1/me (χωρίς δικαίωμα) επιστρέφει τον χώρο εργασίας στον οποίο ανήκει το token, το πρόγραμμά του, καθώς και το όνομα και τα δικαιώματα του ίδιου του token. Είναι ο απλούστερος τρόπος να ελέγξετε ότι ένα token λειτουργεί.
• GET /api/v1/documents (δικαίωμα documents:read) εμφανίζει τα έγγραφα, πρώτα τα νεότερα. Περιορίστε με reference (ο ακριβής αριθμός DOC-…), status ή template_id· το limit φτάνει έως 100, προεπιλογή 25.
• GET /api/v1/cases (δικαίωμα cases:read) εμφανίζει τις νεότερες υποθέσεις, αν θέλετε μόνο όσες έχουν ένα συγκεκριμένο status, με το ίδιο limit. Κάθε υπόθεση έχει πλέον και created_at.
• GET /api/v1/case-types (δικαίωμα cases:read) απαριθμεί τους τύπους υποθέσεων από τους οποίους ανοίγει μια υπόθεση.
• GET /api/v1/templates?name=… κρατά μόνο τα πρότυπα των οποίων το όνομα περιέχει το κείμενο, ανεξαρτήτως πεζών και κεφαλαίων.

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

Ποιο πρόγραμμα

Το API και τα webhooks είναι μέρος του προγράμματος Team. Σε οποιοδήποτε άλλο πρόγραμμα, τα tokens και οι διευθύνσεις που έχετε ήδη δημιουργήσει παραμένουν ορατά και μπορούν να ανακληθούν, αλλά δεν εκδίδονται νέα, και οι κλήσεις που γίνονται με token δεν εξυπηρετούνται πλέον. Συγκρίνετε τα προγράμματα στη σελίδα τιμών.