Περιγραφή κλήσεων REST API και χαρακτηριστικά τους

Συνοπτικά, η διεπαφή παρέχει τις εξής λειτουργίες-μεθόδους: 

• /RegisterTransfer: διαδικασία δήλωσης έναρξης ή μεταφόρτωσης διακίνησης από μεταφορέα. 
• /ConfirmDeliveryOutcome: διαδικασία δήλωσης αποτελέσματος παράδοσης από μεταφορέα ή λήπτη. 
•  /RejectDeliveryNote: διαδικασία ολικής απόρριψης διακίνησης από τον λήπτη. 
• /GetDeliveryNoteStatus: διαδικασία λήψης της κατάστασης και του ιστορικού ενός Δελτίου Αποστολής. 
• /GenerateGroupQRCode: διαδικασία δημιουργίας ομαδικού QR Code για πολλαπλά Δελτία Αποστολής.

/RegisterTransfer:

1. Η μέθοδος καλείται από τον μεταφορέα για να δηλώσει την παραλαβή των αγαθών και την έναρξη της διακίνησης, ή την παραλαβή από προηγούμενο μεταφορέα (μεταφόρτωση). 

2. Με την επιτυχή κλήση, το Δελτίο Αποστολής μεταβαίνει σε κατάσταση InTransit. 

3. Σε περίπτωση επιτυχίας, η απόκριση περιέχει το transportMark, το οποίο είναι ο Μοναδικός Αριθμός Καταχώρησης του γεγονότος μεταφοράς.

/ConfirmDeliveryOutcome:

1. Η μέθοδος καλείται είτε από τον Μεταφορέα για να δηλώσει το αποτέλεσμα της παράδοσης, είτε από τον Λήπτη για να επιβεβαιώσει την παραλαβή. 

2. Αν κληθεί από Μεταφορέα σε B2B συναλλαγή, θέτει το ΔΑ σε κατάσταση DeliveredByCarrier.

3. Αν κληθεί από Μεταφορέα σε B2C συναλλαγή, θέτει το ΔΑ σε κατάσταση Completed. 

4. Αν κληθεί από Λήπτη, θέτει το ΔΑ σε κατάσταση Completed. 

5. Η τιμή NONE για το πεδίο outcome θέτει το ΔΑ σε κατάσταση FailedDelivery.

/RejectDeliveryNote:

1. Η μέθοδος καλείται αποκλειστικά από τον Λήπτη για να δηλώσει την ολική απόρριψη των ειδών του Δελτίου Αποστολής. 

2. Με την επιτυχή κλήση, το Δελτίο Αποστολής μεταβαίνει στην τελική κατάσταση Rejected.

3. Σε περίπτωση επιτυχίας, η απόκριση περιέχει το rejectMark, το οποίο είναι ο Μοναδικός Αριθμός Καταχώρησης του γεγονότος απόρριψης.

/GetDeliveryNoteStatus: 

1. Η μέθοδος επιστρέφει ένα αντικείμενο DeliveryNoteStatusResponse που περιέχει την τρέχουσα κατάσταση (status) και το ιστορικό (lifecycleHistory). 
Η δομή του στοιχείου DeliveryNoteStatusResponse στην περίπτωση που ο χρήστης χρησιμοποιήσει τη μέθοδο GetDeliveryNoteStatus θα λαμβάνει ως απάντηση ένα αντικείμενο DeliveryNoteStatusResponse σε xml μορφή.  Η δομή του είναι περιλαμβάνει τα εξής πεδία:

 2. Η κλήση επιτρέπεται στον εκδότη, τον λήπτη και σε οποιονδήποτε μεταφορέα συμμετείχε στη διακίνηση.

GenerateGroupQRCode:

1. Η μέθοδος μπορεί να κληθεί από οποιονδήποτε εξουσιοδοτημένο χρήστη (εκδότη ή μεταφορέα). 

2. Απαιτούνται τουλάχιστον 2 qrUrl για τη δημιουργία ομάδας. 

3. Η απόκριση περιέχει το groupQrUrl, το οποίο μπορεί να χρησιμοποιηθεί στις μεθόδους RegisterTransfer, ConfirmDeliveryOutcome και RejectDeliveryNote για την ταυτόχρονη ενημέρωση όλων των ΔΑ της ομάδας. 

4. Το groupQrUrl έχει περιορισμένη διάρκεια ισχύος, η οποία επιστρέφεται στο πεδίο expiresAt.

Συνοπτικά οι ρόλοι διακίνησης είναι οι εξής:

• Εκδότης (Issuer): Η οντότητα που εκδίδει το παραστατικό διακίνησης. 
• Μεταφορέας (Carrier): Η οντότητα που αναλαμβάνει τη φυσική μεταφορά των αγαθών. Μπορεί να υπάρχουν πολλοί μεταφορείς σε μία διακίνηση (μεταφόρτωση). 
• Λήπτης (Recipient): Η οντότητα που είναι ο τελικός παραλήπτης των αγαθών.