Οδηγοί

Τιμολόγια

Ο πράκτορας μπορεί να διαβάσει ένα εκδοθέν τιμολόγιο από το συνδεδεμένο Fakturoid ή ABRA Flexi και να το χρησιμοποιήσει ως βάση για μια υπενθυμιστική κλήση - ποτέ δεν εκδίδει τιμολόγιο ούτε το χαρακτηρίζει ως εξοφλημένο.

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

• Αναζητά εκδοθέντα τιμολόγια με βάση τον αριθμό ή την επωνυμία της εταιρείας (list_invoices).
• Φορτώνει την πρόσφατη κατάσταση ενός τιμολογίου απευθείας από τον πάροχο (get_invoice).
• Δημιουργεί υπενθυμιστική Εργασία (taskType: "invoice") που παραπέμπει στο τιμολόγιο.

Δεν μπορεί να

• Δεν εκδίδει, δεν επεξεργάζεται και δεν διαγράφει κανένα τιμολόγιο.
• Δεν χαρακτηρίζει ένα τιμολόγιο ως εξοφλημένο - αυτό μπορούν να το κάνουν μόνο το Fakturoid ή το ABRA.
• Δεν συνδέει το Fakturoid με διαπιστευτήρια - η σύνδεση γίνεται μόνο μέσω OAuth στο πρόγραμμα περιήγησης.

Σύνδεση λογαριασμού

Και οι δύο υπηρεσίες τιμολόγησης διαχειρίζονται στο ίδιο σημείο με τα ημερολόγια, στην πύλη, στην ενότητα Δεδομένα και ενσωματώσεις (/propojeni). Τα list_integrations και GET /v1/integrations είναι μόνο για ανάγνωση: επιστρέφουν την κατάσταση σύνδεσης και ενδεχομένως ένα connectUrl, αλλά δεν συνδέουν τίποτα από μόνα τους. Λεπτομερής διαδικασία για τον πράκτορα (list_integrations -> connectUrl -> βήμα στο πρόγραμμα περιήγησης) υπάρχει στη σελίδα Συνδέσεις.

Fakturoid

Συνδέεται αποκλειστικά με σύνδεση OAuth στο πρόγραμμα περιήγησης - το POST /v1/integrations με provider: "fakturoid" απορρίπτεται από το REST με το σφάλμα integration_unsupported, διαπιστευτήρια δεν μπορούν να σταλούν εδώ. Όταν ο λογαριασμός έχει περισσότερες εταιρείες με τιμολόγηση, μετά τη σύνδεση το πρόγραμμα περιήγησης επιστρέφει στη σελίδα Δεδομένα και ενσωματώσεις του volai (/propojeni, ή /en/connections στα αγγλικά) και μόνο εκεί εμφανίζεται η επιλογή εταιρείας - η εγγραφή στο integrations δημιουργείται μόνο μετά από αυτή την επιλογή. Το ready για το fakturoid στο GET /v1/integrations αναφέρει μόνο ότι το volai έχει ρυθμισμένα διαπιστευτήρια OAuth για το Fakturoid (FAKTUROID_CLIENT_ID κ.ά.) - ΟΧΙ ότι ένας συγκεκριμένος λογαριασμός είναι ήδη συνδεδεμένος. Αν η σύνδεση έχει ολοκληρωθεί, ο πράκτορας το καταλαβαίνει από το ότι εμφανίζεται στο πεδίο integrations.

ABRA Flexi

Συνδέεται με διαπιστευτήρια, όπως το Apple Calendar: POST /v1/integrations με {provider: "abra-flexi", baseUrl, company, username, password}. Η διεύθυνση του διακομιστή (baseUrl) πρέπει να ταιριάζει ακριβώς με τη διεύθυνση που έχει εγκρίνει εκ των προτέρων ο διαχειριστής της πλατφόρμας (ABRA_FLEXI_ALLOWED_HOSTS) - οποιαδήποτε άλλη επιστρέφει σφάλμα.

Ανάγνωση τιμολογίων

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

• list_invoices({integrationId, search?}) - το search (έως 100 χαρακτήρες) αναζητά στον πάροχο με βάση τον αριθμό παραστατικού ή την επωνυμία της εταιρείας· επιστρέφει τις πρώτες 40 γραμμές στο Fakturoid ή 50 στο ABRA, χωρίς σελιδοποίηση. Όταν τα αποτελέσματα είναι πολλά, περιορίστε το search.
• get_invoice({integrationId, invoiceId}) - το invoiceId είναι το externalId που επιστρέφει το list_invoices, αυτούσιο. Επιστρέφει την πιο πρόσφατη κατάσταση απευθείας από τον πάροχο, όχι ό,τι θυμάται το volai.

