Αποστολή και λήψη τιμολογίων μέσω Peppol

Το Peppol είναι το ευρωπαϊκό δίκτυο ανταλλαγής δομημένων ηλεκτρονικών τιμολογίων μεταξύ επιχειρήσεων και δημόσιων φορέων. Κάθε τιμολόγιο ταξιδεύει από το σημείο πρόσβασης του αποστολέα στο σημείο πρόσβασης του παραλήπτη. Το Nordlet δημιουργεί τιμολόγια και πιστωτικά σημειώματα Peppol BIS Billing 3.0 και τα αποστέλλει και τα λαμβάνει μέσω του λογαριασμού σημείου πρόσβασης της εταιρείας σας.

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

Πάροχος	Αποστολή	Κατάσταση παράδοσης	Λήψη
Recommand	ναι	μέσω webhook και κατόπιν αιτήματος	ναι
Storecove	ναι	αποκλειστικά μέσω webhook	ναι
e-invoice.be	ναι	μέσω webhook και κατόπιν αιτήματος	ναι

Χωρίς σημείο πρόσβασης, το Nordlet εξακολουθεί να δημιουργεί το αρχείο Peppol για κάθε εκδιδόμενο τιμολόγιο και πιστωτικό σημείωμα ώστε να μπορείτε να το κατεβάσετε και να το διαχειριστείτε με άλλον τρόπο, ωστόσο δεν πραγματοποιεί αποστολή ή λήψη.

Τι θα χρειαστείτε

• Έναν λογαριασμό σε έναν από τους παραπάνω παρόχους, με την εταιρεία σας καταχωρισμένη στο Peppol μέσω αυτού. Κάθε πάροχος χρεώνει για την υπηρεσία του, οπότε ανατρέξτε στον τιμοκατάλογό του.
• Στο Nordlet, τον ΑΦΜ ή τον αριθμό μητρώου της εταιρείας, ή το αναγνωριστικό Peppol της (Λογαριασμός → Εταιρείες → Αναγνωριστικό Peppol). Κάθε πελάτης στον οποίο αποστέλλετε πρέπει επίσης να διαθέτει κάποιο από αυτά στην καρτέλα συνεργάτη του.

Σύνδεση του σημείου πρόσβασης

Ανοίξτε την ενότητα Λογαριασμός → Συμμόρφωση → ΕΕ → Σημείο πρόσβασης Peppol, επιλέξτε τον πάροχό σας στο πεδίο Πάροχος, συμπληρώστε τα πεδία για τον συγκεκριμένο πάροχο σύμφωνα με τα παρακάτω και αποθηκεύστε. Αφήστε το πεδίο Διεύθυνση βάσης API (API base URL) κενό, εκτός εάν ο πάροχος σάς έχει δώσει διαφορετική διεύθυνση. Μετά την αποθήκευση, η σελίδα εμφανίζει τη Διεύθυνση URL webhook της εταιρείας σας: https://api.nordlet.com/v1/peppol/webhooks/{provider}/{companyId}, όπου {provider} είναι recommand, storecove ή e-invoice-be και {companyId} είναι το αναγνωριστικό της εταιρείας σας. Κάθε εταιρεία στο Nordlet διαθέτει τη δική της διεύθυνση URL webhook.

Το Nordlet αποδέχεται μια κλήση webhook μόνο όταν επαληθεύεται ότι γνωρίζει το μυστικό webhook (webhook secret) σας, επομένως μια κλήση που δεν προέρχεται από τον λογαριασμό του σημείου πρόσβασης σας απορρίπτεται. Το Nordlet επικοινωνεί αποκλειστικά με διευθύνσεις του δημόσιου διαδικτύου όταν καλεί το σημείο πρόσβασης σας.

Recommand

1. Στο Recommand, ανοίξτε την εταιρεία σας και αντιγράφψτε το αναγνωριστικό εταιρείας στο πεδίο Αναγνωριστικό λογαριασμού στο σημείο πρόσβασης.
2. Στο Recommand, δημιουργήστε ένα κλειδί API (API key) και αντιγράφψτε το κλειδί και το μυστικό του στα πεδία Κλειδί API και Μυστικό API (API secret).
3. Δημιουργήστε ένα μακροσκελές τυχαίο κείμενο που θα γνωρίζετε μόνο εσείς και το Recommand και καταχωρίστε το στο πεδίο Μυστικό webhook. Αποθηκεύστε.
4. Στο Recommand, δημιουργήστε ένα webhook για την εταιρεία σας χρησιμοποιώντας τη διεύθυνση URL webhook που εμφανίζει το Nordlet και το ίδιο μυστικό webhook.

