Added more docs

docs/cancel-invoice.md

@@ -5,4 +5,67 @@ prev: send-payments-method|SendPaymentsMethod
 next: request-docs|RequestDocs
 ---
 
-# Ακύρωση παραστατικού
+# Ακύρωση παραστατικού
+
+Για την ακύρωση ενός παραστατικού στο σύστημα του ΑΑΔΕ myDATA, χρησιμοποιήστε την κλάση `Firebed\AadeMyData\Http\CancelInvoice`.
+Η ακύρωση παραστατικού γίνεται παρέχοντας το mark του παραστατικού που θέλουμε να ακυρώσουμε.
+
+```php
+use Firebed\AadeMyData\Http\CancelInvoice;
+
+$cancel = new CancelInvoice();
+$cancel->handle("1234567890");
+```
+
+Για την περίπτωση εκείνη και μόνο που η μέθοδος κληθεί από τρίτο πρόσωπο (όπως εκπρόσωπος Ν.Π. ή λογιστής), 
+ο ΑΦΜ της οντότητας που εξέδωσε το προς ακύρωση παραστατικό αποστέλλεται μέσω της παραμέτρου entityVatNumber,
+διαφορετικά η εν λόγω παράμετρος δε χρειάζεται να αποσταλεί.
+
+```php
+use Firebed\AadeMyData\Http\CancelInvoice;
+
+$cancel = new CancelInvoice();
+$cancel->handle(mark: "1234567890", entityVatNumber: "888888888");
+```
+
+> [!NOTE]
+> Δεν υπάρχει δυνατότητα ακύρωσης πολλαπλών παραστατικών ταυτόχρονα.
+
+## Λήψη αποτελεσμάτων
+Σε περίπτωση επιτυχίας η ακύρωση ως πράξη λαμβάνει το δικό της mark το οποίο
+επιστρέφεται στον χρήστη και το παραστατικό θεωρείται ακυρωμένο. Σε περίπτωση
+αποτυχίας επιστρέφεται το αντίστοιχο μήνυμα λάθους.
+
+```php
+use Firebed\AadeMyData\Http\CancelInvoice;
+use Firebed\AadeMyData\Exceptions\MyDataException;
+
+try {
+    $cancel = new CancelInvoice();
+    $responses = $cancel->handle("1234567890");
+
+    $response = $responses->first();
+
+    if ($response->isSuccessful()) {
+        echo "Το παραστατικό ακυρώθηκε με επιτυχία." . PHP_EOL;
+        echo "Το mark ακύρωσης του παραστατικού είναι: " . $response->getCancellationMark();
+    } else {
+        echo "Η ακύρωση απέτυχε. Λόγος: " . $response->getMessage();
+    }
+} catch (MyDataException $e) {
+    echo "Σφάλμα επικοινωνίας: " . $e->getMessage();
+}
+```
+
+Παρόλο που η ακύρωση γίνεται πάντα για 1 παραστατικό το αποτέλεσμα επιστρέφεται ως πίνακας αποτελεσμάτων.
+Αυτό γίνεται για να είναι συμβατό με τις υπόλοιπες μεθόδους που επιστρέφουν πολλαπλά αποτελέσματα.
+Στην πράξη, ο πίνακας αποτελεσμάτων θα περιέχει μόνο 1 στοιχείο και μπορείτε να έχετε πρόσβαση σ' αυτό
+μέσω:
+- `$responses->first()` όπως στο παραπάνω παράδειγμα
+- `$responses[0]`
+- `$responses->getOffset(0)`
+- foreach loop
+
+> [!TIP]
+> Παράλληλα, μετά από επιτυχή ακύρωση, στα αποτελέσματα του [RequestTransmittedDocs](request-transmitted-docs)
+> καλώντας τη μέθοδος `getCancelledInvoices()` θα μας επιστρέφεται και το ακυρωμένο που μόλις ακυρώσαμε.

docs/getting-started.md

@@ -6,7 +6,6 @@ next: installation|Εγκατάσταση
 
 # ΑΑΔΕ myDATA REST API
 
-## 
 Το invoicemaker.gr παρέχει μια εκφραστική, ευέλικτη διεπαφή που έχει αναπτυχθεί με τη χρήση της γλώσσας **PHP** για την επικοινωνία με την εφαρμογή myDATA της Ανεξάρτητης Αρχής Δημοσίων Εσόδων (ΑΑΔΕ).
 Παρέχει μια εύκολη και γρήγορη λύση για την αποστολή και λήψη παραστατικών, ακύρωση παραστατικών, χαρακτηρισμός και λήψη εσόδων και εξόδων και λήψη αναφορών ΦΠΑ.
 
@@ -15,6 +14,7 @@ next: installation|Εγκατάσταση
 
 Το invoicemaker.gr απευθύνεται επίσης στους προγραμματιστές (developers) που θέλουν να ενσωματώσουν την υποστήριξη του myDATA στις εφαρμογές τους εντελώς δωρεάν.
 