Ισοδύναμα REST: GET /v1/integrations/{id}/invoices?search=... και GET /v1/integrations/{id}/invoices/{invoiceId}.

Το status είναι paid, unpaid, overdue ή unknown· το amountDueMinor είναι ακέραιος αριθμός στις μικρότερες μονάδες του ΝΟΜΙΣΜΑΤΟΣ ΤΟΥ ΠΑΡΑΣΤΑΤΙΚΟΥ (όχι απαραίτητα CZK) και το null σημαίνει άγνωστο υπόλοιπο. Η λεπτομέρεια περιλαμβάνει επιπλέον τα provider, fetchedAt και evidence: "provider_response".

Υπενθύμιση μέσω Εργασιών

Η μαζική υπενθυμιστική κλήση για ανεξόφλητα τιμολόγια γίνεται μέσω των Εργασιών.

Μια Εργασία τύπου taskType: "invoice" δημιουργείται με source: "integration" και κάθε παραλήπτης (ή ολόκληρη η εργασία, όταν το τιμολόγιο είναι το ίδιο για όλους) φέρει externalRefs.invoice = {connectionId, externalId, provider?} - το connectionId είναι το id της σύνδεσης από το list_integrations, το externalId το id του τιμολογίου από το list_invoices. Χωρίς αυτή την αναφορά το create_task/POST /v1/tasks αποτυγχάνει με σφάλμα validation και μήνυμα recipients.externalRefs και δεν αποθηκεύει καμία εργασία. Αν η υποχρεωτική αναφορά λείπει από μια ήδη υπάρχουσα εγγραφή, το get_task/GET /v1/tasks/{id} την αναφέρει στο issues και το start_task αρνείται να ξεκινήσει την εργασία με το ίδιο σφάλμα επικύρωσης.

Κάθε παραλήπτης φέρει επιπλέον το πεδίο paymentStatus (not_applicable, unknown, unpaid, paid, disputed) - μόνο για ανάγνωση, το σύστημα το εξάγει από την τελευταία ανάγνωση του τιμολογίου στον πάροχο, αμέσως πριν από την κλήση. Χωρίς αναφορά σε τιμολόγιο είναι not_applicable, μετά τη δημιουργία ή όταν η κατάσταση ή το ποσό δεν μπορούν να επαληθευτούν είναι unknown, αλλιώς ακολουθεί την απάντηση του Fakturoid/ABRA - για εξοφλημένο τιμολόγιο η εργασία παραλείπει το στοιχείο (skipped) και ορίζει paid. Την τιμή disputed σήμερα δεν την ορίζει το ίδιο το σύστημα, μόνο η πύλη μπορεί να την εμφανίσει - ανήκει στη δημόσια απαρίθμηση (TaskItem στο /openapi.json) για μελλοντική χειροκίνητη επισήμανση αμφισβητούμενου τιμολογίου.

Σφάλματα

• integration_not_found - Η σύνδεση με αυτό το integrationId δεν υπάρχει ή δεν ανήκει σε αυτόν τον λογαριασμό.
• integration_unsupported - Η σύνδεση δεν είναι σύνδεση τιμολόγησης (για παράδειγμα ημερολόγιο), ή έγινε απόπειρα σύνδεσης του Fakturoid με διαπιστευτήρια αντί για OAuth.
• integration_unauthorized - Το Fakturoid ή το ABRA ανάκαλεσαν την πρόσβαση - η σύνδεση πρέπει να γίνει ξανά στην πύλη.
• integration_provider_error - Ο πάροχος δεν ανταποκρίνεται αυτή τη στιγμή ή επέστρεψε σφάλμα - δοκιμάστε αργότερα και στο μεταξύ θεωρήστε την κατάσταση του τιμολογίου άγνωστη.
• integration_invalid_query - Το ABRA απέρριψε το search με ανάστροφες κάθετους ή μικτά εισαγωγικά - απλοποιήστε το ερώτημα.

Τον πλήρη πίνακα με όλους τους κωδικούς θα βρείτε στην ενότητα τιμολόγια στην αναφορά του REST API και στα σφάλματα MCP.

Ασφάλεια

Ούτε το REST API ούτε το MCP επιστρέφουν ποτέ τα διακριτικά πρόσβασης ή τους κωδικούς για το Fakturoid ή το ABRA Flexi, και τα αποθηκεύουμε κρυπτογραφημένα. Η αποσύνδεση μιας ενσωμάτωσης γίνεται μόνο στην πύλη ή μέσω REST (DELETE /v1/integrations/{id}) - το MCP δεν έχει επίτηδες εργαλείο γι' αυτό, καθώς η ενέργεια είναι μη αναστρέψιμη.