Το Recommand υπογράφει κάθε κλήση webhook με αυτό το μυστικό.

Storecove

1. Στο Storecove, δημιουργήστε μια νομική οντότητα για την εταιρεία σας, ρυθμισμένη για αποστολή και λήψη, και αντιγράφψτε το αναγνωριστικό της στο πεδίο Αναγνωριστικό λογαριασμού στο σημείο πρόσβασης.
2. Στο Storecove, στην ενότητα Κλειδιά API (API Keys), δημιουργήστε ένα κλειδί API και αντιγράφψτε το στο πεδίο Κλειδί API. Αφήστε το πεδίο Μυστικό API (API secret) κενό.
3. Δημιουργήστε ένα μακροσκελές τυχαίο κείμενο και καταχωρίστε το στο πεδίο Μυστικό webhook. Αποθηκεύστε.
4. Στο Storecove, ρυθμίστε ένα webhook προώθησης (push webhook) με τη διεύθυνση URL webhook που εμφανίζει το Nordlet, προστατευμένο με βασικό έλεγχο ταυτότητας HTTP (HTTP Basic authentication): οποιοδήποτε όνομα χρήστη και το μυστικό webhook ως κωδικό πρόσβασης.

Το Storecove δεν διαθέτει κλήση για την κατάσταση ενός απεσταλμένου εγγράφου, επομένως με το Storecove η κατάσταση παράδοσης προέρχεται αποκλειστικά από το webhook του και η σελίδα του τιμολογίου δεν διαθέτει κουμπί Έλεγχος κατάστασης Peppol. Ένας λογαριασμός δοκιμών (sandbox) του Storecove πραγματοποιεί αποστολές στο δίκτυο δοκιμών του Peppol, ενώ τα κλειδιά API παραγωγής παρέχονται από την υποστήριξη του Storecove.

e-invoice.be