+> [!NOTE]
 > Αν είστε ελεύθερος επαγγελματίας ή επιχείρηση και θέλετε να αποστέλλετε τιμολόγια στο myDATA, μπορείτε να εγγραφείτε στο invoicemaker.gr και να ξεκινήσετε αμέσως.
 >
 > <a class='button' href='https://www.invoicemaker.gr'>Δείτε περισσότερα</a>

docs/installation.md

@@ -7,7 +7,7 @@ next: send-invoices|Send Invoices
 
 # Εγκατάσταση
 
-## <a href="#composer">Εγκατάσταση μέσω του Composer</a>
+## Εγκατάσταση μέσω του Composer
 Για εγκατάσταση μέσω του Composer, εκτελέστε την ακόλουθη εντολή:
 ```shell
 composer require firebed/aade-mydata
@@ -50,12 +50,16 @@ $subscription_key = "your-subscription-key";
 
 MyDataRequest::setEnvironment($env);
 MyDataRequest::setCredentials($user_id, $subscription_key);
+```
+
+Ή εναλλακτικά, μπορείτε να ορίσετε το περιβάλλον και τα διαπιστευτήρια μέσω της μεθόδου `init`:
 
-// Alternative
-//MyDataRequest::init($user_id, $subscription_key, $env);
+```php
+MyDataRequest::init($user_id, $subscription_key, $env);
 ```
 
 Για το στάδιο της ανάπτυξη, μπορεί να χρειαστεί να απενεργοποιήσετε την επαλήθευση πελάτη εάν δεν χρησιμοποιείτε ***https***:
+
 ```php
 MyDataRequest::verifyClient(false);
 ```

docs/send-invoices.md

@@ -17,10 +17,11 @@ next: send-income-classification|SendIncomeClassification
 - είτε ένα αντικείμενο `Firebed\AadeMyData\Models\Invoice` 
 - είτε έναν πίνακα από αντικείμενα `Firebed\AadeMyData\Models\Invoice`.
 
-> ### Σημείωση
+> [!NOTE]
 > Στα παρακάτω παραδείγματα δημιουργούμε κενά αντικείμενα `Firebed\AadeMyData\Models\Invoice` για χάριν συντομίας. Κανονικά θα πρέπει να 
 συμπληρώσουμε όλα τα απαραίτητα πεδία του παραστατικού πριν την αποστολή του.
-> [**Δείτε περισσότερα**](/types/invoice-type)
+> 
+> [**Δείτε περισσότερα**](types/invoice-type)
 
 ### Αποστολή ενός μόνο παραστατικού
 
@@ -30,10 +31,16 @@ next: send-income-classification|SendIncomeClassification
 use Firebed\AadeMyData\Http\SendInvoices;
 use Firebed\AadeMyData\Models\InvoicesDoc;
 use Firebed\AadeMyData\Models\Invoice;
+use Firebed\AadeMyData\Exceptions\MyDataException;
 
 $invoice = new Invoice();
 $request = new SendInvoices();
-$response = $request->handle($invoice);
+
+try {
+    $response = $request->handle($invoice);
+} catch (MyDataException $e) {
+    echo "Σφάλμα επικοινωνίας: " . $e->getMessage();
+}
 ```
 
 ### Αποστολή πολλών παραστατικών με τη χρήση πίνακα αντικειμένων `Invoice`
@@ -45,8 +52,13 @@ $response = $request->handle($invoice);
 $invoice1 = new Invoice();
 $invoice2 = new Invoice();
 $invoice3 = new Invoice();
-$request = new SendInvoices();
-$response = $request->handle([$invoice1, $invoice2, $invoice3]);
+
+$request = new SendInvoices();    
+try {
+    $response = $request->handle([$invoice1, $invoice2, $invoice3]);
+} catch (MyDataException $e) {
+    echo "Σφάλμα επικοινωνίας: " . $e->getMessage();
+}
 ```
 
 ### Αποστολή πολλών παραστατικών με τη χρήση ενός αντικειμένου `InvoicesDoc`
@@ -66,9 +78,19 @@ $response = $request->handle($doc);
 // Alternatively
 $doc = new InvoicesDoc([new Invoice(), new Invoice()]);
 $request = new SendInvoices();