1. Στην εφαρμογή e-invoice.be, στην ενότητα Ρυθμίσεις API (API Settings), αντιγράφψτε το κλειδί API της εταιρείας σας στο πεδίο Κλειδί API. Αφήστε τα πεδία Αναγνωριστικό λογαριασμού στο σημείο πρόσβασης και Μυστικό API (API secret) κενά. Αποθηκεύστε.
2. Δημιουργήστε ένα webhook μέσω του API του e-invoice.be (POST https://api.e-invoice.be/api/webhooks/) χρησιμοποιώντας τη διεύθυνση URL webhook που εμφανίζει το Nordlet και τα γεγονότα document.received, document.sent και document.sent.failed.
3. Αντιγράφψτε το secret που επιστρέφει το API για το νέο webhook στο πεδίο Μυστικό webhook στο Nordlet και αποθηκεύστε ξανά.

Το e-invoice.be υπογράφει κάθε κλήση webhook με αυτό το μυστικό. Μια εταιρεία δοκιμών (sandbox) στο e-invoice.be αποστέλλει τα έγγραφα μέσω email αντί να τα στέλνει μέσω του δικτύου Peppol.

Αποστολή τιμολογίου

1. Εκδώστε το τιμολόγιο ή το πιστωτικό σημείωμα.
2. Βεβαιωθείτε ότι ο πελάτης διαθέτει αναγνωριστικό Peppol, ΑΦΜ ή αριθμό μητρώου στην καρτέλα συνεργάτη του.
3. Στη σελίδα του τιμολογίου, στην ενότητα Παράδοση, κάντε κλικ στην επιλογή Αποστολή μέσω Peppol και επιβεβαιώστε. Η ενότητα Παράδοση εμφανίζεται για εκδοθέντα τιμολόγια που δεν έχουν εξοφληθεί ακόμη, ενώ το κουμπί εμφανίζεται μόνο όταν το σημείο πρόσβασης είναι συνδεδεμένο.

Το Nordlet δημιουργεί το αρχείο Peppol και το παραδίδει στο σημείο πρόσβασης σας. Στη συνέχεια, η σελίδα του τιμολογίου εμφανίζει την ενότητα Παράδοση Peppol:

Κατάσταση	Σημασία
pending (εκκρεμεί)	Παραδόθηκε στο σημείο πρόσβασης. Το σημείο πρόσβασης του πελάτη δεν το έχει επιβεβαιώσει ακόμη
delivered (παραδόθηκε)	Το σημείο πρόσβασης του πελάτη επιβεβαίωσε τη λήψη του τιμολογίου
rejected (απορρίφθηκε)	Ο πελάτης απέρριψε το τιμολόγιο. Ο λόγος εμφανίζεται κάτω από την κατάσταση
failed (απέτυχε)	Η παράδοση του τιμολογίου απέτυχε. Ο λόγος εμφανίζεται κάτω από την κατάσταση εφόσον παρέχεται από το σημείο πρόσβασης

Η κατάσταση ενημερώνεται αυτόματα όταν το σημείο πρόσβασης αναφέρει μια αλλαγή μέσω του webhook του. Η επιλογή Έλεγχος κατάστασης Peppol ζητά από το Recommand ή το e-invoice.be την τρέχουσα κατάσταση άμεσα. Στην περίπτωση του e-invoice.be, διαβάζει επίσης την απάντηση του πελάτη στο τιμολόγιο, και μια απόρριψη (κωδικός απάντησης RE) εμφανίζεται ως απορριφθείσα. Ένα απορριφθέν τιμολόγιο ή τιμολόγιο του οποίου η αποστολή απέτυχε μπορεί να αποσταλεί ξανά αφότου διορθώσετε την αιτία. Όταν το σημείο πρόσβασης απορρίπτει ευθέως ένα τιμολόγιο, για παράδειγμα επειδή ο πελάτης δεν είναι εγγεγραμμένος στο Peppol, το Nordlet εμφανίζει την αιτία και το τιμολόγιο παραμένει αναστάλτος.

Το κουμπί Peppol XML στο επάνω μέρος της σελίδας τιμολογίου κατεβάζει το ίδιο αρχείο Peppol χωρίς να το αποστέλλει.

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

Λήψη τιμολογίων

Όταν το σημείο πρόσβασης αναφέρει ένα εισερχόμενο έγγραφο μέσω του webhook του, το Nordlet κατεβάζει το αρχείο Peppol από το σημείο πρόσβασης. Τα τιμολόγια και τα πιστωτικά σημειώματα που λαμβάνει η εταιρεία σας εμφανίζονται στην ενότητα Αγορές → Λήψη εγγράφων, επισημασμένα ως ληφθέντα μέσω Peppol από το αναγνωριστικό Peppol του αποστολέα. Το Nordlet διαβάζει το αρχείο Peppol απευθείας, επομένως η λήψη δεν καταναλώνει μονάδες αναγνώρισης εγγράφων.

1. Ανοίξτε το ληφθέν έγγραφο.
2. Ελέγξτε τον προμηθευτή, τις ημερομηνίες και τις γραμμές. Επιλέξτε τον προμηθευτή από τους συνεργάτες σας ή δημιουργήστε τον.
3. Κάντε κλικ στην επιλογή Αποθήκευση προσχέδιου. Το Nordlet δημιουργεί ένα προσχέδιο τιμολογίου αγοράς, ή ένα προσχέδιο πιστωτικού σημειώματος αγοράς για εισερχόμενο πιστωτικό σημείωμα, με συνημμένο το αρχικό αρχείο Peppol. Καταχωρίστε το όπως ακριβώς θα κάνατε με οποιοδήποτε άλλο τιμολόγιο αγοράς.

Οι γραμμές τιμολογίου αγοράς στο Nordlet δεν μπορούν να είναι αρνητικές. Οι εκπτώσεις και οι επιβαρύνσεις για ολόκληρο το έγγραφο, καθώς και οι αρνητικές γραμμές, κατανέμονται στις γραμμές με τον ίδιο συντελεστή ΦΠΑ. Ένα ποσό που δεν μπορεί να απορροφηθεί από καμία γραμμή του αντίστοιχου συντελεστή ΦΠΑ του, όπως για παράδειγμα ένα επιστραφέν είδους με συντελεστή ΦΠΑ για τον οποίο δεν υπάρχει άλλη γραμμή στο τιμολόγιο, εμφανίζεται σε έναν δεύτερο πίνακα: Γραμμές πιστωτικού σημειώματος για ληφθέν τιμολόγιο, ή Γραμμές τιμολογίου για ληφθέν πιστωτικό σημείωμα. Αυτές οι γραμμές αποθηκεύονται ως δεύτερο έγγραφο για τον ίδιο προμηθευτή: ένα πιστωτικό σημείωμα αγοράς έναντι του νέου τιμολογίου, με αρίθμηση "<αριθμός εγγράφου>-CR", ή ένα τιμολόγιο αγοράς με αρίθμηση "<αριθμός εγγράφου>-INV". Τα δύο έγγραφα μαζί αθροίζουν στα συνολικά ποσά του ληφθέντος εγγράφου.

Έλεγχος εάν ένας πελάτης είναι εγγεγραμμένος στο Peppol

Η κλήση POST /v1/peppol/participants/lookup με την παράμετρο partnerId ή participantId (":") ερωτά το δίκτυο Peppol εάν ο παραλήπτης είναι εγγεγραμμένος και ποia έγγραφα αποδέχεται. Λειτουργεί χωρίς σημείο πρόσβασης.

Εκτέλεση των ίδιων ενεργειών μέσω του API

Εργασία	Κλήση
Σύνδεση του σημείου πρόσβασης	POST /v1/declarations/configs/update με system: "peppol" και το αντικείμενο config να περιέχει provider (recommand, storecove ή e-invoice-be), accountId, apiKey, apiSecret, webhookSecret και προαιρετικά apiBaseUrl
Λήψη του webhook του σημείου πρόσβασης	POST /v1/peppol/webhooks/{provider}/{companyId}, το οποίο καλείται από το σημείο πρόσβασης
Λήψη του αρχείου Peppol	POST /v1/sales/invoices/peppol-xml
Αποστολή	POST /v1/sales/invoices/peppol-send (επιστρέφει 422 χωρίς σημείο πρόσβασης)
Ανάγνωση της κατάστασης παράδοσης	POST /v1/sales/invoices/peppol-status (επιστρέφει 422 με το Storecove). Τα τιμολόγια φέρουν τα πεδία peppolMessageId, peppolStatus, peppolDetail, peppolSentAt, peppolCheckedAt
Εύρεση ληφθέντων εγγράφων	POST /v1/capture/documents/list. Τα ληφθέντα έγγραφα φέρουν provider: "peppol" και senderId
Μετατροπή σε τιμολόγιο αγοράς	POST /v1/capture/documents/confirm, με την παράμετρο oppositeLines για το δεύτερο έγγραφο

Γεγονότα webhook: sale_invoice.peppol_sent, sale_invoice.peppol_delivered, sale_invoice.peppol_rejected, sale_invoice.peppol_failed και document_capture.peppol_received. Ανατρέξτε στις Συμβάσεις API για πληροφορίες σχετικά με τα σφάλματα, την ταυτοδυναμία (idempotency) και τα webhooks.

FAQ

• Τι συμβαίνει εάν αλλάξω πάροχο σημείου πρόσβασης; Ενημερώστε τις ρυθμίσεις στο Nordlet με τα στοιχεία του νέου παρόχου και ρυθμίστε εκ νέου τη διεύθυνση URL webhook στον νέο πάροχο. Τα παλαιότερα μηνύματα διατηρούν την ιστορικότητά τους.
• Μπορώ να στείλω τιμολόγια σε πελάτες εκτός Ευρώπης μέσω Peppol; Το δίκτυο Peppol επεκτείνεται διεθνώς (π.χ. Σιγκαπούρη, Ιαπωνία, Αυστραλία, Νέα Ζηλανδία), αρκεί ο παραλήπτης να είναι καταχωρισμένος στο δίκτυο Peppol και να υποστηρίζει τον αντίστοιχο τύπο εγγράφου.