-$response = $request->handle($doc);
+
+try {
+    $response = $request->handle($doc);
+} catch (MyDataException $e) {
+    echo "Σφάλμα επικοινωνίας: " . $e->getMessage();
+}
 ```
 
+> [!NOTE]
+> Στην περίπτωση που η αποστολή παραστατικών αποτύχει λόγω σφάλματος επικοινωνίας, 
+> η εξαίρεση `Firebed\AadeMyData\Exceptions\MyDataException` θα περιέχει το μήνυμα λάθους.
+> Σε τέτοιες περιπτώσεις **κανένα παραστατικό** δε θα διαβιβαστεί στο σύστημα του ΑΑΔΕ myDATA.
+
 ## Λήψη αποτελεσμάτων
 
 Το αποτέλεσμα της αποστολής παραστατικών είναι ένα αντικείμενο `Firebed\AadeMyData\Models\ResponseDoc` το οποίο περιέχει τόσα αντικείμενα
@@ -81,4 +103,51 @@ $response = $request->handle($doc);
 Το πεδίο `status` περιέχει το αποτέλεσμα της αποστολής του παραστατικού. Αν το πεδίο `status` είναι `Success` τότε η αποστολή ήταν επιτυχής.
 Διαφορετικά, στην περίπτωση αποτυχίας, η αποστολή θα περιέχει επίσης και το πεδίο `message` για το μήνυμα λάθους.
 
-```php
+```php
+use Firebed\AadeMyData\Http\SendInvoices;
+use Firebed\AadeMyData\Models\Invoice;
+use Firebed\AadeMyData\Exceptions\MyDataException;
+
+// Create the request and send 2 invoices
+$invoicesToBeSent = [new Invoice(), new Invoice()];
+$sendInvoices = new SendInvoices();
+
+try {
+    $responses = $sendInvoices->handle($invoicesToBeSent);
+
+    $errors = [];
+    foreach ($responses as $response) {
+        if ($response->isSuccessful()) { // $response->getStatusCode() === 'Success';   
+            // This invoice was successfully registered.     
+            // Each response has an index value which corresponds
+            // to the index (-1) of the $invoicesToBeSent array.
+
+            $index = $response->getIndex(); // $sentInvoice = $invoicesToBeSent[$index - 1];
+            $uid = $response->getInvoiceUid();
+            $mark = $response->getInvoiceMark();
+            $cancelledByMark = $response->getCancellationMark();
+            $qrUrl = $response->getQrUrl();
+
+            // Typically, you should have an invoice object of your
+            // own and an invoice reference from myDATA, and you
+            // will have to relate these together. 
+            // Retrieve the invoice's uid, mark, qr and other values
+            // from the response, then establish the correlation
+            // with your local invoice and persist these details in your database.
+            print_r(compact('index', 'uid', 'mark', 'cancelledByMark', 'qrUrl'));
+        } else {
+            // There were some errors for this specific invoice. See errors for details.
+            foreach ($response->getErrors() as $error) {
+                $errors[$response->getIndex()][] = $error->getCode() . ': ' . $error->getMessage();
+            }
+        }
+    }
+} catch (MyDataException $e) {
+    // There was a communication error. None of the invoices were sent.
+    echo "Σφάλμα επικοινωνίας: " . $e->getMessage();
+}
+```
+
+> [!CAUTION]
+> **Στην περίπτωση διαβίβασης πολλαπλών παραστατικών ταυτόχρονα, θα πρέπει να ελέγξουμε το αποτέλεσμα της αποστολής κάθε παραστατικού ξεχωριστά.
+> Υπάρχει περίπτωση να έχουμε επιτυχία σε ένα παραστατικό και αποτυχία σε ένα άλλο.**

src/Models/Invoice.php

@@ -156,7 +156,7 @@ public function addPaymentMethod(PaymentMethodDetail $paymentMethodDetail): void
     {
         $paymentMethods = $this->getPaymentMethods();
         if ($paymentMethods) {
-            $paymentMethods->push($paymentMethodDetail);
+            $paymentMethods->add($paymentMethodDetail);
         } else {
             $this->set('paymentMethods', new PaymentMethods($paymentMethodDetail));
         }
@@ -231,7 +231,7 @@ public function getTaxesTotals(): ?TaxesTotals
     public function addTaxesTotals(TaxTotals $taxTotals): void
     {
         $taxesTotals = $this->getTaxesTotals();
-        $taxesTotals->addTaxes($taxTotals);
+        $taxesTotals->add($taxTotals);
         $this->set('taxesTotals', $taxesTotals);
     }
 

src/Models/TypeArray.php

@@ -50,6 +50,14 @@ public function add($value): void
     {
         $this->push($this->childKey, $value);
     }
+
+    /**
+     * @return ?TType
+     */
+    public function first()
+    {
+        return $this->offsetGet(0);
+    }
 
     /**
      * @param int $key

tests/Http/CancelInvoiceTest.php

@@ -24,5 +24,7 @@ public function test_invoice_is_cancelled()
 
         $this->assertCount(1, $responseDoc);
         $this->assertEquals('Success', $responseDoc[0]->getStatusCode());
+        $this->assertEquals('Success', $responseDoc->offsetGet(0)->getStatusCode());
+        $this->assertEquals('Success', $responseDoc->first()->getStatusCode());
     }
 }